implementation

name	implementation
description	Implement code from plan. Max 30 lines per function. No vague names.

/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

Antipattern	Example	Why It's Wrong
Over-abstraction	Factory that creates one thing	Abstraction without justification
Defensive paranoia	Null checks where null is impossible	Implies you don't understand your own code
Reimplementing stdlib	Custom string utils when lodash exists	Arrogance or ignorance
Comment spam	// increment counter above i++	Insulting the reader
Speculative features	Config options nobody asked for	Solving imaginary problems
Wrapper classes	UserWrapper around User	Complexity without value
Enterprise patterns	AbstractFactoryBean for a helper	Cargo-culting

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):

Check	If found, also read
*.ts or *.js files in target	canon/javascript/typescript/SUMMARY.md, canon/javascript/js-safety/SUMMARY.md, canon/javascript/js-perf/SUMMARY.md, canon/javascript/js-internals/SUMMARY.md, canon/javascript/functional/SUMMARY.md
angular.json in project root	canon/angular/angular-arch/SUMMARY.md, canon/angular/angular-core/SUMMARY.md, canon/angular/angular-perf/SUMMARY.md, canon/angular/rxjs/SUMMARY.md
package.json contains "react"	canon/javascript/react-state/SUMMARY.md, canon/javascript/react-test/SUMMARY.md, canon/javascript/reactivity/SUMMARY.md
pom.xml or build.gradle in project	canon/java/SUMMARY.md
*.py files in target	canon/python/python-advanced/SUMMARY.md, canon/python/python-idioms/SUMMARY.md, canon/python/python-patterns/SUMMARY.md, canon/python/python-protocols/SUMMARY.md
*.cs files or *.csproj in project	canon/csharp/csharp-depth/SUMMARY.md, canon/csharp/type-systems/SUMMARY.md, canon/csharp/async/SUMMARY.md
.tsx, .jsx, or HTML template files	canon/ui-ux/components/SUMMARY.md, canon/ui-ux/usability/SUMMARY.md, canon/ui-ux/tokens/SUMMARY.md
d3 in package.json or imports	canon/visualization/d3/SUMMARY.md, canon/visualization/charts/SUMMARY.md, canon/visualization/dashboards/SUMMARY.md
SQL files or ORM imports	canon/database/sql/SUMMARY.md,

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: Check Known Pitfalls

Read canon/pitfalls/SKILL.md if it exists. Apply its patterns as you work:

• Logic Traps → avoid these exact bug patterns (TOCTOU, shell injection, path traversal, XSS in embedded JSON)
• Code Quality Traps → avoid dead exports, unused imports, redundant verification reads
• Design Traps → respect size limits, avoid unbounded lists from user-controlled input
• AI-Generated Antipatterns → do NOT generate these: 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 Trap against your implementation.

If the 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:

Abstract Type	What to implement
ValidatedInput	Validation function at boundary. Function signature accepts validated type, not raw.
SafePath	Path factory that normalizes + checks prefix. Never pass raw user string to path.join.
CausedError	Error construction with { cause: e }. Never throw new Error(msg) in a catch block.
Secret	Opaque type. toString/toJSON must redact. Never interpolate into error messages or logs.
ExternalData	Parse in try-catch. Validate structure before use. Never assume shape.
BoundedOperation	Timeout parameter or max iterations. Never recurse/loop without a bound.
IdempotentAction	Write-then-rename for files. Transactions for DB. Never partial-write.

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.