3.8 KiB
Delegation Context Rules
When dispatching any subagent via the Manager Surface, context must be passed explicitly. Subagents do not automatically inherit the parent's working directory or plan state.
Mandatory Context Fields
Every subagent dispatch MUST include:
| Field | Value | Purpose |
|---|---|---|
| Work Context Path | Git root or CWD of primary files | Anchors all relative paths |
| Reports Path | {work_context}/plans/reports/ |
Where subagent writes its report |
| Plans Path | {work_context}/plans/ |
Where plans are located |
Example dispatch prompt:
Fix the authentication bug in the login module.
Work context: /home/user/projects/my-app
Reports: /home/user/projects/my-app/plans/reports/
Plans: /home/user/projects/my-app/plans/
CWD vs Work Context
The most common delegation mistake: using your current working directory when the work is in a different project.
Scenario: Orchestrator is running from /home/user/orchestrator/, editing files in /home/user/projects/my-app/.
WRONG: Reports → /home/user/orchestrator/plans/reports/
RIGHT: Reports → /home/user/projects/my-app/plans/reports/
Rule: Always use the work context paths (where the files live), not CWD paths.
Active Plan Passing
If an active plan exists, include it in the subagent dispatch:
Implement phase-02 of the authentication plan.
Plan file: /home/user/projects/my-app/plans/260101-1200-auth/phase-02-api.md
Work context: /home/user/projects/my-app
Reports: /home/user/projects/my-app/plans/260101-1200-auth/reports/
Plans: /home/user/projects/my-app/plans/
Note: when an active plan exists, reports go to the plan-specific reports folder, not the default plans/reports/.
Agent-Type Specific Context
Some agents need additional context beyond the standard fields:
ck-planning dispatch
Research these topics and create an implementation plan.
Research reports available:
- /path/to/reports/researcher-260101-1200-auth-patterns.md
- /path/to/reports/researcher-260101-1200-jwt-tradeoffs.md
Work context: /path/to/project
Reports: /path/to/project/plans/reports/
Plans: /path/to/project/plans/
Naming format: {date}-{slug}
ck-code-review dispatch
Review changes from the authentication implementation.
Plan file reviewed: /path/to/plan/phase-02-api.md
Base SHA: abc1234
Head SHA: def5678
Changed files: [list]
Work context: /path/to/project
Reports: /path/to/project/plans/reports/
ck-web-testing dispatch
Run the test suite and analyze results.
Recent changes: [list of modified files]
Test commands: npm test, npm run test:coverage
Work context: /path/to/project
Reports: /path/to/project/plans/reports/
Subagent Context Injection (Automatic)
ck-session-guard automatically injects a compact context block into every dispatched agent (~200 tokens). This includes plan path, reports path, naming pattern, and core rules.
However, this automatic injection uses the session's active plan — not necessarily the plan you want the subagent to work on. Always pass explicit context in the dispatch prompt to override or supplement.
Naming Pattern Propagation
Subagents must write reports using the naming pattern from their injected ## Naming section. Never hardcode dates — use the computed pattern:
Report: {reports-path}/ck-code-review-{name-pattern}.md
Where {name-pattern} = computed date + optional issue ID, with {slug} as the only remaining placeholder.
Anti-Patterns
- Omitting work context: Subagent defaults to its own CWD, which may be wrong
- Relative paths: Always use absolute paths in delegation prompts
- Assuming plan propagation: Active plan in session ≠ plan the subagent should use; pass explicitly
- Stale reports path: If plan was just created, update reports path to plan-specific folder