Comprehensive investigation of OpenClaw-native alternatives to the
file-read-network pattern in dispatch.ts that triggers security audits.
Key Findings:
- Bootstrap hooks are the recommended solution
- Purpose-built for dynamic workspace file injection
- Plugin-only implementation (no core changes needed)
- Eliminates audit false positive
Deliverables:
- Full research document with pros/cons analysis
- PoC code demonstrating implementation approach
- Migration checklist and testing plan
- Decision matrix comparing alternatives
Recommendation: Implement agent:bootstrap hook to inject role
instructions at system prompt construction time instead of appending
to task message payload.
Addresses issue #181
## Changes
### lib/templates.ts (AGENTS.md template)
- Added 'Critical: You Do NOT Write Code' section to orchestrator instructions
- Listed what orchestrator CAN do (planning, analysis, status checks)
- Listed what MUST go through workers (code, git ops, tests)
- Added 'Never write code yourself' to Safety section
### README.md
- Added 'The orchestrator's role' section explaining the workflow boundary
- Table showing what goes through workers vs orchestrator
- Explained why: audit trail, tier selection, parallelization, QA pipeline
### docs/ARCHITECTURE.md
- Updated scope boundaries diagram to show 'planning only' for orchestrator
- Added key boundary note about planner/dispatcher role
Addresses issue #133
Auto-chaining was removed from the codebase. All docs now describe the
scheduling model: work_finish transitions labels, the heartbeat's tick
pass (which also fires immediately after every work_finish) detects
available work and fills free slots. Removed autoChain config references.
Files updated: README.md, README2.md, docs/TOOLS.md, ARCHITECTURE.md,
ROADMAP.md, MANAGEMENT.md, ONBOARDING.md, lib/templates.ts
https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
- Add "Why DevClaw" paragraph explaining the gap between raw OpenClaw and development orchestration
- Rename "Shared sessions" to "Session re-use (context preservation)" in token savings
- Add "External task state" benefit covering GitHub/GitLab integration and pluggable IssueProvider
- Simplify installation to conversational onboarding with full example dialogue
- Move "How it works" and "Session reuse" diagrams to ARCHITECTURE.md (keep reference)
- Add Architecture section with link to detailed technical documentation
- Explain tools as guardrails that encode operations as deterministic code
https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
Complete documentation rewrite to match the current codebase:
- README: add benefits section (process consistency, token savings with
estimates, project isolation, continuous planning, feedback loops,
role-based prompts, atomic operations, audit trail), task workflow
with state diagram, model-to-role mapping tables, installation guide
- New TOOLS.md: complete reference for all 11 tools with parameters,
behavior, and execution guards
- New CONFIGURATION.md: full config reference for openclaw.json,
projects.json, heartbeat, notifications, workspace layout
- Fix tool names across all docs: task_pickup→work_start,
task_complete→work_finish
- Fix tier model: QA has reviewer/tester levels, not flat "qa"
- Fix config schema: nested models.dev.*/models.qa.* structure
- Fix prompt path: projects/roles/ not projects/prompts/
- Fix worker state: uses "level" field not "model"/"tier"
- Fix MANAGEMENT.md: remove incorrect model references
- Fix TESTING.md: update model config example to nested structure
- Remove VERIFICATION.md (one-off checklist, no longer needed)
- Add cross-references between all docs pages
https://claude.ai/code/session_01R3rGevPY748gP4uK2ggYag
Added comprehensive QA workflow documentation explaining:
- Required steps for QA reviews
- Mandatory task_comment before task_complete
- Comment templates for pass/fail scenarios
- Rationale for enforcement (audit trail, knowledge sharing, etc.)
- Best practices for QA documentation
This documentation supports the QA comment enforcement
introduced in role templates.
Related to issue #103
- Add context-guard.ts to detect interaction context (via-agent, direct, group) and generate guardrails.
- Introduce onboarding.ts for conversational onboarding context templates and workspace file checks.
- Enhance setup.ts to support new agent creation with channel binding and migration of existing bindings.
- Create analyze-channel-bindings.ts to analyze channel availability and detect binding conflicts.
- Implement context-test.ts for debugging context detection.
- Develop devclaw_onboard.ts for explicit onboarding tool that guides users through setup.
- Update devclaw_setup.ts to include channel binding and migration support in setup process.
- Modify project-register.ts to enforce project registration from group context and auto-populate group ID.
- Enhance queue-status.ts to provide context-aware status checks and recommendations.
- Update task tools (task-complete, task-create, task-pickup) to clarify group ID usage for Telegram/WhatsApp.
- Replaced raw model aliases with developer tiers (junior, medior, senior, qa) in dispatch and model selection logic.
- Updated `dispatchTask` to resolve models based on tiers and plugin configuration.
- Modified `selectModel` to return tier names instead of model aliases based on task description.
- Implemented migration logic for transitioning from old model aliases to new tier names in worker state.
- Added setup logic for agent creation and model configuration in `setup.ts`.
- Created shared templates for workspace files and instructions for DEV/QA workers.
- Enhanced project registration to scaffold role files based on developer tiers.
- Updated task management tools to reflect changes in model selection and tier assignment.
- Introduced a new `devclaw_setup` tool for agent-driven setup and configuration.
- Updated plugin configuration schema to support model mapping per developer tier.
- Add GitLabProvider class for handling issue operations, label management, and MR checks.
- Implement methods for ensuring labels, creating issues, listing issues by label, and transitioning labels.
- Introduce a provider factory to auto-detect GitLab or GitHub based on the repository URL.
- Create project registration tool to validate repositories, create state labels, and log project entries.
- Enhance queue status and session health tools to support new session management features.
- Update task completion and task creation tools to support auto-chaining and improved session handling.
- Refactor task pickup tool to streamline model selection and session management.
- Session-per-model: each project keeps separate sessions per model per role
(haiku/sonnet/opus for DEV, grok for QA) instead of switching models
- Plugin-controlled lifecycle: sessions managed via Gateway RPC (sessions.patch)
and CLI (openclaw agent), not agent instructions
- New end-to-end flow diagram: human → Telegram → main session → plugin → gateway → sub-agent
- Session reuse diagram showing spawn vs send path
- Updated system overview with Gateway as explicit component
- Updated data flow map with new projects.json sessions schema
- Session spawn/send moved to "DevClaw controls" in scope boundaries
- Added session_health using sessions.list gateway RPC
- Added session transcripts to file locations table
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add "Agents vs Sessions" explainer section to ARCHITECTURE.md
- Replace all "PM Agent" references with "Orchestrator" in sequence diagrams
- Fix ticket creation: agents create issues via glab, not humans
- Update scope boundaries to show sub-agent session responsibilities
- Clarify plugin returns instructions, agent executes session operations
- Update ONBOARDING.md issue creation to show agent-first workflow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
