spec-to-tasks

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.

Spec to Tasks

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.

Process

1. Read the Spec

Read the spec thoroughly. Identify every contract item:

• Each type definition
• Each function/message signature
• Each behavior (normal and error cases)
• Each constraint (performance, memory, security)
• Each edge case

Make a checklist of contract items. Every item must have at least one task responsible for implementing it.

2. Identify Foundation Tasks

Some work must exist before any vertical slice can be built. These are horizontal foundation tasks:

• Data structures and core types
• Trait definitions and abstractions
• Build system setup (new crates, dependencies, feature flags)
• Test infrastructure (test utilities, fixtures, mock implementations)

Foundation tasks are typically small, focused, and have no dependencies on each other. They block vertical slices.

3. Draft Vertical Slices

Break the remaining work into thin vertical slices. Each slice:

• Delivers a narrow but complete path through the contract
• Is independently testable and verifiable
• Can be merged without breaking existing functionality
• References specific contract items from the spec

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:

• Protocol: Define one message type end-to-end (struct, serialize, send, receive, deserialize, handle, test)
• Renderer: One rendering feature end-to-end (data, shader, pipeline, compositing, test)
• Config: One config surface end-to-end (type, parse, validate, apply, hot-reload, test)
• Plugin API: One plugin capability end-to-end (WIT definition, host binding, guest binding, example plugin, test)

4. Classify Tasks

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

5. Set Dependencies

Order tasks so blockers come first:

• Foundation tasks have no dependencies (or depend only on other foundations)
• Vertical slices depend on their foundation tasks
• Later slices may depend on earlier slices if they extend the same surface
• HITL tasks should be scheduled early — they block on human input

Use Trekker's dependency system (trekker dep add) to encode the graph.

6. Verify Spec Coverage

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.

7. Create an Epic

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.

8. Quiz the User

Present the full breakdown:

• Epic name and scope
• Task list with: title, AFK/Checkpoint/HITL classification, dependencies, contract items covered
• Coverage table showing any gaps
• Suggested implementation order (foundation → first slice → remaining slices)

Ask:

• Is the granularity right? (Too coarse? Too fine?)
• Are the dependencies correct?
• Are the HITL/AFK classifications right?
• Any tasks to merge or split?

Iterate until approved.

9. Create Tasks in Trekker

For each approved task, create a Trekker task with:

• Title: Clear, action-oriented (e.g., "Implement PingPdu message with roundtrip test")
• Description: What to build, referencing specific spec sections
• Tags: feature/chore/spike + area tag + AFK/Checkpoint/HITL
• Priority: 1 (must-ship) / 2 (important) / 3 (nice-to-have) within the epic
• Dependencies: Trekker dep links to blocking tasks

Set dependencies after all tasks are created (need real task IDs).

10. Update Spec Status

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.

11. Commit Gate

Present the task breakdown summary and wait for explicit "commit" before committing.

Common Mistakes

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

Output

• A Trekker epic (if 5+ tasks)
• Trekker tasks with descriptions, tags, priorities, and dependencies
• A spec coverage table showing all contract items are accounted for