From f6a4b3c3d656425502ac5c81fe6b358bda99108c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 29 Aug 2026 09:29:32 +0000 Subject: [PATCH 1/3] Add "prefer the simplest solution" to the always-on working-style standard Encode a standing principle against over-engineering for backward compatibility that nothing depends on. The default is the simplest design; compatibility is preserved only where a real consumer relies on it (a versioned/published API, an SLA, a production pipeline, or a persisted data format), and genuine uncertainty is resolved by asking rather than keeping both code paths. Update the README summary of working-style to match, and bump the plugin version so /preflight:update surfaces the change to already-scaffolded projects. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01TsB9nGcmkk7WtAqfQ5Mq61 --- README.md | 2 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/templates/standards/working-style.md | 6 ++++++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 78027f2..defb589 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, prefer 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..d811371 100644 --- a/plugin/templates/standards/working-style.md +++ b/plugin/templates/standards/working-style.md @@ -16,6 +16,12 @@ 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.** Solve the problem in front of you, not a hypothetical future + one. Do NOT preserve backward compatibility, keep dead code paths, or add versioning that nothing + depends on — unused compatibility is maintenance cost, not safety. Keep it 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 depends on the + old behaviour, ask instead of defensively keeping both paths. - **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. From 9b2718842e63a90489ad987ab1ad92f64231537b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 29 Aug 2026 09:49:44 +0000 Subject: [PATCH 2/3] Expand working-style scope discipline with four minimalism directives The always-on standard had one bullet on preferring simplicity but nothing on scope minimalism during implementation, while scalable-architecture nudges toward adding structure. Add four directives so the counterweight is in context on every task: solve the specific ask (not its generalization until a second caller exists), don't re-derive what the input already states, bound the fix by a one-sentence statement of the defect, and justify each touched file against the requirement rather than architectural symmetry. Refocus the existing "prefer the simplest solution" bullet on backward compatibility so it doesn't overlap the new generalization directive, and update the README summary. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01TsB9nGcmkk7WtAqfQ5Mq61 --- README.md | 2 +- plugin/templates/standards/working-style.md | 23 +++++++++++++++------ 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index defb589..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, prefer the simplest solution | `.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/templates/standards/working-style.md b/plugin/templates/standards/working-style.md index d811371..4fdc721 100644 --- a/plugin/templates/standards/working-style.md +++ b/plugin/templates/standards/working-style.md @@ -16,12 +16,23 @@ 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.** Solve the problem in front of you, not a hypothetical future - one. Do NOT preserve backward compatibility, keep dead code paths, or add versioning that nothing - depends on — unused compatibility is maintenance cost, not safety. Keep it 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 depends on the - old behaviour, ask instead of defensively keeping both paths. +- **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; MUST NOT build the generalized version — every case handled, exposed everywhere — + until a second concrete caller exists. +- **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. From 24ed246dee57f962861b2a47b1e8d7170e62e853 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 29 Aug 2026 09:56:40 +0000 Subject: [PATCH 3/3] Reconcile generalization directive with scalable-architecture seams The "solve the specific ask" bullet's absolute rule-of-two forbade the single-implementation interface that scalable-architecture intentionally permits for test fakes and swappable I/O boundaries. Soften MUST NOT to a heuristic and carve out I/O seams as a present need governed by that rule, keeping the anti-over-build teeth for feature generality. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01TsB9nGcmkk7WtAqfQ5Mq61 --- plugin/templates/standards/working-style.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/plugin/templates/standards/working-style.md b/plugin/templates/standards/working-style.md index 4fdc721..cc5f531 100644 --- a/plugin/templates/standards/working-style.md +++ b/plugin/templates/standards/working-style.md @@ -22,8 +22,10 @@ These apply to every task. They are deliberately short — this file is always i 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; MUST NOT build the generalized version — every case handled, exposed everywhere — - until a second concrete caller exists. + 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.