code-craft

Language- and framework-specific code best practices and idiom reference. Complements compass (stack-agnostic architecture / design coach) — code-craft is tactical and per-language.

Quick start

1. Detect the language or framework from the user's request — explicit (ts, dart, flutter) or inferred from file extension / pasted code.
2. Detect the mode:
   • reader — user asks "what is the best practice for X" or "how should I do Y in Z" → return matching rules from the language file (rule + reason + example).
   • reviewer — user pastes code or asks "review this" → load the relevant language file, scan for violations, report location → rule → fix.
3. Load only the relevant file from languages/ (and a frameworks/ file if applicable). When the code touches a store (database, SQLite file, KV), also load general/data-access.md: its rules apply in every stack.
4. Match the topic the user asked about — do not dump the entire language file when the user asked one question.

Supported

If the user asks for a language not yet supported, say so and offer to add a stub via the structure documented below.

When to defer to compass

Defer to compass if the user asks about:

• Architecture / system design
• SOLID, GoF patterns, MVC, microservices
• Refactoring strategy across modules
• TDD / CI/CD / DevOps
• Stack selection or technology trade-offs
• Security model, threat surface, perf budget

code-craft is for inside-the-file decisions. compass is for across-file / across-system decisions. When a user request straddles both, route the language-idiom parts here and the architecture parts to compass.

Reader-mode output format

For a single-rule ask:

Rule. Reason. Wrong vs. right example (3–6 lines).

For a topic ask (e.g. "TS error handling"), return the 3–6 most relevant rules in the same compact format, ordered by importance. Cite the source when there is genuine community debate (enums, barrel files, etc.).

Reviewer-mode output format

Flat numbered list, one violation per line:

1. <file>:<line> — <rule short name> — <one-sentence fix>
2. ...

If the list is long, group by severity:

• must-fix — correctness or safety bugs
• should-fix — idiom or maintainability
• nice-to-have — style only

Close with a one-sentence summary. Do not re-print the user's code.

Adding a new language or framework file

1. Create languages/<lang>.md or frameworks/<framework>.md.
2. Group rules under buckets that fit the language — typical: tactical (day-to-day), idioms (ecosystem patterns), anti-patterns (smells).
3. Each rule:
   • Short name (1–6 words)
   • One-sentence rule
   • One-line reason
   • ≤ 6-line wrong + right example
   • Source citation if there is debate
4. Update the Supported table above.
5. Aim for 30–60 rules per language file. Quality over quantity.

Confirmation discipline

• Reader mode: no confirmation needed; just answer.
• Reviewer mode: confirm scope before scanning ("idioms only, or include anti-patterns?"). Default to both. Security and performance reviews belong in compass — route there if asked.

When to skip code-craft

• One-line tweaks (rename, fix typo, add import).
• Throwaway scripts / spikes.
• Generated code (migrations, codegen output, build artifacts).
• Language not in the Supported table — say so, don't fabricate rules from training data.
• User asks about architecture, security, or perf — route to compass instead.

Pipeline placement

grill-me → to-prd → compass → blueprint → code (+ code-craft) → compass (review)

code-craft sits during the code phase, applied tactically per-file as code lands. Use cases:

• Drafting — when writing new code in a supported stack, apply rules silently to the just-written diff and self-correct before showing it.
• PR review — alongside compass's reviewer workflow, run code-craft on the diff for stack-specific idiom violations.

code-craft does NOT replace compass's reviewer workflow. They run side-by-side at PR time: compass for cross-file architecture, code-craft for inside-file idioms.