القائمة
Break an accepted spec into implementable Trekker tasks with dependency ordering, HITL/AFK classification, and spec coverage verification. Use when: an accepted spec is ready for implementation, you need to decompose work into tasks, or you want to verify every contract item has a task. Requires an accepted spec as input.
Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
Write a formal specification from accepted ADRs and idea docs. Interviews about contract boundaries, sketches bounded concerns, and produces a spec with no hand-waving. Use when: transitioning from accepted ADRs to implementation specs, formalizing API surfaces, wire protocols, or data formats. Must have at least one accepted ADR as input.
| name | spec-to-tasks |
| description | Break an accepted spec into implementable Trekker tasks with dependency ordering, HITL/AFK classification, and spec coverage verification. Use when: an accepted spec is ready for implementation, you need to decompose work into tasks, or you want to verify every contract item has a task. Requires an accepted spec as input. |
Decompose an accepted spec into independently implementable Trekker tasks. Each task is traceable to specific contract items in the spec. No contract item is left without a task.
Skip for: trivial specs that map to a single task, or when the spec is still in draft/review.
Read the spec thoroughly. Identify every contract item:
Make a checklist of contract items. Every item must have at least one task responsible for implementing it.
Some work must exist before any vertical slice can be built. These are horizontal foundation tasks:
Foundation tasks are typically small, focused, and have no dependencies on each other. They block vertical slices.
Break the remaining work into thin vertical slices. Each slice:
Prefer many thin slices over few thick ones. A completed slice should be demoable or verifiable on its own.
For terminal emulator work, typical slices:
Tag each task with an autonomy level:
| Level | Label | Criteria | Example |
|---|---|---|---|
| Autonomous | AFK | Clear spec, single concern, existing patterns to follow, test-first viable | Implement PingPdu message type with roundtrip test |
| Review needed | Checkpoint | Multi-file, touches API surface, security-adjacent, performance-critical | Implement screen buffer dirty-region tracking |
| Collaborative | HITL | Ambiguous spec interpretation, cross-cutting concern, new public API, architectural uncertainty | Design the glyph atlas sharing strategy between daemon and client |
Order tasks so blockers come first:
Use Trekker's dependency system (trekker dep add) to encode the graph.
Walk the contract item checklist from Step 1. For each item, identify which task(s) implement it. Flag any items without a task.
Present a coverage table:
| Contract Item | Task(s) | Status |
| --- | --- | --- |
| PingPdu message type | T-001 | Covered |
| Screen buffer dirty flags | T-003 | Covered |
| Device-loss recovery | (none) | MISSING |
Every contract item must be covered. If an item is intentionally deferred, note it with a reason.
If the spec decomposes into 5+ tasks, create a Trekker epic scoped by user-visible outcome (per CLAUDE.md: "What is different when this is done?"). The epic references the spec. Tasks belong to the epic.
Present the full breakdown:
Ask:
Iterate until approved.
For each approved task, create a Trekker task with:
feature/chore/spike + area tag + AFK/Checkpoint/HITLSet dependencies after all tasks are created (need real task IDs).
Update the spec's frontmatter status from accepted to implementing. Update the index table in docs/specs/README.md if it tracks status. If any doc files were modified during this process, run mise run fmt and mise run lint before committing.
Present the task breakdown summary and wait for explicit "commit" before committing.
| Mistake | Fix |
|---|---|
| All tasks are horizontal layers ("implement all types", "implement all tests") | Split into vertical slices that cut through layers |
| No foundation tasks — first slice is huge | Extract shared types and infrastructure into small foundation tasks |
| Every task is HITL | Most implementation from a clear spec is AFK. Reserve HITL for genuine ambiguity. |
| Tasks don't reference spec sections | Every task description must cite the contract items it implements |
| Coverage gaps not flagged | Run the coverage check. Missing items are either deferred (with reason) or added as tasks. |
| Epic is too vague ("Implement the renderer") | Epic must answer "what is different when this is done?" with a specific, verifiable outcome |