implement
Skill40 starsChanged 4 months agoMITView on GitHub
Canonical implementation parent command. Executes the active track task-by-task using TDD and verification gates, and routes to status, coverage, or revert when the user asks for progress, measurement, or rollback explicitly.
191 other projects use a version of this.
Adopted by
Most recently taken up by
- revisit-studies/studytheir own version, first seen Nov 9, 2026
- dz114879/skillstheir own version, first seen Nov 8, 2026
- Dimon94/dveritytheir own version, first seen Nov 8, 2026
- Dimon94/skillstheir own version, first seen Nov 8, 2026
- The-Vibe-Company/quivrtheir own version, first seen Nov 8, 2026
- miklschmidt/archboardtheir own version, first seen Nov 8, 2026
Used with
Projects with it also use setup-ts-deep-modules, ask-matt and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 43 projects that use this
GoogleSkillask-matt
Ask which skill or flow fits your situation. A router over the skills in this repo.
Also in 91 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 50 projects that use this
AWSSkillto-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
Also in 88 projects that use this
ryotaroh180105Skillclaude-handoff
Hand the current conversation off to a fresh background agent that picks up the work immediately.
Also in 42 projects that use this
GoogleSkillto-spec
Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
Also in 168 projects that use this
- +3 more from google
Other versions191 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 191
- mattpocock/skills★ 309ksame name
- QuivrHQ/quivr★ 40ksame name
- The-Vibe-Company/quivr★ 40ksame name
- foambubble/foam★ 17ksame name
- formbricks/formbricks★ 13ksame name
- ArcReel/ArcReel★ 6.3ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.5ksame name
- fallow-rs/fallow★ 5.3ksame name
- withcoral/coral★ 4.9ksame name
- bestofjs/bestofjs★ 3.1ksame name
181 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository35 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- web/llms-full.txtllms.txt
- web/llms.txtllms.txt
- adrSkill
- assist-reviewSkill
- bughuntSkill
- changeSkill
- coverageSkill
- debugSkill
- decomposeSkill
- deep-reviewSkill
- deploy-checklistSkill
- discoverSkill
- docsSkill
- documentationSkill
- draftSkill
- graphSkill
- impactSkill
- incident-responseSkill
- initSkill
- integrationsSkill
- jiraSkill
- learnSkill
- new-trackSkill
- opsSkill
- planSkill
- quick-reviewSkill
- revertSkill
- reviewSkill
- standupSkill
- statusSkill
- tech-debtSkill
- testing-strategySkill
- tourSkill
- uploadSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
118 rules. 0 are common, 75 are distinctive, and 43 are very specific to this project.
0
Common
Most of the 171 edited versions we read keep these.
75
Distinctive
This author's own choices. Worth a look.
43
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 49
If the user invokes explicit child intent, route directly:
- Distinctive: line 69
run review and verification gates at phase boundaries
- Very specific: line 72
Do not make the user remember status or coverage in the happy path just to continue safe execution.
- Distinctive: line 78
Before loading implementation context, check whether the request is really:
- Distinctive: line 113
If one of these applies, route directly to the specialist workflow and stop this baseline implementation flow.
- Very specific: line 120
Read the track's spec.md for requirements
- Very specific: line 121
Read the track's plan.md for task list
- Very specific: line 122
Read draft/workflow.md for TDD and commit preferences
- Very specific: line 123
Read draft/tech-stack.md for technical context
- Very specific: line 124
Read draft/guardrails.md (if exists) for hard guardrails and learned conventions
- Distinctive: line 128
If relevant design context exists → Enable architecture mode (Story, Execution State, Skeletons)
- Distinctive: line 129
If neither exists → Standard TDD workflow
- Very specific: line 131
Read the ## INVARIANTS section (and ## CONCURRENCY if present)
- Distinctive: line 133
Keep matching invariants as active constraints for this task — these govern code generation, not just review
- Distinctive: line 134
If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
- Very specific: line 148
Run "$DRAFT_TOOLS/hotspot-rank.sh" --repo .
- Distinctive: line 149
If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}).
- Very specific: line 152
Update the track's entry in draft/tracks.md from [ ] to [~] In Progress
- Distinctive: line 154
If no active track found:
- Distinctive: line 168
Run once, before the first task of a new track:
- Very specific: line 174
Verify at least one task in plan.md references or addresses it
- Distinctive: line 175
If an AC has no corresponding task, flag it: "⚠️ AC: '[criterion]' has no task in plan.md"
- Distinctive: line 182
If they differ: "⚠️ Spec and plan were synced to different commits — verify they are still aligned."
- Distinctive: line 199
Before starting TDD cycle for the first task:
- Distinctive: line 201
Check for testing strategy:
- Distinctive: line 204
If found: load coverage targets, test boundaries, and strategy into TDD context
- Very specific: line 205
If not found and TDD is enabled: suggest "Run /draft:testing-strategy to define test approach"
- Very specific: line 209
If track type is bugfix (from metadata.json):
- Distinctive: line 226
IMPORTANT: If blocked task found, notify user:
- Distinctive: line 231
Do NOT attempt to implement blocked tasks
- Very specific: line 233
If resuming [~] task, check for partial work.
- Distinctive: line 237
After choosing the next task, check whether baseline implementation should remain in build mode or whether it should surface another …
- Distinctive: line 241
If the track has:
- Distinctive: line 244
no obvious next runnable task
- Distinctive: line 253
If the implementation is at one of these points:
- Very specific: line 272
If the selected task is blocked because earlier implementation appears invalid, conflicting, or partially reverted, /draft:implement should …
- Very specific: line 276
Activation: Only runs when .ai-context.md, graph-primary architecture.md, or track hld.md/lld.md exists.
- Distinctive: line 278
When the next task involves creating or substantially modifying a code file:
- Distinctive: line 280
Check if file already has a Story comment: - If yes, skip this step
- Distinctive: line 325
Read the Story (from Step 2.5) to understand the Input -> Output path
- Distinctive: line 355
Create stubs with complete signatures (all parameters, return types)
- Very specific: line 357
No implementation bodies — use // TODO, pass, unimplemented!(), etc.
- Very specific: line 359
Follow naming conventions from tech-stack.md
- Distinctive: line 371
When your implementation hits any of these triggers, use the corresponding pattern.
- Distinctive: line 446
When refactoring code that lacks tests, write characterization tests first to capture current behavior as a baseline.
- Distinctive: line 450
Iron Law: No production code without a failing test first.
- Distinctive: line 464
No shared mutable state between test cases — each test sets up its own state
- Distinctive: line 466
No logic in tests: no conditionals, loops, or try/catch in test code — tests should be trivially readable
- Distinctive: line 468
Test behavior, not implementation: verify observable outcomes, not internal method calls
- Distinctive: line 473
After writing example-based tests, consider property-based tests for pure functions (algebraic properties, round-trip serialization, sort …
- Distinctive: line 503
Test passes immediately (testing wrong thing)
- Very specific: line 519
Activation: Only when .ai-context.md or architecture.md exists (track-level or project-level).
- Distinctive: line 521
If the implementation diff for a task exceeds ~200 lines:
- Distinctive: line 523
STOP: after ~200 lines of implementation
- Distinctive: line 525
CHECKPOINT (MANDATORY): Wait for developer approval of the chunk
- Very specific: line 526
Commit the approved chunk: feat(<track_id>): <task description> (chunk N)
- Distinctive: line 536
Iron Law: Every completed task gets its own commit.
- Distinctive: line 538
After completing each task:
- Distinctive: line 542
If any trigger is present but the pattern wasn't applied: fix it now
- Distinctive: line 545
Commit FIRST (REQUIRED - non-negotiable):
- Distinctive: line 548
Verify staged changes exist before committing: git diff --cached --quiet.
- Very specific: line 550
If a Jira ticket is linked in spec.md, reference it in the commit body: Refs: <JIRA_ID>.
- Distinctive: line 552
Do NOT proceed to the next task without committing
- Distinctive: line 553
Do NOT batch multiple tasks into one commit
- Very specific: line 557
Add the commit SHA next to the task: [x] Task description (abc1234)
- Very specific: line 564
Read back plan.md - confirm task marked [x] with SHA
- Very specific: line 565
Read back metadata.json - confirm tasks.completed incremented
- Distinctive: line 566
If EITHER verification fails:
- Very specific: line 568
Add recovery message: "State update failed after commit <SHA>.
- Very specific: line 571
If .ai-context.md or graph-primary architecture.md (or track hld/lld) exists:
- Distinctive: line 572
Update module status markers where applicable.
- Very specific: line 574
If updating project-level draft/.ai-context.md: also update YAML frontmatter and run the Condensation Subroutine to keep it in sync.
- Distinctive: line 578
Iron Law: No completion claims without fresh verification evidence.
- Very specific: line 580
Before marking ANY task/phase/track complete:
- Very specific: line 586
If NO: Keep task as [~], state actual status
- Very specific: line 587
If YES: Show evidence, then mark [x]
- Very specific: line 601
When all tasks in a phase are [x]:
- Distinctive: line 615
Verify all requirements for this phase are implemented
- Distinctive: line 616
Check acceptance criteria coverage
- Distinctive: line 621
Verify code follows project patterns (tech-stack.md)
- Distinctive: line 622
Check error handling is appropriate
- Distinctive: line 623
Verify tests cover real logic
- Very specific: line 639
If quick-review chosen, invoke /draft:quick-review with the phase's changed files.
- Distinctive: line 641
Run verification steps from plan (tests, builds)
- Distinctive: line 643
If review passes (no Critical issues):
- Distinctive: line 644
Update phase status in plan
- Distinctive: line 648
If Critical/Important issues found:
- Distinctive: line 649
Document issues in plan.md
- Very specific: line 654
After a phase passes review, refresh metadata.json.impact so future tracks can detect overlap with this work.
- Very specific: line 664
Compute downstream blast radius (graph-aware, optional): If draft/graph/schema.yaml exists, for each file in files_touched query (this runs …
- Distinctive: line 682
When all phases complete:
- Very specific: line 685
Read draft/workflow.md review configuration
- Distinctive: line 686
Check if auto-review enabled:
- Very specific: line 693
If enabled, run /draft:review track <track_id>
- Distinctive: line 695
If block-on-failure enabled AND critical issues found → HALT, require fixes
- Very specific: line 698
Update plan.md status to [x] Completed
- Very specific: line 705
Read back plan.md - confirm status [x] Completed
- Very specific: line 707
Read back draft/tracks.md - confirm track in Completed section with completion date
- Distinctive: line 708
If ANY file shows inconsistent state:
- Distinctive: line 712
Do NOT announce completion until all three files verified consistent
- Distinctive: line 727
All acceptance criteria from spec.md should be verified.
- Distinctive: line 736
Add reason in plan.md
- Very specific: line 737
REQUIRED: Follow systematic debugging process (see core/agents/debugger.md)
- Distinctive: line 738
Investigate: - Read errors, reproduce, trace (NO fixes yet)
- Distinctive: line 742
Do NOT attempt random fixes
- Distinctive: line 743
Document root cause when found
- Very specific: line 745
Recommended: Instead of inline debugging, invoke /draft:debug skill for a structured session:
- Distinctive: line 755
Don't mark complete
- Distinctive: line 756
Follow systematic debugging process above
- Distinctive: line 764
Don't proceed with assumptions
- Distinctive: line 770
When you encounter a shortcut, workaround, or known-imperfect solution during implementation:
- Very specific: line 772
Add an entry to the ## Tech Debt section at the bottom of plan.md
- Distinctive: line 792
Only log genuine debt — intentional shortcuts with known consequences.
- Distinctive: line 798
After each task, report:
- Distinctive: line 813
After announcing track completion, suggest relevant follow-ups based on context:
- Very specific: line 842
If Jira ticket linked, sync via core/shared/jira-sync.md:
- Very specific: line 848
If implementing a bug track and draft/tracks/<id>/rca.md exists:
- Distinctive: line 852
After fix: update rca.md "Proposed Fix" section with actual fix details
“Common” is measured: kept by at least 6 in 10 of the 171 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Implement Track
Implement tasks from the active track's plan following the TDD workflow.
/draft:implement is the canonical implementation parent.
It owns the common execution loop and absorbs three adjacent commands when appropriate:
/draft:status/draft:coverage/draft:revert
Red Flags - STOP if you're
- Implementing without an approved spec and plan
- Skipping TDD cycle when workflow.md has TDD enabled
- Marking a task
[x]without fresh verification evidence - Batching multiple tasks into a single commit
- Proceeding past a phase boundary without running the three-stage review
- Writing production code before a failing test (when TDD is strict)
- Assuming a test passes without actually running it
Verify before you mark complete. One task, one commit.
Constraints
Draft skills are designed for single-agent, single-track execution. Do not run multiple Draft commands concurrently on the same track.
Parent Contract
/draft:implement owns four execution jobs:
- Build the next task → baseline
/draft:implement - Show current execution state →
/draft:status - Measure implementation completeness via coverage →
/draft:coverage - Undo implementation safely →
/draft:revert
Most developers should only need /draft:implement in the common path.
Explicit Child Modes
If the user invokes explicit child intent, route directly:
/draft:implement status→ follow/draft:status/draft:implement coverage→ follow/draft:coverage/draft:implement revert→ follow/draft:revert
Examples:
/draft:implement status/draft:implement coverage src/auth/draft:implement revert phase 2
Explicit child mode always wins over the baseline implementation workflow.
Bare /draft:implement
Without an explicit child mode, /draft:implement should:
- continue the active track's next task
- surface blocked-task conditions immediately
- run review and verification gates at phase boundaries
- suggest or attach coverage only when the implementation state justifies it
Do not make the user remember status or coverage in the happy path just to continue safe execution.
Step 0: Route Explicit Child Modes
Before loading implementation context, check whether the request is really:
- progress inspection
- coverage measurement
- rollback / undo
Route to /draft:status
Route when the user asks:
statusprogresswhat's leftwhere am I
Route to /draft:coverage
Route when the user asks:
coveragemeasure testshow much is coveredcoverage for <module/path>
Route to /draft:revert
Route when the user asks:
revertundoroll backrevert taskrevert phaserevert track
If one of these applies, route directly to the specialist workflow and stop this baseline implementation flow.
Step 1: Load Context
- Find active track from
draft/tracks.md(look for[~] In Progressor first[ ]track) - Read the track's
spec.mdfor requirements - Read the track's
plan.mdfor task list - Read
draft/workflow.mdfor TDD and commit preferences - Read
draft/tech-stack.mdfor technical context - Read
draft/guardrails.md(if exists) for hard guardrails and learned conventions - Check for architecture context:
- Project-level:
draft/.ai-context.md(preferred) ordraft/architecture.md(graph-primary) - Track-level design docs:
draft/tracks/<id>/hld.md(+lld.mdwhen present) - If relevant design context exists → Enable architecture mode (Story, Execution State, Skeletons)
- If neither exists → Standard TDD workflow
- Project-level:
- Load production invariants (if
draft/.ai-context.mdexists):- Read the
## INVARIANTSsection (and## CONCURRENCYif present) - Identify which invariants reference files this task will modify (same file or same module)
- Keep matching invariants as active constraints for this task — these govern code generation, not just review
- If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
- Read the
Load graph context (if
draft/graph/schema.yamlexists):First resolve the bundled helpers:
# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT} # is not exported into skill Bash). See core/shared/tool-resolver.md. DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"- Run
"$DRAFT_TOOLS/hotspot-rank.sh" --repo .— check if any files this task will modify appear as hotspots - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query."
- Query
"$DRAFT_TOOLS/graph-impact.sh"/"$DRAFT_TOOLS/graph-callers.sh"for the module(s) being modified — gives file-level dependency context - See
core/shared/graph-query.mdfor on-demand query subroutines (callers, impact)
- Run
- Update the track's entry in
draft/tracks.mdfrom[ ]to[~]In Progress
If no active track found:
- Tell user: "No active track found. Run
/draft:planto create or resume planned work."
Architecture / Design Mode Activation:
- Automatically enabled when
.ai-context.md, graph-primaryarchitecture.md, or trackhld.md/lld.mdexists. - Project-level context from
/draft:init. - Track-level design docs from
/draft:decompose.
Step 1.5: Readiness Gate (Fresh Start Only)
Skip if: Any task in plan.md is already [x] — the track is in progress, this check has already passed.
Run once, before the first task of a new track:
AC Coverage Check
For each acceptance criterion in spec.md:
- Verify at least one task in
plan.mdreferences or addresses it - If an AC has no corresponding task, flag it: "⚠️ AC: '[criterion]' has no task in plan.md"
Sync Check (if .ai-context.md exists)
Compare the synced_to_commit values in the YAML frontmatter of spec.md and plan.md.
- Skip if either file has no YAML frontmatter or no
synced_to_commitfield (quick-mode tracks omit it). - If they differ: "⚠️ Spec and plan were synced to different commits — verify they are still aligned."
Result
Issues found: List them, then ask:
Readiness issues found (see above). Proceed anyway or update first? [proceed/update]proceed→ add a## Notesentry inplan.mdlisting the issues, then continue to Step 2update→ stop here and let the user refine spec or plan before re-running
No issues: Print Readiness check passed. and continue to Step 2.
Step 1.7: Testing Strategy Loading
Before starting TDD cycle for the first task:
- Check for testing strategy:
- Track-level:
draft/tracks/<id>/testing-strategy.md - Project-level:
draft/testing-strategy.mdordraft/testing-strategy-latest.md
- Track-level:
- If found: load coverage targets, test boundaries, and strategy into TDD context
- If not found and TDD is enabled: suggest "Run
/draft:testing-strategyto define test approach"
Bug Track Test Guardrail
If track type is bugfix (from metadata.json):
BEFORE writing any test file:
ASK: "This is a bug fix track. Want me to write tests as part of the fix? [Y/n]"
If declined: skip TDD cycle, note in plan.md: "Tests: developer-handled"Step 2: Find Next Task
Scan plan.md for the first uncompleted task:
[ ]= Pending (pick this one)[~]= In Progress (resume this one)[x]= Completed (skip)[!]= Blocked (skip - requires manual intervention)
IMPORTANT: If blocked task found, notify user:
- "Task [task description] is marked
[!]Blocked" - Show the blocked task details and recovery message
- "Resolve the blockage manually before continuing implementation"
- Do NOT attempt to implement blocked tasks
If resuming [~] task, check for partial work.
Implementation-State Escalations
After choosing the next task, check whether baseline implementation should remain in build mode or whether it should surface another execution helper.
Escalate to Status-Style Summary
If the track has:
- many blocked tasks
- no obvious next runnable task
- conflicting in-progress markers
then present a concise status summary before proceeding so the user can see the execution state clearly.
This does not require fully routing to /draft:status; it is an implementation-owned checkpoint.
Escalate to Coverage Guidance
If the implementation is at one of these points:
- phase just completed
- track just completed
- high-risk module just changed and tests exist but coverage is unknown
then /draft:implement should suggest coverage or auto-attach it when the workflow and user intent imply measurement is expected.
Examples:
Implementation checkpoint:
- Phase 2 is complete
- Next recommended action: /draft:implement coverage
- Reason: high-risk auth code changed and coverage has not been measured for this phaseEscalate to Revert Guidance
If the selected task is blocked because earlier implementation appears invalid, conflicting, or partially reverted, /draft:implement should recommend /draft:implement revert explicitly rather than pushing forward blindly.
Step 2.5: Write Story (Architecture Mode Only)
Activation: Only runs when .ai-context.md, graph-primary architecture.md, or track hld.md/lld.md exists.
When the next task involves creating or substantially modifying a code file:
- Check if file already has a Story comment - If yes, skip this step
- Skip for trivial tasks - Config files, type definitions, simple one-liners
- Write a natural-language algorithm description as a comment block at the top of the target file
Story Format
// Story: [Module/File Name]
//
// Input: [what this module/function receives]
// Process:
// 1. [first algorithmic step]
// 2. [second algorithmic step]
// 3. [third algorithmic step]
// Output: [what this module/function produces]
//
// Dependencies: [what this module relies on]
// Side effects: [any mutations, I/O, or external calls]Adapt comment syntax to the language (# for Python, /* */ for CSS, etc.).
CHECKPOINT (MANDATORY)
STOP. Present the Story to the developer for review.
- Developer may refine, modify, or rewrite the Story
- Do NOT proceed to execution state or implementation until Story is approved
- Developer can say "skip" to bypass this checkpoint for the current task
See core/agents/architect.md for story writing guidelines.
Step 3: Execute Task
Step 3.0: Design Before Code (Architecture Mode Only)
Activation: Only runs when .ai-context.md, graph-primary architecture.md, or track hld.md/lld.md exists.
Skip for trivial tasks - Config updates, type-only changes, single-function tasks where the design is obvious.
3.0a. Execution State Design
Study the control flow for the task and propose intermediate state variables:
- Read the Story (from Step 2.5) to understand the Input -> Output path
- Study similar patterns in the existing codebase
- Check
.ai-context.mdData Lifecycle — Align execution state with documented state machines (valid states/transitions), storage topology (which tier data targets), and data transformation chain (shape changes at boundaries) - Check
.ai-context.mdCritical Paths — Identify where this task sits in documented write/read/async paths. Note consistency boundaries and failure recovery expectations. - Propose execution state: input state, intermediate state, output state, error state
Present in this format:
EXECUTION STATE: [Task/Module Name]
─────────────────────────────────────────────────────────
Input State:
- variableName: Type — purpose
Intermediate State:
- variableName: Type — purpose
Output State:
- variableName: Type — purpose
Error State:
- variableName: Type — purposeCHECKPOINT (MANDATORY): Present execution state to developer. Wait for approval. Developer may add, remove, or modify state variables. Developer can say "skip" to bypass.
3.0b. Function Skeleton Generation
Generate function/method stubs based on the approved execution state:
- Create stubs with complete signatures (all parameters, return types)
- Include a one-line docstring describing purpose and when it's called
- No implementation bodies — use
// TODO,pass,unimplemented!(), etc. - Order functions to match control flow sequence
- Follow naming conventions from
tech-stack.md
CHECKPOINT (MANDATORY): Present skeletons to developer. Wait for approval. Developer may rename functions, change signatures, add/remove methods. Developer can say "skip" to bypass.
See core/agents/architect.md for execution state and skeleton guidelines.
Step 3.0c: Production Robustness Patterns (REQUIRED)
Applies to all code generation — architecture mode or not. These patterns are generation directives, not a post-hoc checklist. Apply them while writing code, not after.
When your implementation hits any of these triggers, use the corresponding pattern. Do not write code that violates these and plan to "fix it later."
Atomicity
| Trigger | Required Pattern |
| Multi-step state mutation (DB + memory, multiple records) | Wrap in transaction or try/finally with rollback on failure |
| File write | Write to temp file + atomic rename to target path. Never write directly to the target. |
| DB write paired with in-memory state update | DB-first: persist to DB, update memory only on DB success. Never update memory optimistically. |
| Resource acquisition (locks, file handles, connections, capital) | Release in finally / defer / RAII — never rely on happy-path-only cleanup |
Isolation
| Trigger | Required Pattern |
| Method mutates shared/instance state | Acquire the class's or module's existing lock before mutation |
| Lifecycle operations (start/stop/reset/reconnect) | Use a dedicated lifecycle lock, separate from data locks |
| Returning internal state to callers | Return a deep copy or frozen snapshot — never a mutable reference to internal state |
| Acquiring a second lock while holding one | Follow documented lock ordering. If no ordering exists, do not nest locks — restructure to acquire sequentially. |
| DB I/O while holding a state lock | Move DB I/O outside the lock scope. Lock only the in-memory mutation, not the I/O. |
Durability
| Trigger | Required Pattern |
| Critical state that must survive crashes | Ensure state is recoverable from DB/disk alone — no reliance on in-memory-only state for recovery |
| Async DB write (fire-and-forget) | Await the write. Check return value or propagate exceptions. No fire-and-forget on data persistence. |
| Event log / audit trail / fill history | Use append-only pattern where specified by architecture |
Defensive Boundaries
| Trigger | Required Pattern |
| External numeric data used in arithmetic | Guard with isFinite() / isnan() / equivalent before any calculation |
| External API/webhook response consumed | Validate expected fields exist and have correct types before accessing nested properties |
| SQL query with dynamic values | Parameterized queries only — zero string interpolation for values |
| Dynamic column names, table names, or identifiers in SQL | Validate against an explicit allowlist — never pass user-controlled strings as identifiers |
Idempotency
| Trigger | Required Pattern |
| Operation that may be retried (network calls, queue consumers, webhook handlers) | Use a dedup key (UUID, request ID, fill ID) — check-before-write or upsert |
| State transition (status changes, lifecycle events) | Validate the transition is legal from the current state. Reject terminal→terminal transitions. |
| Alert / notification emission | Dedup on (alert_type, entity_id, time_window) to prevent re-firing on retries |
Fail-Closed
| Trigger | Required Pattern |
| Error path or exception handler that determines access/action | Default to the safe/restrictive/deny state — never default to permissive on error |
| Missing data, null, or undefined where a decision depends on it | Treat as deny/reject/skip — not as allow/proceed |
| Config or feature flag missing/unparseable | Use the restrictive default — system runs in safe mode, not open mode |
Resilience
| Trigger | Required Pattern |
| Any retry logic | Exponential backoff with jitter — never fixed-interval or immediate retries. Prevents retry storms. |
| Cache population under high concurrency | Cache stampede prevention: use probabilistic early expiration or request coalescing to prevent thundering herd |
| External dependency call (HTTP, RPC, DB to external service) | Circuit breaker pattern: track failure rate, open circuit on threshold, allow periodic probes to recover |
| Non-critical dependency failure | Graceful degradation: return cached/default/partial result rather than failing the entire request |
Enforcement: These patterns override convenience. If following a pattern makes the code more verbose, that's correct — the verbosity is the safety. If a pattern is genuinely N/A for the current task (e.g., no DB in a pure utility function), skip it — only apply relevant patterns.
If project invariants were loaded in Step 1: Cross-reference them here. Project-specific invariants (lock ordering, concurrency model, consistency boundaries) take precedence over these general patterns when they conflict.
Step 3.1: Implement (TDD Workflow)
For each task, follow this workflow based on workflow.md. If skeletons were generated in Step 3.0b, fill them in using the TDD cycle below.
Characterization Testing (Refactoring Existing Code Without Tests)
When refactoring code that lacks tests, write characterization tests first to capture current behavior as a baseline. Identify seams (interfaces for test doubles, swappable imports), record actual outputs for representative inputs, then proceed with the TDD cycle for new behavior.
If TDD Enabled
Iron Law: No production code without a failing test first.
3a. RED - Write Failing Test
1. Create/update test file as specified in task
2. Write test that captures the requirement
3. RUN test - VERIFY it FAILS (not syntax error, actual assertion failure)
4. Show test output with failure
5. Announce: "Test failing as expected: [failure message]"Test Quality Checklist (REQUIRED for every test):
- No shared mutable state between test cases — each test sets up its own state
- Assertion density: every test must have at least one meaningful assertion (not just
assertTrue(true)) - No logic in tests: no conditionals, loops, or try/catch in test code — tests should be trivially readable
- DAMP over DRY: prefer descriptive and meaningful test names and setup over deduplication
- Test behavior, not implementation: verify observable outcomes, not internal method calls
- One behavior per test: each test should verify exactly one logical behavior
- Reference: Google SWE Book Ch. 12, Google Testing Blog "Test Behavior, Not Implementation"
Property-Based Testing Checkpoint: After writing example-based tests, consider property-based tests for pure functions (algebraic properties, round-trip serialization, sort invariants). Not mandatory — skip if properties are not obvious.
3b. GREEN - Implement Minimum Code
1. Write MINIMUM code to make test pass (no extras)
2. RUN test - VERIFY it PASSES
3. Show test output with pass
4. Announce: "Test passing: [evidence]"Observability Prompts (consider during implementation): Structured logging at decision points, metrics for latency-sensitive ops, tracing at service boundaries, error classification (transient vs permanent). Use engineering judgment — not mandatory for every task.
Contract Testing Checkpoint (Service Boundaries Only): For new API endpoints or service-to-service interfaces, suggest consumer-driven contract tests. Skip for purely internal modules.
3c. REFACTOR - Clean with Tests Green
1. Review code for improvements
2. Refactor while keeping tests green
3. RUN all related tests after each change
4. Show final test output
5. Announce: "Refactoring complete, all tests passing: [evidence]"Red Flags - STOP and restart the cycle if:
- About to write code before test exists
- Test passes immediately (testing wrong thing)
- Thinking "just this once" or "too simple to test"
- Running tests mentally instead of actually executing
If TDD Not Enabled
3a. Implement
1. Implement the task as specified
2. Test manually or run existing tests
3. Announce: "Implementation complete"Implementation Chunk Limit (Architecture Mode Only)
Activation: Only when .ai-context.md or architecture.md exists (track-level or project-level).
If the implementation diff for a task exceeds ~200 lines:
- STOP after ~200 lines of implementation
- Present the chunk for developer review
- CHECKPOINT (MANDATORY): Wait for developer approval of the chunk
- Commit the approved chunk:
feat(<track_id>): <task description> (chunk N) - Continue with the next chunk
- Repeat until the task is fully implemented
This prevents large, unreviewable code drops. Each chunk should be a coherent, reviewable unit.
Step 4: Update Progress & Commit
Iron Law: Every completed task gets its own commit. No batching. No skipping.
After completing each task:
- Quick robustness scan (30-second check before committing):
- Scan the code you just wrote against the Step 3.0c triggers
- If any trigger is present but the pattern wasn't applied: fix it now
- This is a rapid pattern-match, not a full review — you should have applied these during generation, this catches anything missed
- Commit FIRST (REQUIRED - non-negotiable):
- Stage only files changed by this task (never
git add .) git add <specific files>- Verify staged changes exist before committing:
git diff --cached --quiet. If nothing staged, skip the commit step. git commit -m "type(<track_id>): task description"(Conventional Commits — seecore/shared/vcs-commands.md)- If a Jira ticket is linked in
spec.md, reference it in the commit body:Refs: <JIRA_ID>. - Get commit SHA:
git rev-parse --short HEAD - Do NOT proceed to the next task without committing
- Do NOT batch multiple tasks into one commit
- Stage only files changed by this task (never
- Update
plan.md:- Change
[ ]to[x]for the completed task - Add the commit SHA next to the task:
[x] Task description (abc1234)
- Change
- Update
metadata.json:- Increment
tasks.completed - Update
updatedtimestamp
- Increment
- Verify state updates (CRITICAL):
- Read back
plan.md- confirm task marked[x]with SHA - Read back
metadata.json- confirmtasks.completedincremented - If EITHER verification fails:
- Mark task as
[!]Blocked in plan.md - Add recovery message: "State update failed after commit
<SHA>. Recovery: manually edit plan.md line X to mark[x], update metadata.json tasks.completed to Y" - HALT - require manual intervention before continuing
- Mark task as
- Read back
- If
.ai-context.mdor graph-primaryarchitecture.md(or track hld/lld) exists:- Update module status markers where applicable.
- Fill in Story placeholders with the approved story from Step 2.5
- If updating project-level
draft/.ai-context.md: also update YAML frontmatter and run the Condensation Subroutine to keep it in sync.
Verification Gate (REQUIRED)
Iron Law: No completion claims without fresh verification evidence.
Before marking ANY task/phase/track complete:
- IDENTIFY: What command proves this claim? (test, build, lint)
- RUN: Execute the FULL command (fresh, complete run)
- READ: Full output, check exit code
- VERIFY: Does output confirm the claim?
- If NO: Keep task as
[~], state actual status - If YES: Show evidence, then mark
[x]
- If NO: Keep task as
Red Flags - STOP if you're thinking:
- "Should pass", "probably works"
- Satisfaction before running verification
- About to mark
[x]without fresh evidence from this session - "I already tested earlier"
- "This is a simple change, no need to verify"
Step 5: Phase Boundary Check
When all tasks in a phase are [x]:
- Announce: "Phase N complete. Running three-stage review."
Three-Stage Review (REQUIRED)
Stage 1: Automated Validation
- Fast static checks: architecture conformance, dead code, circular dependencies, performance anti-patterns. Review for common security anti-patterns (OWASP top 10). For automated checks, use language-specific tools (e.g.,
npm auditfor JS,banditfor Python,cargo auditfor Rust). - If critical issues found: List them, return to implementation
Stage 2: Spec Compliance (only if Stage 1 passes)
- Load track's
spec.md - Verify all requirements for this phase are implemented
- Check acceptance criteria coverage
- If gaps found: List them, return to implementation
Stage 3: Code Quality (only if Stage 2 passes)
- Verify code follows project patterns (tech-stack.md)
- Check error handling is appropriate
- Verify tests cover real logic
- Classify issues: Critical (must fix) > Important (should fix) > Minor (note)
See core/agents/reviewer.md for detailed review process.
Quick Review Alternative
At phase boundaries, offer the lightweight alternative:
"Phase {N} complete. Review options:
1. Full three-stage review (recommended) — spec compliance + security + quality
2. /draft:quick-review — lightweight 4-dimension check (faster)
Choose [1/2, default: 1]:"If quick-review chosen, invoke /draft:quick-review with the phase's changed files.
- Run verification steps from plan (tests, builds)
- Present review findings to user
- If review passes (no Critical issues):
- Update phase status in plan
- Update
metadata.jsonphases.completed - Refresh blast-radius memory (see "Impact Memory" subsection below)
- Proceed to next phase
- If Critical/Important issues found:
- Document issues in plan.md
- Fix before proceeding (don't skip)
Impact Memory (blast-radius snapshot)
After a phase passes review, refresh metadata.json.impact so future tracks can detect overlap with this work.
Compute touched files: From
plan.md, find the first commit SHA recorded for this track (earliest[x]line with(<sha>)). Run:git diff --name-only <first_sha>^..HEADThat is the
files_touchedlist. Derivemodules_touchedas the unique top-level path segments (e.g.auth/login.go→auth).Compute downstream blast radius (graph-aware, optional): If
draft/graph/schema.yamlexists, for each file infiles_touchedquery (this runs in its own Bash session — re-resolve the helpers):DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)" [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools" "$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>Aggregate across all files:
downstream_files= count of the union of each query'sdownstream_filesarray,downstream_modules= union ofaffected_modules,max_depth= max across queries,by_category= sum of each query'sby_category. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.- Write metadata.json with the populated
impactblock andcomputed_atset to the current timestamp.
This snapshot is consumed by /draft:new-track to surface overlap warnings when a new track touches the same modules as a recently completed track.
Step 6: Track Completion
When all phases complete:
- Run review (if enabled):
- Read
draft/workflow.mdreview configuration Check if auto-review enabled:
## Review Settings - [x] Auto-review at track completion- If enabled, run
/draft:review track <track_id> - Check review results:
- If block-on-failure enabled AND critical issues found → HALT, require fixes
- Otherwise, document warnings and continue
- Read
- Update
plan.mdstatus to[x] Completed - Update
metadata.jsonstatus to"completed" - Update
draft/tracks.md:- Move from Active to Completed section
- Add completion date
- Verify completion state consistency (CRITICAL):
- Read back
plan.md- confirm status[x] Completed - Read back
metadata.json- confirm status"completed" - Read back
draft/tracks.md- confirm track in Completed section with completion date - If ANY file shows inconsistent state:
- ERROR: "Track completion partially failed"
- Report: "plan.md:
<status>, metadata.json:<status>, tracks.md:<section>" - Provide recovery: "Manually complete updates: [list specific edits needed]"
- Do NOT announce completion until all three files verified consistent
- Read back
- Announce: "Track <track_id> completed!
Summary:
- Phases: N/N
- Tasks: M/M
- Duration: [if tracked]
[If review ran:] Review: PASS | PASS WITH NOTES | FAIL Report: draft/tracks/<track_id>/review-report-latest.md
All acceptance criteria from spec.md should be verified.
Next: Run /draft:status to see project overview."
Error Handling
If blocked:
- Mark task as
[!]Blocked - Add reason in plan.md
- REQUIRED: Follow systematic debugging process (see
core/agents/debugger.md)- Investigate - Read errors, reproduce, trace (NO fixes yet)
- Analyze - Find similar working code, list differences
- Hypothesize - Single hypothesis, smallest test
- Implement - Regression test first, then fix
- Do NOT attempt random fixes
- Document root cause when found
Recommended: Instead of inline debugging, invoke /draft:debug skill for a structured session:
"Task blocked: {description}. Run /draft:debug for structured investigation? [Y/n]"The debug skill provides: Reproduce → Isolate → Diagnose → Fix methodology with debug report output.
If test fails unexpectedly:
- Don't mark complete
- Follow systematic debugging process above
- Announce failure details with root cause analysis
- Show evidence when resolved
If unsure about implementation:
- Ask clarifying questions
- Reference spec.md for requirements
- Don't proceed with assumptions
Tech Debt Log
During implementation, track technical debt decisions in the track's plan.md:
When you encounter a shortcut, workaround, or known-imperfect solution during implementation:
- Add an entry to the
## Tech Debtsection at the bottom of plan.md - Use this format:
## Tech Debt
| ID | Location | Description | Severity | Payback Trigger |
|----|----------|-------------|----------|-----------------|
| TD-1 | `src/api/handler.ts:45` | Hardcoded timeout instead of config | Low | When adding config system |
| TD-2 | `src/auth/session.ts:12` | In-memory session store | Medium | Before horizontal scaling |Severity levels:
- Low — Cosmetic or minor maintainability issue
- Medium — Will cause problems at scale or in specific scenarios
- High — Actively impeding development or risking production issues
Payback Trigger — The condition or event that should trigger debt repayment (e.g., "before launch", "when adding feature X", "before scaling past N users").
Only log genuine debt — intentional shortcuts with known consequences. Not everything imperfect is debt.
Progress Reporting
After each task, report:
Task: [description]
Status: Complete
Phase Progress: N/M tasks
Overall: X% completeCross-Skill Dispatch
At Track Completion (Step 6)
After announcing track completion, suggest relevant follow-ups based on context:
If track modifies production code:
"Track complete! Consider:
→ /draft:deploy-checklist — Pre-deployment verification"If track added new APIs/services/components:
→ /draft:documentation — Update documentation for new components"If implementation contains TODO/FIXME/HACK comments:
→ /draft:tech-debt — Catalog any new technical debt introduced"If new patterns or dependencies not in tech-stack.md:
→ /draft:adr — Document this design decision"Jira Sync at Completion
If Jira ticket linked, sync via core/shared/jira-sync.md:
- Post comment: "[draft] implementation-complete: All {n} tasks done. Ready for review."
Bug Track with rca.md
If implementing a bug track and draft/tracks/<id>/rca.md exists:
- Load rca.md as context for the implementation
- Reference root cause, blast radius, and prevention items during fix
- After fix: update rca.md "Proposed Fix" section with actual fix details
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

