| name | code-craft |
| description | Code design discipline enforcing SOLID, KISS, DRY, modularity, separation of concerns, and human-readability during implementation. Load for any non-trivial code write, feature addition, refactor, or restructuring. Covers: clean code, design patterns, decomposition, dependency management, naming, and architecture at the function/class/module level. Activate on "refactor", "restructure", "design this module", "clean up this code", "make this maintainable", "decompose", "extract", or any implementation touching more than one file. |
Code Craft
Implementation workflow for non-trivial code. Hard constraints (naming, nesting, prohibited patterns, debt markers) live in always-on rules/code-quality.md and rules/tdd.md — obey them; do not restate them here.
Skip only for: typos, formatting, config values, renames with no logic change.
Progressive disclosure: load refs only when the phase needs them.
| When | Load |
|---|
| Writing implementation (Phase 3) | references/write-standards.md |
| Tempted by a shortcut | references/anti-patterns.md |
Workflow (5 phases — all required for non-trivial work)
Phase 1 — Design Intent (before writing)
Produce this block:
DESIGN INTENT
=============
Unit name :
Responsibility : [one sentence, no "and"]
Caller interface: [in → out]
Glossary Sync : yes/no
Interface contract: [signature / schema]
Docstring Spec : yes/no
Interface sign-off: yes/no/assumed-approved (AFK only)
Module README : yes/no/updated
Dependencies :
Quality tools : [repo-native commands first]
Complexity guard:
Isolation test : yes/no
Error budget :
Failure contract:
Ambiguity policy:
Traceability :
STOP if: isolation = no → redesign; interface sign-off = no (interactive) → get approval; edge-case semantics unspecified → ask (AFK: fail closed, do not invent fallbacks).
Phase 2 — SOLID checklist (before writing)
| Check | Pass? |
|---|
| S — one responsibility | ☐ |
| O — extend without rewrite | ☐ |
| L — no weakened contracts | ☐ / N/A |
| I — minimal public surface | ☐ |
| D — depend on abstractions | ☐ |
| Docstrings on public APIs | ☐ |
| Deep modules (no shallow 1–3 line helpers) | ☐ |
| YAGNI | ☐ |
| SoC — logic free of framework/IO details | ☐ |
| Complexity budget OK | ☐ |
Unchecked → fix or // TODO(debt):.
Phase 3 — Write
- Obey
rules/code-quality.md + rules/tdd.md (RED → GREEN → REFACTOR; post test output).
- Load
references/write-standards.md for: defensive boundaries, immutability, invariants, types, quality tooling pass, docstrings, abstraction rules.
- Prefer repo-native
make / scripts over ad-hoc tool installs.
Phase 4 — Readability audit
As a new engineer: entry point, flow by names, side effects, error path, resilience, ambiguity handling, metric smells, docstrings, deep helpers. Fix or // CLARITY:. Create/update module README.md when the public surface or responsibility changes.
Phase 5 — Tech debt inventory
TECH DEBT INVENTORY
===================
[none]
— OR —
- TODO(debt): [where] — [what] — [why deferred] — [cleanup trigger]
Deliverable
