diff --git a/README.md b/README.md index 78027f2..acdc69f 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Everything is branched so it loads only when it is relevant, keeping context lea | Loaded | What | Where it lands | |---|---|---| -| **Always-on** | `working-style` — propose-before-implementing, a question isn't a work order, report honestly, flag reusable logic | `.claude/standards/`, imported by `CLAUDE.md` | +| **Always-on** | `working-style` — propose-before-implementing, a question isn't a work order, report honestly, flag reusable logic, scope discipline & the simplest solution | `.claude/standards/`, imported by `CLAUDE.md` | | **When editing `*.py`** | `python` — 3.13+, type hints, PEP 695, `uv`, structured logging, definition ordering, suppression discipline, async safety | `.claude/rules/` | | **When editing `*.py`** (opt-in) | `scalable-architecture` — ports-and-adapters, dependency injection, boundary validation, idempotent writes; patterns for services/larger apps | `.claude/rules/` | | **When editing `*.md`** | `prose-and-docs` — no historical narration, verify before documenting, voice, ordering, RFC-2119 & leanness | `.claude/rules/` | diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 70adc28..4dd0815 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { "name": "preflight", "description": "Starter kit of reusable AI-agent standards, personas, and workflows. Run /preflight:setup to scaffold editable copies into a project.", - "version": "0.1.0" + "version": "0.2.0" } diff --git a/plugin/templates/standards/working-style.md b/plugin/templates/standards/working-style.md index 3362f42..cc5f531 100644 --- a/plugin/templates/standards/working-style.md +++ b/plugin/templates/standards/working-style.md @@ -16,6 +16,25 @@ These apply to every task. They are deliberately short — this file is always i - **Flag reusable logic.** When generic utility code (transforms, math helpers, shared parsing) is buried as a private method in one module, raise it: propose extracting it to a shared location so there is one source of truth. +- **Prefer the simplest solution.** Backward-compatibility shims, dead code paths, and versioning + that nothing depends on are maintenance cost, not safety — don't add them. Keep compatibility only + where a real consumer relies on it: a versioned or published API, an SLA, a production pipeline, or + a persisted data format with outside callers. When it is genuinely unclear whether something still + depends on the old behaviour, ask instead of defensively keeping both paths. +- **Solve the specific ask, not its generalization.** When a task names a concrete need, implement + exactly that; don't build the generalized version — every case handled, exposed everywhere — + until a second concrete caller exists. A seam at an I/O boundary for testability or genuine + swappability is a present need, not speculative generality — the `scalable-architecture` rule + governs that call where a project follows it. +- **Don't re-derive what the input already states.** Before writing code to compute, select, or + reconstruct a value, check whether the source data already states it authoritatively — if it does, + read and apply it rather than adding a second source of truth that can drift. +- **Name the defect in one sentence, then make that sentence false.** Write the current wrong + behaviour as one sentence and let the smallest change that falsifies it bound the fix — "stop + discarding the table" stays small where "add X support" invites machinery. +- **Justify each touched file against the requirement, not architectural symmetry.** Mirror the + shape of existing patterns, not their breadth — that one feature spans a frame, a schema, meta, and + inventory usage does not mean a related change must touch all four. - **Confirm destructive or outward-facing actions** unless already authorized. Before deleting or overwriting something you did not create, look at it first; if it contradicts how it was described, surface that instead of proceeding.