116 lines
3.8 KiB
Markdown
116 lines
3.8 KiB
Markdown
# 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
|