| name | plan-execution |
| description | How to read and execute feature plans from the imas-codex plans/ directory. Use when implementing features from plan documents or when the fleet orchestrator dispatches work. |
Executing Feature Plans
Plan Locations
| Location | Purpose |
|---|
plans/features/*.md | Active plans (unstarted or in-progress) |
plans/features/pending/*.md | Partially implemented (gaps documented in parent dir) |
plans/features/gaps-*.md | Consolidated remaining work from related plans |
Plan Structure
Plans typically contain:
- Executive Summary — what and why
- Phases — ordered implementation steps
- Per-phase details — files to modify, test cases, acceptance criteria
- Dependencies — what must exist before a phase can start
- Documentation Updates — what docs to update when complete
Execution Workflow
- Read the full plan to understand scope and dependencies
- Identify which phases/tasks are ready (dependencies met)
- For each task:
a. Read the specific section carefully
b. Note the listed files, test cases, and acceptance criteria
c. Implement changes
d. Run specified tests
e. Verify acceptance criteria
- After completing a phase, run the full test suite
- Commit with conventional commit message (no plan phase references in title)
Task Decomposition
When breaking a plan into tasks:
- One task per phase subsection (e.g., "1a", "1b", "2a")
- Respect phase ordering — later phases may depend on earlier ones
- Identify parallel tasks — items marked "independent" or "can be implemented in parallel"
- Check for shared infrastructure — multiple tasks may need a common utility first
Complexity Assessment
A task is straightforward (→ @engineer agent) when:
- The plan specifies exact file paths and changes
- Changes are isolated to 1-3 files
- Test cases are provided in the plan
- It follows an established pattern in the codebase
A task is complex (→ @architect agent) when:
- The plan says "investigate", "determine", or "design"
- Changes span 4+ files across multiple modules
- New patterns or shared infrastructure are needed
- Integration with unfamiliar subsystems is required
- The plan has gaps that require codebase research to fill
Using /fleet for Parallel Execution
The /fleet command automatically decomposes work into subtasks and dispatches to
custom agents based on their descriptions. When a plan has independent tasks:
- Switch to plan mode (Shift+Tab) and create the plan
- Use
/fleet to execute — it will route simple tasks to engineer and complex
tasks to architect based on the agent descriptions
- You can also force routing:
@engineer fix the dd_version bug or
@architect design the new pipeline
Scoring Dimensions
Rate each task 0-3 on each dimension:
| Dimension | 0 (Simple) | 1 (Moderate) | 2 (Complex) | 3 (Deep) |
|---|
| Files | 1 file | 2-3 files | 4-6 files | 7+ files |
| Ambiguity | Fully specified | Minor gaps | Design choices | Research needed |
| Dependencies | None | 1 internal | 2-3 internal | External + internal |
| Testing | Add to existing | New test file | New test patterns | Integration tests |
| Risk | Local change | Module-scoped | Cross-module | Breaking change |
Total ≤ 5 → @engineer (Sonnet 4.6 — fast, precise)
Total ≥ 6 → @architect (Opus 4.6 — researches then builds)
Plan Lifecycle
plans/features/<name>.md → Active (implement from here)
plans/features/pending/<name>.md → Reference material (gaps documented)
DELETE the plan file → Fully implemented (code is the doc)
Documentation Checklist
Every completed plan must update affected documentation:
| Target | When to Update |
|---|
AGENTS.md | New CLI commands, MCP tools, config, workflows |
README.md | User-facing features, installation changes |
plans/README.md | Plan status changes |
.claude/skills/ | New reusable workflows |
docs/ | Mature architecture documentation |
| Prompt templates | New or changed LLM prompts |
Common Plan Types in This Project
- Bug fix plans — Phase 1 items, specific file + line references, test cases provided
- Pipeline plans — Multi-phase, schema → code → tests → docs progression
- Server improvement plans — Tool-level changes with A/B test criteria
- Schema evolution plans — LinkML YAML → build-models → migrate data → update code
