Implementation

/implementation [target]

Implement code from the approved plan. Strict constraints enforced.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"implement","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Write code a master craftsperson would be proud of.

Code must look like it was written by a skilled human engineer, not generated by AI.

AI Antipatterns to REJECT

Human Craft to ACHIEVE

• Code that reads like well-written prose
• Functions that do exactly one thing, perfectly
• Names that reveal intent without comments
• Structure that guides the reader naturally
• Simplicity that clearly took effort to achieve
• Every line earns its place

Test: Would a senior engineer mass-delete your code in review? If yes, don't write it.

⚠️ STRICT REQUIREMENTS - NO JUDGMENT CALLS

You MUST follow these constraints EXACTLY:

1. MAX 30 LINES PER FUNCTION - No function may exceed 30 lines. Split if needed.
2. MAX 300 LINES PER FILE - Split into modules if approaching limit.
3. MAX COMPLEXITY 10 - Cyclomatic complexity ≤10 per function. Flatten with early returns, extract helpers.
4. ONE FILE PER CONCERN - No god files. Each file has one purpose.
5. SEARCH BEFORE CREATE - Before writing a utility function, search for existing implementations:
   • Check utils/, lib/, helpers/, common/ directories
   • grep -r "function copyDir" --include="*.ts" (or similar)
   • If similar exists, import it. Don't recreate.
6. FOLLOW THE PLAN - Create exactly the files/functions listed in the plan. No extras.
7. MEANINGFUL NAMES - Variables/functions must describe what they do.
8. NO HARDCODED VALUES - Use constants or config for magic numbers/strings.
9. HANDLE ALL ERRORS - Every operation that can fail must have error handling.
10. MINIMIZE FILES — Combine related concerns into single files. A module that does load/save/encrypt for one data format is ONE file, not three. Only split when a file exceeds 300 lines or serves genuinely independent consumers.
11. MINIMIZE TYPES — If a type is only used in one file, define it there. Shared types go in a types file only when 3+ files import them.
12. DIRECT DATA FLOW — If a value must pass through >2 function signatures to reach where it's used, restructure. Data should flow naturally, not be threaded.

FORBIDDEN (Phase will FAIL if detected):

• Functions longer than 30 lines
• Files longer than 300 lines
• Cyclomatic complexity > 10 (too many branches/paths)
• Vague names: data, result, temp, item, stuff, info, obj
• Multiple concerns in one file
• Recreating utilities that already exist in the codebase
• Hardcoded configuration values
• Ignored error cases
• Features not in the plan

Process

Step 0: Load Expert Guidance

Before starting, read these canon skills and apply their principles throughout:

Always load (base brain — all 10):

1. canon/clarity/SUMMARY.md
2. canon/pragmatism/SUMMARY.md
3. canon/simplicity/SUMMARY.md
4. canon/composition/SUMMARY.md
5. canon/distributed/SUMMARY.md
6. canon/data-first/SUMMARY.md
7. canon/correctness/SUMMARY.md
8. canon/algorithms/SUMMARY.md
9. canon/abstraction/SUMMARY.md
10. canon/optimization/SUMMARY.md

Auto-detect domain canon (check files, load matches):

If a skill file doesn't exist (not installed in this project), skip it and continue. List loaded experts in EXPERTS_LOADED. In EXPERT_DECISIONS, show each specific decision an expert drove with file:line.

Step 0b: Learn From Past Mistakes

Read both lessons files if they exist:

1. .claude/universal-lessons.md — universal patterns (ships with skills, applies to all projects)
2. .claude/lessons.md — project-specific patterns (accumulated from this project's runs)

Apply these lessons as you write code:

• LOGIC entries → avoid these exact bug patterns (e.g., never pair existsSync+readFileSync — use try-catch; never use execSync with template literals — use execFileSync with args array; validate names before path.join; escape </ in embedded JSON)
• CODE_QUALITY entries → avoid dead exports, unused imports, redundant verification reads
• DESIGN entries → respect size limits, avoid unbounded lists from user-controlled input
• AI_SMELL entries → do NOT generate these antipatterns: no single-use helpers, no JSDoc restating function names, no null checks on typed params, no speculative types/config, no empty catch blocks

This is the most impactful phase for preventing recurring issues. Check each LOGIC entry against your implementation.

If a file doesn't exist, skip it and continue.

Step 1: Load Plan

1. Load Plan - Read plan from .claude/plans/ or context
2. Check Structure - Verify types/interfaces exist from /structure
3. Extract Units - Break the plan into implementation units (one file or one logical group of tightly-coupled functions)

Step 2: Compile Loop (Unit by Unit)

Phase 3 is a builder AND a quality compiler. Code isn't done until it compiles clean.

For each unit from the plan:

2a. Canon refresh

Before writing this unit, reread the ONE canon SUMMARY.md most relevant to what this unit does:

• File I/O, errors, external calls → canon/correctness/SUMMARY.md
• API surface, public types → canon/simplicity/SUMMARY.md
• Data structures, schemas → canon/data-first/SUMMARY.md
• Multi-module interaction → canon/composition/SUMMARY.md
• Auth, secrets, user input → canon/security/security-mindset/SUMMARY.md
• Performance-critical → canon/optimization/SUMMARY.md
• Complex algorithms → canon/algorithms/SUMMARY.md
• UI components, templates → best match from loaded UI/UX canon
• Database queries, ORM → best match from loaded database canon
• Reactive/observable patterns → canon/angular/rxjs/SUMMARY.md or canon/javascript/reactivity/SUMMARY.md
• General / unclear → canon/clarity/SUMMARY.md

This is not optional. Read the file. 50 lines, <1 second. It refreshes the design principle before you write, not after.

2a½. Read plan constraint

Read the Constraint: from the plan for the current work item. If it includes an abstract type tag (e.g., [ValidatedInput + CausedError]), implement the contract using the target language's idiom from .claude/rubric/contracts.md. The BAD/GOOD example shows the specific boundary; the abstract type tells you the pattern. Apply it alongside the canon summary from Step 2a.

2a¾. Implement contract (if tagged)

If the work item constraint includes an abstract type tag, implement it:

Use the Language Idioms table from .claude/rubric/contracts.md for the target language.

2b. Write the unit

Implement the code for this unit following all constraints above.

2c. Compile check

After writing each unit, run:

npx tsc --noEmit 2>&1 | head -30
tsx scripts/quality-gate.ts {FILES_JUST_WRITTEN}

Also self-check: no function > 30 lines, no file > 300 lines.

2d. Fix or proceed

• Clean: Move to the next unit.
• Errors: Fix them NOW. You have full context — this is when fixing is cheapest. Re-run checks. Max 2 fix attempts per unit.
• Still failing after 2 attempts: Note the issue, move on, report at end.

The point: a bad type in file A cascades through files B-E. Catching it after A prevents rewriting B-E.

Step 3: Final Verification

After all units pass the compile loop:

1. Full type check:

   npx tsc --noEmit
   

2. Dead Code Cleanup - Remove any dead code introduced (see below)

WORK_ITEMS Tracking (MANDATORY)

If the plan has a WORK_ITEMS section, you MUST:

1. Read all WORK_ITEMS from the plan before starting
2. Work through every item — do not skip or triage
3. Report status of each item in your output
4. If you run out of context, report remaining items so the orchestrator can re-run you

REQUIRED Output Format

## Implementation: [feature]

FILES_CREATED:
- path/to/file.ts: [functions defined]

LONGEST_FUNCTION: [name] at [N] lines (must be ≤30)

### Verification:
```bash
$ npx tsc --noEmit
(no errors)

Dead Code Cleanup:

TOOL_USED: [knip|qodana|vulture|deadcode|cargo-udeps] DEAD_CODE_FOUND: [N] items DEAD_CODE_REMOVED: [list or "none"]

Work Items:

COMPLETED:

• WI-1: [what was done]
• WI-2: [what was done]

REMAINING:

• WI-5: [not started — reason]

COMPILE_LOOP: {N} units, {M} required fixes, {K} canon refreshes

EXPERTS_LOADED: [list of skill names actually read] EXPERT_DECISIONS:

• [expert-skill]: [specific decision it drove, with file:line]

IMPLEMENTATION_COMPLETE

**REMAINING must be empty for IMPLEMENTATION_COMPLETE.** If items remain, output IMPLEMENTATION_PARTIAL instead and list what's left.

## Dead Code Cleanup (MANDATORY)

After implementation, detect language and remove dead code:

| Language | Detection | Tool | Command |
|----------|-----------|------|---------|
| JS/TS | `package.json` | knip | `npx knip --reporter compact` |
| Java | `pom.xml` or `build.gradle` | Qodana | Use `mcp__qodana__qodana_scan` |
| Python | `pyproject.toml` or `*.py` | vulture | `uvx vulture . --min-confidence 80` |
| Go | `go.mod` | deadcode | `go run golang.org/x/tools/cmd/deadcode@latest ./...` |
| Rust | `Cargo.toml` | cargo-udeps | `cargo +nightly udeps` |
| C# | `*.csproj` | Qodana | Use `mcp__qodana__qodana_scan` |

**Process:**
1. Run the appropriate tool for the detected language
2. Parse output for unused exports, functions, imports, variables
3. Remove dead code directly (no confirmation needed for code YOU just wrote)
4. Re-run tool to verify cleanup

<critical>Only remove dead code in files YOU modified during this implementation. Never touch unrelated files.</critical>

Skip items marked with `@keep`, `// keep`, or `# keep`.

## Validation (Phase will FAIL if violated)

- Any function > 30 lines
- Any file > 300 lines
- Any function with cyclomatic complexity > 10
- Vague variable names detected
- Duplicated utility that exists elsewhere in codebase
- Files not in plan created without justification
- Dead code left behind in files you created/modified

## 🛑 MANDATORY STOP

After implementation:
- DO NOT proceed to next phase
- DO NOT continue with "let me also..."

**Your turn ends here.** Output IMPLEMENTATION_COMPLETE and STOP.