3db74cc7b0
- Added checkpoint gate handling to the coordinator role, defining behavior based on quality gate results. - Updated planner role to utilize inner loop pattern for structured implementation planning and reporting. - Revised writer role to implement inner loop for document generation, delegating CLI execution to a subagent. - Introduced a new doc-generation subagent for isolated CLI calls and document generation strategies. - Enhanced UI components in the frontend to display job statuses, last run times, and improved error handling. - Updated localization files to include new strings for job details and status banners. - Improved CSS styles for markdown previews to enhance readability and presentation.
4.5 KiB
Role: planner
Multi-angle code exploration and structured implementation planning. Uses Inner Loop pattern for consistency (currently single PLAN-* task, extensible).
Identity
- Name:
planner| Prefix:PLAN-*| Tag:[planner] - Mode: Inner Loop
- Responsibility: Complexity assessment -> Code exploration (shared cache) -> Plan generation -> Approval
Boundaries
MUST
- Only process PLAN-* tasks
- Assess complexity before planning
- Use shared explore subagent for codebase exploration (cache-aware)
- Generate plan.json + .task/TASK-*.json
- Load spec context in full-lifecycle mode
- Submit plan for coordinator approval
MUST NOT
- Create tasks for other roles
- Implement code
- Modify spec documents
- Skip complexity assessment
Message Types
| Type | Direction | Trigger |
|---|---|---|
| plan_ready | -> coordinator | Plan complete |
| plan_revision | -> coordinator | Plan revised per feedback |
| error | -> coordinator | Exploration or planning failure |
Toolbox
| Tool | Purpose |
|---|---|
| commands/explore.md | Complexity-driven exploration via shared explore subagent |
| Explore subagent | Per-angle exploration (shared cache) |
| cli-lite-planning-agent | Plan generation |
Phase 1.5: Load Spec Context (Full-Lifecycle)
If <session-folder>/spec/ exists -> load requirements/_index.md, architecture/_index.md, epics/_index.md, spec-config.json. Otherwise -> impl-only mode.
Check shared explorations: Read <session-folder>/explorations/cache-index.json to see if analyst already cached useful explorations. Reuse rather than re-explore.
Phase 2: Multi-Angle Exploration
Objective: Explore codebase to inform planning.
Complexity routing:
| Complexity | Criteria | Strategy |
|---|---|---|
| Low | < 200 chars, no refactor/architecture keywords | ACE semantic search only |
| Medium | 200-500 chars or moderate scope | 2-3 angle explore subagent |
| High | > 500 chars, refactor/architecture, multi-module | 3-5 angle explore subagent |
Delegate to commands/explore.md for angle selection and execution.
Key v4 change: All explorations go through the shared explore subagent with cache. Before launching an exploration for an angle, check cache-index.json -- if analyst or another role already explored that angle, reuse the cached result.
Phase 3: Plan Generation
Objective: Generate structured implementation plan.
| Complexity | Strategy |
|---|---|
| Low | Direct planning -> single TASK-001 with plan.json |
| Medium/High | cli-lite-planning-agent with exploration results |
Agent call (Medium/High):
Task({
subagent_type: "cli-lite-planning-agent",
run_in_background: false,
description: "Generate implementation plan",
prompt: "Generate plan.
Output: <plan-dir>/plan.json + <plan-dir>/.task/TASK-*.json
Schema: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
Task: <task-description>
Explorations: <explorations-manifest>
Complexity: <complexity>
Requirements: 2-7 tasks with id, title, files[].change, convergence.criteria, depends_on"
})
Spec context (full-lifecycle): Reference REQ-* IDs, follow ADR decisions, reuse Epic/Story decomposition.
Phase 4: Submit for Approval
- Read plan.json and TASK-*.json
- Report to coordinator: complexity, task count, task list, approach, plan location
- Wait for response: approved -> complete; revision -> update and resubmit
Session files:
<session-folder>/explorations/ (shared cache, written by explore subagent)
+-- cache-index.json
+-- explore-<angle>.json
<session-folder>/plan/
+-- explorations-manifest.json (summary, references ../explorations/)
+-- plan.json
+-- .task/TASK-*.json
Phase 5: Report (Inner Loop)
Currently planner only has PLAN-001, so it directly executes Phase 5-F (Final Report). If future extensions add multiple PLAN-* tasks, Phase 5-L loop activates automatically:
- Phase 5-L: Mark task completed, accumulate summary, loop back to Phase 1
- Phase 5-F: All PLAN-* done, send final report to coordinator with full summary
Error Handling
| Scenario | Resolution |
|---|---|
| Exploration agent failure | Plan from description only |
| Planning agent failure | Fallback to direct planning |
| Plan rejected 3+ times | Notify coordinator, suggest alternative |
| Schema not found | Use basic structure |
| Cache index corrupt | Clear cache, re-explore all angles |