From 80f87fb8b99a02ecc6bce378bda803206b84c577 Mon Sep 17 00:00:00 2001 From: Guillaume Ferrari Date: Fri, 9 Oct 2026 12:19:57 +0000 Subject: [PATCH] release: v1.13.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bump both manifests and the state file, sweep the generated-by signature across 122 files, finalize the CHANGELOG heading, add the migration entry. README reviewed on the three fronts. Skill-list drift: none, fifteen skills listed, and the new generated output INBOX.md is in What's generated. Justification drift: this release adds a convention, so the practices table gains a 'capture is free, deciding is not' row with Allen's capture/clarify split as its reference. References: updated with it. Mechanical checks green: check-adr-index 48/48, validate-runner 14/14. The eval suite was run case by case through skill-creator's method, as in 1.12.0 — and the CLI runner is no longer gated, which is a finding for its own change rather than this release's: our cases are in skill-creator's JSON format and claude plugin eval now looks for its own directory format, so it reports no cases found. ADR 0042 anticipated exactly this and said to transpose back when the gate opened. --- .claude-plugin/marketplace.json | 4 ++-- .claude-plugin/plugin.json | 2 +- .claude/rules/plugin-meta.md | 2 +- .github/workflows/adr-index.yml | 2 +- .groundrules.json | 8 +++++++- CHANGELOG.md | 4 ++-- CLAUDE.md | 2 +- PLAN.md | 2 +- README.md | 2 ++ docs/AGENT-EVALS.md | 2 +- docs/ARCHITECTURE.md | 2 +- docs/CONTEXT-ECONOMY.md | 2 +- docs/LEARNINGS.md | 2 +- docs/ROADMAP.md | 2 +- docs/VISION.md | 2 +- docs/best-practices-pending.md | 2 +- docs/decisions/0000-template.md | 2 +- docs/decisions/0001-marketplace-json-location.md | 2 +- .../decisions/0002-plain-text-placeholder-substitution.md | 2 +- docs/decisions/0003-multi-skill-architecture.md | 2 +- docs/decisions/0004-starter-kit-json-schema.md | 2 +- .../0005-intent-capture-and-apply-best-practices.md | 2 +- docs/decisions/0006-optional-specialized-docs.md | 2 +- docs/decisions/0007-denumber-entry-docs.md | 2 +- docs/decisions/0008-adopt-brownfield-projects.md | 2 +- docs/decisions/0009-global-claude-md-awareness.md | 2 +- .../decisions/0010-managed-project-claude-md-deference.md | 2 +- docs/decisions/0011-detect-no-ai-attribution-policy.md | 2 +- docs/decisions/0012-english-only.md | 2 +- docs/decisions/0013-media-under-docs.md | 2 +- docs/decisions/0014-rename-brief-to-intake.md | 2 +- docs/decisions/0015-best-effort-update-check.md | 2 +- docs/decisions/0016-rename-marketplace.md | 2 +- docs/decisions/0017-plugin-rename-at-v1.md | 2 +- docs/decisions/0018-adopt-consolidation-mode.md | 2 +- docs/decisions/0019-heyjoe-inspired-doc-improvements.md | 2 +- docs/decisions/0020-repo-is-the-only-memory.md | 2 +- .../0021-context-economy-index-over-doc-search.md | 2 +- docs/decisions/0022-agent-evals-and-session-close.md | 2 +- docs/decisions/0023-project-scope-for-team-portability.md | 2 +- docs/decisions/0024-slim-skill-claude-md-budget.md | 2 +- docs/decisions/0025-no-runtime-hook-no-watch.md | 2 +- docs/decisions/0026-posture-and-per-feature-prd.md | 2 +- .../0027-reflection-realization-interactive-loop.md | 2 +- docs/decisions/0028-git-workflow-conventions.md | 2 +- docs/decisions/0029-content-aware-claude-md-tailoring.md | 2 +- docs/decisions/0030-loop-namespace-and-backlog.md | 2 +- .../0031-goal-interop-swappable-loop-executor.md | 2 +- docs/decisions/0032-premortem-anti-sycophancy.md | 2 +- docs/decisions/0033-adopt-full-mode.md | 2 +- docs/decisions/0034-posture-keep-the-diff-small.md | 2 +- docs/decisions/0035-no-auto-capture-memory-layer.md | 2 +- docs/decisions/0036-git-workflow-corrected.md | 2 +- docs/decisions/0037-executable-evals-over-agent-config.md | 2 +- docs/decisions/0038-close-reconcile-plan-against-diff.md | 2 +- docs/decisions/0039-conditional-superpowers-interop.md | 2 +- docs/decisions/0040-three-bootstrap-modes.md | 2 +- .../0041-a-migration-never-damages-a-correct-file.md | 2 +- .../decisions/0042-skill-creator-harness-as-the-runner.md | 2 +- docs/decisions/0043-probed-not-validated.md | 2 +- docs/decisions/0044-runner-enforces-verifier-isolation.md | 2 +- docs/decisions/0045-the-lock-was-scoped-to-four-skills.md | 2 +- docs/decisions/0046-orchestrated-working-regime.md | 2 +- docs/decisions/0047-agents-md-deferred-to-m2.md | 2 +- .../0048-the-convention-here-the-transport-elsewhere.md | 2 +- docs/decisions/README.md | 2 +- docs/media/README.md | 2 +- docs/prd/adoption-log.md | 2 +- docs/prd/backward-crossing-convention.md | 2 +- docs/prd/content-aware-claude-md-tailoring.md | 2 +- docs/prd/goal-interop.md | 2 +- docs/prd/loop-minimal-runnable.md | 2 +- docs/prd/loop-scaffolding-bootstrap-adopt.md | 2 +- docs/prd/loop-walkthrough.md | 2 +- docs/prd/realize-skill.md | 2 +- docs/prd/tdd-gate.md | 2 +- docs/prd/template-refinement-regimes.md | 2 +- docs/prd/vision-skill.md | 2 +- docs/prototypes/loop/LOOP.md | 2 +- docs/prototypes/loop/README.md | 2 +- docs/prototypes/loop/fixture/TODO.md | 2 +- docs/prototypes/loop/maker.md | 2 +- docs/prototypes/loop/verifier.md | 2 +- evals/README.md | 2 +- intake/INTENT.md | 2 +- intake/README.md | 2 +- skills/apply-best-practices/SKILL.md | 2 +- skills/bootstrap/SKILL.md | 2 +- skills/bootstrap/templates/ADOPTION-LOG.md.tpl | 2 +- skills/bootstrap/templates/AGENT-EVALS.md.tpl | 2 +- skills/bootstrap/templates/ARCHITECTURE.md.tpl | 2 +- skills/bootstrap/templates/CHANGELOG.md.tpl | 2 +- skills/bootstrap/templates/CLAUDE.md.tpl | 2 +- skills/bootstrap/templates/DATA_MODEL.md.tpl | 2 +- skills/bootstrap/templates/DESIGN_SYSTEM.md.tpl | 2 +- skills/bootstrap/templates/GLOSSARY.md.tpl | 2 +- skills/bootstrap/templates/I18N.md.tpl | 2 +- skills/bootstrap/templates/INBOX.md.tpl | 2 +- skills/bootstrap/templates/LEARNINGS.md.tpl | 2 +- skills/bootstrap/templates/PLAN.md.tpl | 2 +- skills/bootstrap/templates/PRD.md.tpl | 2 +- skills/bootstrap/templates/PROCESS.md.tpl | 2 +- skills/bootstrap/templates/README.md.tpl | 2 +- skills/bootstrap/templates/RELEASE.md.tpl | 2 +- skills/bootstrap/templates/ROADMAP.md.tpl | 2 +- skills/bootstrap/templates/SECURITY.md.tpl | 2 +- skills/bootstrap/templates/adr-template.md | 2 +- skills/bootstrap/templates/decisions-README.md.tpl | 2 +- skills/bootstrap/templates/docs-VISION.md.tpl | 2 +- skills/bootstrap/templates/intake-INTENT.md.tpl | 2 +- skills/bootstrap/templates/intake-README.md.tpl | 2 +- skills/bootstrap/templates/loop/CLAUDE-invariants.md | 2 +- skills/bootstrap/templates/loop/LOOP.md | 2 +- skills/bootstrap/templates/loop/README.md.tpl | 2 +- skills/bootstrap/templates/loop/backlog.md | 2 +- skills/bootstrap/templates/loop/maker.md | 2 +- skills/bootstrap/templates/loop/verifier.md | 2 +- skills/bootstrap/templates/media-README.md.tpl | 2 +- skills/verify-bootstrap/SKILL.md | 2 +- test/check-adr-index.sh | 2 +- test/loop/QUICKSTART.md | 2 +- test/loop/README.md | 2 +- test/loop/TUTORIAL.md | 2 +- test/loop/WALKTHROUGH.md | 2 +- test/loop/fixtures/game-of-life/PRD.md | 2 +- test/loop/fixtures/sample-plan.md | 2 +- 126 files changed, 135 insertions(+), 127 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 97864eb..d283a7d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,14 +6,14 @@ }, "metadata": { "description": "Mono-plugin marketplace for the groundrules Claude Code plugin (formerly starter-kit)", - "version": "1.12.0" + "version": "1.13.0" }, "plugins": [ { "name": "groundrules", "source": "./", "description": "Interactive bootstrap of Claude Code projects — docs structure + best practices of documentation and configuration", - "version": "1.12.0", + "version": "1.13.0", "category": "scaffold" } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index faf158d..b0007fc 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "groundrules", - "version": "1.12.0", + "version": "1.13.0", "description": "Interactive bootstrap of Claude Code projects: interview, docs/ structure, best practices of documentation and configuration, git init, optional remote.", "author": { "name": "Guillaume Ferrari", diff --git a/.claude/rules/plugin-meta.md b/.claude/rules/plugin-meta.md index b13fd1f..ee81391 100644 --- a/.claude/rules/plugin-meta.md +++ b/.claude/rules/plugin-meta.md @@ -4,7 +4,7 @@ paths: - "skills/**" - "**/*.tpl" --- - + # Plugin meta-development rules diff --git a/.github/workflows/adr-index.yml b/.github/workflows/adr-index.yml index 0cbd709..f84124b 100644 --- a/.github/workflows/adr-index.yml +++ b/.github/workflows/adr-index.yml @@ -1,4 +1,4 @@ -# generated-by: groundrules v1.12.0 +# generated-by: groundrules v1.13.0 # # The ADR index invariant, checked where the omission lands: a pull request. # diff --git a/.groundrules.json b/.groundrules.json index 0a1f695..081f88c 100644 --- a/.groundrules.json +++ b/.groundrules.json @@ -1,5 +1,5 @@ { - "groundrulesVersion": "1.12.0", + "groundrulesVersion": "1.13.0", "bootstrappedAt": "2026-05-11", "bootstrappedWithVersion": "0.1.0", "migrations": [ @@ -164,6 +164,12 @@ "to": "1.12.0", "at": "2026-09-11", "note": "V1.12 the loop's verifier becomes genuinely independent (ADR 0044): run-loop.sh makes TWO invocations per iteration — a maker pass that leaves its work uncommitted, then a separate verifier pass with a fresh context that judges the working tree and holds the write; validate-runner.sh asserts the split by counting invocations. The verifier preamble's 'nothing else' now bars the maker's narration rather than the artifacts its own checks require. AGENT-EVALS retires 'validated' for 'watching' / 'probed: , N/N since ' (ADR 0043): a case covers one instance, never the behavioural class. The eval suite moves to skill-creator's harness, the CLI runner being gated (ADR 0042). The meta CLAUDE.md gains the Session start reading list the plugin ships to every project but never applied to itself — guards in LEARNINGS and AGENT-EVALS were unreadable here, hence unable to fire. No user-facing template change beyond the loop." + }, + { + "from": "1.12.0", + "to": "1.13.0", + "at": "2026-10-09", + "note": "V1.13 optional INBOX.md at the repository root (ADR 0048) — what was handed to the project from outside, dated and verbatim, not yet triaged; offered by bootstrap and adopt, unchecked by default, and named FIRST in the generated CLAUDE.md session-start list (no conditional: the list already marks optional entries '(if present)'). The plugin never fills it — how lines arrive is the caller's business. The request behind it asked for a SessionStart hook reading one estate's private document layout and was refused on ADR 0025 (nothing the plugin generates runs unasked) and on the rule that it never describes one estate's layout; the principle recorded is the convention here, the transport elsewhere. AGENTS.md investigated and deferred to M2 with the harness behaviour measured (ADR 0047). Dogfood: the orchestrated working regime recorded (ADR 0046, amends 0036's commit rule), 'validated' retired for 'probed' (ADR 0043), the ADR index invariant made a CI check. No other change to generated output." } ], "answers": { diff --git a/CHANGELOG.md b/CHANGELOG.md index 544ec91..ed52871 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ - + # Changelog All notable changes to this project are documented in this file. @@ -6,7 +6,7 @@ All notable changes to this project are documented in this file. Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow [Semantic Versioning](https://semver.org/). -## [Unreleased] +## [1.13.0] - 2026-10-09 ### Added - **An optional `INBOX.md`: what was handed to this project from outside, not yet triaged** ([ADR 0048](docs/decisions/0048-the-convention-here-the-transport-elsewhere.md)). Offered by `bootstrap` and `adopt`, unchecked by default, at the repository root: one dated line per subject, **verbatim**, and triage **marks** a line (`→ ADR 0012`, `→ PLAN.md`, `→ dropped`) rather than deleting it — the file is a record of what arrived, not a queue that empties. It is named **first** in the generated `CLAUDE.md`'s session-start list, before `PLAN.md`, because what arrived can change what the rest of the list means; no conditional was needed, the list already marks optional entries *(if present)*. **The plugin never fills it** — how lines get there is the caller's business, described nowhere here. diff --git a/CLAUDE.md b/CLAUDE.md index e8ecf58..89b4a09 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -82,7 +82,7 @@ Reloading after a change: a **new skill directory** requires a full restart of C ## Template conventions -- Every template carries `` at the top. +- Every template carries `` at the top. - Placeholders in `{{KEY}}` format (plain text substitution, no template engine). - Available placeholders defined in `skills/bootstrap/SKILL.md` (Phase 5). - **English-only**: one `.tpl` per file, no language suffix (cf. ADR 0012). `gitignore.minimal` and `adr-template.md` are plain files. diff --git a/PLAN.md b/PLAN.md index 00376fd..a666165 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,4 +1,4 @@ - + # PLAN — groundrules **Active** plan/todo for the project. Maintained by Claude during work. diff --git a/README.md b/README.md index 58f546e..f924244 100644 --- a/README.md +++ b/README.md @@ -216,6 +216,7 @@ Not everything here is a research result — and we won't pretend it is. Some ch | **Semantic Versioning** — `MAJOR.MINOR.PATCH` | A version number that *means something*: consumers can tell at a glance whether an update is a fix, a feature, or a breaking change. | [semver.org](https://semver.org/) | | **Test-Driven Development** — a failing test *before* the code (**loop regime only**) | When a task is handed to the autonomous loop (`/groundrules:realize`), a pre-written, currently-**red** acceptance test is the loop's back pressure: the maker makes it green, an independent verifier replays it. Red-first is Kent Beck's discipline; groundrules applies it as the *loop precondition* — **not** a global mandate (interactive work keeps the human as back pressure, handoff-not-gospel). | [Beck, *TDD by Example*](https://www.oreilly.com/library/view/test-driven-development/0321146530/) · [ADR 0027](docs/decisions/0027-reflection-realization-interactive-loop.md) | | **Reconciliation over reminders** — a doc you can't generate gets *checked* against the code | A rule that asks an agent to remember to update a record relies on attention and fails quietly; comparing the record with the code does not. Martraire calls this a **reconciliation mechanism**: where documentation can't be generated from the source, verify it against the source and report the mismatch. `/groundrules:close` applies it to `PLAN.md` — git says what changed, the plan says what it believes — and leaves the edit to a human. | [Martraire, *Living Documentation*](https://www.oreilly.com/library/view/living-documentation-continuous/9780134689418/) · [ADR 0038](docs/decisions/0038-close-reconcile-plan-against-diff.md) | +| **Capture is free, deciding is not** — an inbox separate from the plan | Writing down what arrived and deciding what it means are different acts, and fusing them makes you refuse input to avoid the decision. Allen's capture/clarify split is the standard form; groundrules applies it as an optional `INBOX.md` holding dated, verbatim lines, named first in the generated `CLAUDE.md`'s session-start list — and triage **marks** a line rather than deleting it, so the file stays a record of what arrived rather than a queue that empties. | [Allen, *Getting Things Done*](https://gettingthingsdone.com/) · [ADR 0048](docs/decisions/0048-the-convention-here-the-transport-elsewhere.md) | | **Small, surgical diffs** — simplicity first, touch only what the task needs | The smallest change that solves the *stated* problem is easier to review, revert, and reason about; speculative abstraction and drive-by refactors are liabilities, not value (the YAGNI / minimal-change craft consensus). groundrules folds it into the generated `CLAUDE.md` **Posture**. | [YAGNI](https://martinfowler.com/bliki/Yagni.html) · [ADR 0034](docs/decisions/0034-posture-keep-the-diff-small.md) | These aren't dressed up as science — they're conventions we chose deliberately, and the choice itself is recorded where every other one is: [`docs/decisions/`](docs/decisions/). @@ -266,6 +267,7 @@ The findings behind the design choices above: - **Semantic Versioning** — [semver.org](https://semver.org/) - **Test-Driven Development** — Kent Beck, *Test-Driven Development: By Example* (Addison-Wesley, 2002) — red-first as the loop's back pressure. [O'Reilly](https://www.oreilly.com/library/view/test-driven-development/0321146530/) - **Reconciliation mechanisms** — Cyrille Martraire, *Living Documentation: Continuous Knowledge Sharing by Design* (Addison-Wesley, 2019) — when a document can't be generated from the code, check it against the code and report the mismatch. [O'Reilly](https://www.oreilly.com/library/view/living-documentation-continuous/9780134689418/) +- **Capture before clarifying** — David Allen, *Getting Things Done* (1st ed. 2001) — collect what arrives without judging it, decide what it means as a separate step. [gettingthingsdone.com](https://gettingthingsdone.com/) The complete per-decision history lives in [`docs/decisions/`](docs/decisions/) and [`CHANGELOG.md`](CHANGELOG.md). diff --git a/docs/AGENT-EVALS.md b/docs/AGENT-EVALS.md index 3d3e24a..b3421dd 100644 --- a/docs/AGENT-EVALS.md +++ b/docs/AGENT-EVALS.md @@ -1,4 +1,4 @@ - + # Agent evals — groundrules > A log of the **agent's own** observed failure modes while developing this plugin — diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 265ac1d..865f888 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,4 +1,4 @@ - + # Architecture — groundrules **Living** snapshot of the current architecture. Updated as the structure evolves. diff --git a/docs/CONTEXT-ECONOMY.md b/docs/CONTEXT-ECONOMY.md index 0b1d3bf..a8718b0 100644 --- a/docs/CONTEXT-ECONOMY.md +++ b/docs/CONTEXT-ECONOMY.md @@ -1,4 +1,4 @@ - + # Context economy — how groundrules keeps docs exhaustive *and* cheap > Why groundrules generates an **index + on-demand docs** instead of dumping everything diff --git a/docs/LEARNINGS.md b/docs/LEARNINGS.md index 2d9223d..8563d58 100644 --- a/docs/LEARNINGS.md +++ b/docs/LEARNINGS.md @@ -1,4 +1,4 @@ - + # Learnings — groundrules Non-trivial learnings that emerged during the project. Reverse-chronological order (newest at the top). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 796f74b..2b2e756 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,4 +1,4 @@ - + # ROADMAP — groundrules Long-term direction: the **big milestones** we want to reach. This is the *vision* horizon — diff --git a/docs/VISION.md b/docs/VISION.md index 97fe5e3..07499d2 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -1,4 +1,4 @@ - + # Vision — groundrules > Synthesis of the project intent. Source: `intake/INTENT.md` (retroactive paste of the original prompt). Update when the intent evolves (rare; tactical decisions go in `docs/decisions/`). diff --git a/docs/best-practices-pending.md b/docs/best-practices-pending.md index fb1fda1..113b7b3 100644 --- a/docs/best-practices-pending.md +++ b/docs/best-practices-pending.md @@ -1,4 +1,4 @@ - + # Best practices pending — to review manually File generated by `/starter-kit:apply-best-practices` on 2026-05-11. Contains the recommendations **not applied automatically** (hooks, custom skills) awaiting human review. diff --git a/docs/decisions/0000-template.md b/docs/decisions/0000-template.md index 9385089..7a60ce7 100644 --- a/docs/decisions/0000-template.md +++ b/docs/decisions/0000-template.md @@ -1,4 +1,4 @@ - + # NNNN — Short decision title **Date**: YYYY-MM-DD diff --git a/docs/decisions/0001-marketplace-json-location.md b/docs/decisions/0001-marketplace-json-location.md index 572c28a..441a0a3 100644 --- a/docs/decisions/0001-marketplace-json-location.md +++ b/docs/decisions/0001-marketplace-json-location.md @@ -1,4 +1,4 @@ - + # 0001 — `marketplace.json` lives in `.claude-plugin/`, not at the repo root **Date**: 2026-05-11 diff --git a/docs/decisions/0002-plain-text-placeholder-substitution.md b/docs/decisions/0002-plain-text-placeholder-substitution.md index d38b163..5754220 100644 --- a/docs/decisions/0002-plain-text-placeholder-substitution.md +++ b/docs/decisions/0002-plain-text-placeholder-substitution.md @@ -1,4 +1,4 @@ - + # 0002 — Plain text placeholder substitution, no templating engine **Date**: 2026-05-11 diff --git a/docs/decisions/0003-multi-skill-architecture.md b/docs/decisions/0003-multi-skill-architecture.md index 3b7b593..24dc2a8 100644 --- a/docs/decisions/0003-multi-skill-architecture.md +++ b/docs/decisions/0003-multi-skill-architecture.md @@ -1,4 +1,4 @@ - + # 0003 — Multi-skill architecture with `disable-model-invocation: true` **Date**: 2026-05-11 diff --git a/docs/decisions/0004-starter-kit-json-schema.md b/docs/decisions/0004-starter-kit-json-schema.md index c154dd3..fd322e2 100644 --- a/docs/decisions/0004-starter-kit-json-schema.md +++ b/docs/decisions/0004-starter-kit-json-schema.md @@ -1,4 +1,4 @@ - + # 0004 — `.starter-kit.json` schema with `bootstrappedWithVersion` and `migrations` array **Date**: 2026-05-11 diff --git a/docs/decisions/0005-intent-capture-and-apply-best-practices.md b/docs/decisions/0005-intent-capture-and-apply-best-practices.md index 9c33337..d74891f 100644 --- a/docs/decisions/0005-intent-capture-and-apply-best-practices.md +++ b/docs/decisions/0005-intent-capture-and-apply-best-practices.md @@ -1,4 +1,4 @@ - + # 0005 — Intent capture in bootstrap + separate `apply-best-practices` skill **Date**: 2026-05-11 diff --git a/docs/decisions/0006-optional-specialized-docs.md b/docs/decisions/0006-optional-specialized-docs.md index 1f6ebe5..c01bc90 100644 --- a/docs/decisions/0006-optional-specialized-docs.md +++ b/docs/decisions/0006-optional-specialized-docs.md @@ -1,4 +1,4 @@ - + # 0006 — Optional specialized docs in bootstrap **Date**: 2026-06-03 diff --git a/docs/decisions/0007-denumber-entry-docs.md b/docs/decisions/0007-denumber-entry-docs.md index 437f534..d0361fe 100644 --- a/docs/decisions/0007-denumber-entry-docs.md +++ b/docs/decisions/0007-denumber-entry-docs.md @@ -1,4 +1,4 @@ - + # 0007 — Drop the numeric prefix on entry docs (VISION / INTENT) **Date**: 2026-06-03 diff --git a/docs/decisions/0008-adopt-brownfield-projects.md b/docs/decisions/0008-adopt-brownfield-projects.md index 196f112..352e447 100644 --- a/docs/decisions/0008-adopt-brownfield-projects.md +++ b/docs/decisions/0008-adopt-brownfield-projects.md @@ -1,4 +1,4 @@ - + # 0008 — Adopt existing (brownfield) projects via a dedicated skill **Date**: 2026-06-03 diff --git a/docs/decisions/0009-global-claude-md-awareness.md b/docs/decisions/0009-global-claude-md-awareness.md index c8cabac..8cc3737 100644 --- a/docs/decisions/0009-global-claude-md-awareness.md +++ b/docs/decisions/0009-global-claude-md-awareness.md @@ -1,4 +1,4 @@ - + # 0009 — Global / enterprise CLAUDE.md awareness + lean project CLAUDE.md **Date**: 2026-06-03 diff --git a/docs/decisions/0010-managed-project-claude-md-deference.md b/docs/decisions/0010-managed-project-claude-md-deference.md index fbda287..37c503d 100644 --- a/docs/decisions/0010-managed-project-claude-md-deference.md +++ b/docs/decisions/0010-managed-project-claude-md-deference.md @@ -1,4 +1,4 @@ - + # 0010 — Defer to an existing tool-managed project CLAUDE.md **Date**: 2026-06-03 diff --git a/docs/decisions/0011-detect-no-ai-attribution-policy.md b/docs/decisions/0011-detect-no-ai-attribution-policy.md index f1b0cda..b393560 100644 --- a/docs/decisions/0011-detect-no-ai-attribution-policy.md +++ b/docs/decisions/0011-detect-no-ai-attribution-policy.md @@ -1,4 +1,4 @@ - + # 0011 — Detect a "no AI attribution" policy and adapt suggested commits **Date**: 2026-06-03 diff --git a/docs/decisions/0012-english-only.md b/docs/decisions/0012-english-only.md index 2d8a5f7..ddeed7a 100644 --- a/docs/decisions/0012-english-only.md +++ b/docs/decisions/0012-english-only.md @@ -1,4 +1,4 @@ - + # 0012 — English-only (drop bilingual FR/EN templates) **Date**: 2026-06-04 diff --git a/docs/decisions/0013-media-under-docs.md b/docs/decisions/0013-media-under-docs.md index 4f8d3e2..d8d0ae9 100644 --- a/docs/decisions/0013-media-under-docs.md +++ b/docs/decisions/0013-media-under-docs.md @@ -1,4 +1,4 @@ - + # 0013 — Move media under docs/ (docs/media/ instead of top-level media/) **Date**: 2026-06-04 diff --git a/docs/decisions/0014-rename-brief-to-intake.md b/docs/decisions/0014-rename-brief-to-intake.md index 7f673eb..d181160 100644 --- a/docs/decisions/0014-rename-brief-to-intake.md +++ b/docs/decisions/0014-rename-brief-to-intake.md @@ -1,4 +1,4 @@ - + # 0014 — Rename the brief/ folder to intake/ **Date**: 2026-06-06 diff --git a/docs/decisions/0015-best-effort-update-check.md b/docs/decisions/0015-best-effort-update-check.md index 0194831..f7699b7 100644 --- a/docs/decisions/0015-best-effort-update-check.md +++ b/docs/decisions/0015-best-effort-update-check.md @@ -1,4 +1,4 @@ - + # 0015 — Best-effort plugin update check in skills (Phase 0) **Date**: 2026-06-06 diff --git a/docs/decisions/0016-rename-marketplace.md b/docs/decisions/0016-rename-marketplace.md index 5f3ca33..c9139c8 100644 --- a/docs/decisions/0016-rename-marketplace.md +++ b/docs/decisions/0016-rename-marketplace.md @@ -1,4 +1,4 @@ - + # 0016 — Rename the marketplace starter-kit-local → claude-code-starter-kit **Date**: 2026-06-06 diff --git a/docs/decisions/0017-plugin-rename-at-v1.md b/docs/decisions/0017-plugin-rename-at-v1.md index f21c47b..5096ac2 100644 --- a/docs/decisions/0017-plugin-rename-at-v1.md +++ b/docs/decisions/0017-plugin-rename-at-v1.md @@ -1,4 +1,4 @@ - + # 0017 — Rename the plugin to groundrules at V1.0.0 **Date**: 2026-06-06 diff --git a/docs/decisions/0018-adopt-consolidation-mode.md b/docs/decisions/0018-adopt-consolidation-mode.md index c40f686..a2a4cee 100644 --- a/docs/decisions/0018-adopt-consolidation-mode.md +++ b/docs/decisions/0018-adopt-consolidation-mode.md @@ -1,4 +1,4 @@ - + # 0018 — adopt: map-in-place vs consolidate strategies **Date**: 2026-06-06 diff --git a/docs/decisions/0019-heyjoe-inspired-doc-improvements.md b/docs/decisions/0019-heyjoe-inspired-doc-improvements.md index 4688324..7f49b0d 100644 --- a/docs/decisions/0019-heyjoe-inspired-doc-improvements.md +++ b/docs/decisions/0019-heyjoe-inspired-doc-improvements.md @@ -1,4 +1,4 @@ - + # 0019 — Doc improvements harvested from a real project (crm-heyjoe) **Date**: 2026-06-06 diff --git a/docs/decisions/0020-repo-is-the-only-memory.md b/docs/decisions/0020-repo-is-the-only-memory.md index c7f3a92..ad95a5d 100644 --- a/docs/decisions/0020-repo-is-the-only-memory.md +++ b/docs/decisions/0020-repo-is-the-only-memory.md @@ -1,4 +1,4 @@ - + # 0020 — The repo is the only memory **Date**: 2026-06-07 diff --git a/docs/decisions/0021-context-economy-index-over-doc-search.md b/docs/decisions/0021-context-economy-index-over-doc-search.md index 5ea9efe..322718a 100644 --- a/docs/decisions/0021-context-economy-index-over-doc-search.md +++ b/docs/decisions/0021-context-economy-index-over-doc-search.md @@ -1,4 +1,4 @@ - + # 0021 — Context economy: index over doc-search for a project's own docs **Date**: 2026-06-08 diff --git a/docs/decisions/0022-agent-evals-and-session-close.md b/docs/decisions/0022-agent-evals-and-session-close.md index 8b0d480..adc6490 100644 --- a/docs/decisions/0022-agent-evals-and-session-close.md +++ b/docs/decisions/0022-agent-evals-and-session-close.md @@ -1,4 +1,4 @@ - + # 0022 — Session-close ritual + optional agent-evals log **Date**: 2026-06-08 diff --git a/docs/decisions/0023-project-scope-for-team-portability.md b/docs/decisions/0023-project-scope-for-team-portability.md index f1a1d3f..ce7de7f 100644 --- a/docs/decisions/0023-project-scope-for-team-portability.md +++ b/docs/decisions/0023-project-scope-for-team-portability.md @@ -1,4 +1,4 @@ - + # 0023 — Recommend project-scope install for team portability (no CLAUDE.md bloat, no vendoring) **Date**: 2026-06-08 diff --git a/docs/decisions/0024-slim-skill-claude-md-budget.md b/docs/decisions/0024-slim-skill-claude-md-budget.md index 165a126..229931c 100644 --- a/docs/decisions/0024-slim-skill-claude-md-budget.md +++ b/docs/decisions/0024-slim-skill-claude-md-budget.md @@ -1,4 +1,4 @@ - + # 0024 — `/groundrules:slim` — operationalize the CLAUDE.md budget **Date**: 2026-06-08 diff --git a/docs/decisions/0025-no-runtime-hook-no-watch.md b/docs/decisions/0025-no-runtime-hook-no-watch.md index 9561780..b6aaef0 100644 --- a/docs/decisions/0025-no-runtime-hook-no-watch.md +++ b/docs/decisions/0025-no-runtime-hook-no-watch.md @@ -1,4 +1,4 @@ - + # 0025 — Won't-do: PreToolUse `{{KEY}}` hook and `/watch-bootstrap` **Date**: 2026-06-08 diff --git a/docs/decisions/0026-posture-and-per-feature-prd.md b/docs/decisions/0026-posture-and-per-feature-prd.md index c4d9768..75b3c93 100644 --- a/docs/decisions/0026-posture-and-per-feature-prd.md +++ b/docs/decisions/0026-posture-and-per-feature-prd.md @@ -1,4 +1,4 @@ - + # 0026 — Posture section + per-feature PRD (harvested from the four-principles doc) **Date**: 2026-06-13 diff --git a/docs/decisions/0027-reflection-realization-interactive-loop.md b/docs/decisions/0027-reflection-realization-interactive-loop.md index 08399b0..f088af1 100644 --- a/docs/decisions/0027-reflection-realization-interactive-loop.md +++ b/docs/decisions/0027-reflection-realization-interactive-loop.md @@ -1,4 +1,4 @@ - + # 0027 — Reflection vs realization phases; interactive vs loop regimes **Date**: 2026-06-13 diff --git a/docs/decisions/0028-git-workflow-conventions.md b/docs/decisions/0028-git-workflow-conventions.md index e7087a5..8a5f80b 100644 --- a/docs/decisions/0028-git-workflow-conventions.md +++ b/docs/decisions/0028-git-workflow-conventions.md @@ -1,4 +1,4 @@ - + # 0028 — Git workflow conventions (branching, commit granularity, AI attribution) **Date**: 2026-06-13 diff --git a/docs/decisions/0029-content-aware-claude-md-tailoring.md b/docs/decisions/0029-content-aware-claude-md-tailoring.md index a1c511f..3f77160 100644 --- a/docs/decisions/0029-content-aware-claude-md-tailoring.md +++ b/docs/decisions/0029-content-aware-claude-md-tailoring.md @@ -1,4 +1,4 @@ - + # 0029 — Content-aware CLAUDE.md tailoring (retire the lean template) **Date**: 2026-06-14 diff --git a/docs/decisions/0030-loop-namespace-and-backlog.md b/docs/decisions/0030-loop-namespace-and-backlog.md index 4cd5100..d8d44db 100644 --- a/docs/decisions/0030-loop-namespace-and-backlog.md +++ b/docs/decisions/0030-loop-namespace-and-backlog.md @@ -1,4 +1,4 @@ - + # 0030 — `loop/` as the loop's namespace; a dedicated backlog referenced by `PLAN.md` **Date**: 2026-06-14 diff --git a/docs/decisions/0031-goal-interop-swappable-loop-executor.md b/docs/decisions/0031-goal-interop-swappable-loop-executor.md index a1ac1a7..f07ce79 100644 --- a/docs/decisions/0031-goal-interop-swappable-loop-executor.md +++ b/docs/decisions/0031-goal-interop-swappable-loop-executor.md @@ -1,4 +1,4 @@ - + # 0031 — `/goal` interop: the loop executor is swappable; reposition `run-loop.sh` as fallback **Date**: 2026-06-15 diff --git a/docs/decisions/0032-premortem-anti-sycophancy.md b/docs/decisions/0032-premortem-anti-sycophancy.md index 3d9a8e4..0eddc84 100644 --- a/docs/decisions/0032-premortem-anti-sycophancy.md +++ b/docs/decisions/0032-premortem-anti-sycophancy.md @@ -1,4 +1,4 @@ - + # 0032 — Adopt the premortem as a reflection-phase adversarial technique (anti-sycophancy) **Date**: 2026-06-20 diff --git a/docs/decisions/0033-adopt-full-mode.md b/docs/decisions/0033-adopt-full-mode.md index c959484..672bb37 100644 --- a/docs/decisions/0033-adopt-full-mode.md +++ b/docs/decisions/0033-adopt-full-mode.md @@ -1,4 +1,4 @@ - + # 0033 — adopt: "Full adoption" mode (consolidate + reformat, single grouped confirmation) **Date**: 2026-06-26 diff --git a/docs/decisions/0034-posture-keep-the-diff-small.md b/docs/decisions/0034-posture-keep-the-diff-small.md index 2474d7a..978b9ac 100644 --- a/docs/decisions/0034-posture-keep-the-diff-small.md +++ b/docs/decisions/0034-posture-keep-the-diff-small.md @@ -1,4 +1,4 @@ - + # 0034 — Posture: a "keep the diff small" axis (simplicity + surgical changes) **Date**: 2026-06-29 diff --git a/docs/decisions/0035-no-auto-capture-memory-layer.md b/docs/decisions/0035-no-auto-capture-memory-layer.md index 1718485..5e6f1ab 100644 --- a/docs/decisions/0035-no-auto-capture-memory-layer.md +++ b/docs/decisions/0035-no-auto-capture-memory-layer.md @@ -1,4 +1,4 @@ - + # 0035 — Considered an auto-capture memory layer (claude-mem class); declined **Date**: 2026-06-29 diff --git a/docs/decisions/0036-git-workflow-corrected.md b/docs/decisions/0036-git-workflow-corrected.md index 09142ce..ee797fb 100644 --- a/docs/decisions/0036-git-workflow-corrected.md +++ b/docs/decisions/0036-git-workflow-corrected.md @@ -1,4 +1,4 @@ - + # 0036 — Git workflow corrected: PR on protected `main`, no AI attribution (supersedes 0028) **Date**: 2026-09-02 diff --git a/docs/decisions/0037-executable-evals-over-agent-config.md b/docs/decisions/0037-executable-evals-over-agent-config.md index 0504cd0..19fefd4 100644 --- a/docs/decisions/0037-executable-evals-over-agent-config.md +++ b/docs/decisions/0037-executable-evals-over-agent-config.md @@ -1,4 +1,4 @@ - + # 0037 — An executable eval suite over the agent's configuration (`evals/`), native format, out of band **Date**: 2026-09-02 diff --git a/docs/decisions/0038-close-reconcile-plan-against-diff.md b/docs/decisions/0038-close-reconcile-plan-against-diff.md index 92b7b91..08b2d2f 100644 --- a/docs/decisions/0038-close-reconcile-plan-against-diff.md +++ b/docs/decisions/0038-close-reconcile-plan-against-diff.md @@ -1,4 +1,4 @@ - + # 0038 — `/groundrules:close`: reconcile `PLAN.md` against the diff — a check, not a reminder **Date**: 2026-09-08 diff --git a/docs/decisions/0039-conditional-superpowers-interop.md b/docs/decisions/0039-conditional-superpowers-interop.md index 3431b3e..33a79a3 100644 --- a/docs/decisions/0039-conditional-superpowers-interop.md +++ b/docs/decisions/0039-conditional-superpowers-interop.md @@ -1,4 +1,4 @@ - + # 0039 — The superpowers interop section is conditional, detected rather than asked **Date**: 2026-09-08 diff --git a/docs/decisions/0040-three-bootstrap-modes.md b/docs/decisions/0040-three-bootstrap-modes.md index 6851384..585b11c 100644 --- a/docs/decisions/0040-three-bootstrap-modes.md +++ b/docs/decisions/0040-three-bootstrap-modes.md @@ -1,4 +1,4 @@ - + # 0040 — Three bootstrap modes: emptiness and prior state are two questions, not one **Date**: 2026-09-08 diff --git a/docs/decisions/0041-a-migration-never-damages-a-correct-file.md b/docs/decisions/0041-a-migration-never-damages-a-correct-file.md index 11b6256..183255e 100644 --- a/docs/decisions/0041-a-migration-never-damages-a-correct-file.md +++ b/docs/decisions/0041-a-migration-never-damages-a-correct-file.md @@ -1,4 +1,4 @@ - + # 0041 — A migration never damages a correct file: two write guards, and a comparison text that matches what `bootstrap` would produce **Date**: 2026-09-08 diff --git a/docs/decisions/0042-skill-creator-harness-as-the-runner.md b/docs/decisions/0042-skill-creator-harness-as-the-runner.md index a519d56..4d129c0 100644 --- a/docs/decisions/0042-skill-creator-harness-as-the-runner.md +++ b/docs/decisions/0042-skill-creator-harness-as-the-runner.md @@ -1,4 +1,4 @@ - + # 0042 — The eval suite runs on `skill-creator`'s harness, because the runner ADR 0037 chose is gated **Date**: 2026-09-09 diff --git a/docs/decisions/0043-probed-not-validated.md b/docs/decisions/0043-probed-not-validated.md index 14d2efb..f66c29f 100644 --- a/docs/decisions/0043-probed-not-validated.md +++ b/docs/decisions/0043-probed-not-validated.md @@ -1,4 +1,4 @@ - + # 0043 — `validated` is retired; a case makes an entry `probed`, and a class is never validated **Date**: 2026-09-09 diff --git a/docs/decisions/0044-runner-enforces-verifier-isolation.md b/docs/decisions/0044-runner-enforces-verifier-isolation.md index 098f619..f2087d8 100644 --- a/docs/decisions/0044-runner-enforces-verifier-isolation.md +++ b/docs/decisions/0044-runner-enforces-verifier-isolation.md @@ -1,4 +1,4 @@ - + # 0044 — The runner spawns the verifier separately; isolation stops being a request and becomes a fact **Date**: 2026-09-09 diff --git a/docs/decisions/0045-the-lock-was-scoped-to-four-skills.md b/docs/decisions/0045-the-lock-was-scoped-to-four-skills.md index c582111..684fcd3 100644 --- a/docs/decisions/0045-the-lock-was-scoped-to-four-skills.md +++ b/docs/decisions/0045-the-lock-was-scoped-to-four-skills.md @@ -1,4 +1,4 @@ - + # 0045 — `disable-model-invocation` was scoped to four skills and inherited by fifteen **Date**: 2026-09-21 diff --git a/docs/decisions/0046-orchestrated-working-regime.md b/docs/decisions/0046-orchestrated-working-regime.md index b40d043..65922ac 100644 --- a/docs/decisions/0046-orchestrated-working-regime.md +++ b/docs/decisions/0046-orchestrated-working-regime.md @@ -1,4 +1,4 @@ - + # 0046 — Orchestrated working regime: the request for work carries the authorisation for the commit **Date**: 2026-09-21 diff --git a/docs/decisions/0047-agents-md-deferred-to-m2.md b/docs/decisions/0047-agents-md-deferred-to-m2.md index 2f1dbc9..4137ec6 100644 --- a/docs/decisions/0047-agents-md-deferred-to-m2.md +++ b/docs/decisions/0047-agents-md-deferred-to-m2.md @@ -1,4 +1,4 @@ - + # 0047 — `AGENTS.md`: deferred to M2, with the measurements taken now **Date**: 2026-09-23 diff --git a/docs/decisions/0048-the-convention-here-the-transport-elsewhere.md b/docs/decisions/0048-the-convention-here-the-transport-elsewhere.md index e525b67..0609825 100644 --- a/docs/decisions/0048-the-convention-here-the-transport-elsewhere.md +++ b/docs/decisions/0048-the-convention-here-the-transport-elsewhere.md @@ -1,4 +1,4 @@ - + # 0048 — An optional `INBOX.md`: the plugin ships the convention, the caller ships the transport **Date**: 2026-09-29 diff --git a/docs/decisions/README.md b/docs/decisions/README.md index e5b3025..15b95b9 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -1,4 +1,4 @@ - + # Architecture Decisions (ADR) This folder contains the project's **Architecture Decision Records**: each structural decision made during the project is recorded in a file. diff --git a/docs/media/README.md b/docs/media/README.md index c33a505..e53e8a9 100644 --- a/docs/media/README.md +++ b/docs/media/README.md @@ -1,4 +1,4 @@ - + # docs/media/ — Visual assets Images, mockups, screenshots, videos, audio, diagrams — anything binary and visual. diff --git a/docs/prd/adoption-log.md b/docs/prd/adoption-log.md index bb2bfdf..db3d353 100644 --- a/docs/prd/adoption-log.md +++ b/docs/prd/adoption-log.md @@ -1,4 +1,4 @@ - + # PRD — adopt → ADOPTION-LOG.md (field → plugin feedback channel) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/backward-crossing-convention.md b/docs/prd/backward-crossing-convention.md index 49d474f..b2c05f1 100644 --- a/docs/prd/backward-crossing-convention.md +++ b/docs/prd/backward-crossing-convention.md @@ -1,4 +1,4 @@ - + # PRD — Backward-crossing convention (triaging `loop/blocked.md`) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/content-aware-claude-md-tailoring.md b/docs/prd/content-aware-claude-md-tailoring.md index 1c9437a..d96ab22 100644 --- a/docs/prd/content-aware-claude-md-tailoring.md +++ b/docs/prd/content-aware-claude-md-tailoring.md @@ -1,4 +1,4 @@ - + # PRD — Content-aware CLAUDE.md tailoring (retire the lean template) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/goal-interop.md b/docs/prd/goal-interop.md index 9c217ff..775060e 100644 --- a/docs/prd/goal-interop.md +++ b/docs/prd/goal-interop.md @@ -1,4 +1,4 @@ - + # PRD — `/goal` interop: surface the two executors (implements ADR 0031) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/loop-minimal-runnable.md b/docs/prd/loop-minimal-runnable.md index 7fc8d02..a3eebe7 100644 --- a/docs/prd/loop-minimal-runnable.md +++ b/docs/prd/loop-minimal-runnable.md @@ -1,4 +1,4 @@ - + # PRD — Minimal runnable loop (M1 proof-of-concept) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/loop-scaffolding-bootstrap-adopt.md b/docs/prd/loop-scaffolding-bootstrap-adopt.md index 0997661..837b66e 100644 --- a/docs/prd/loop-scaffolding-bootstrap-adopt.md +++ b/docs/prd/loop-scaffolding-bootstrap-adopt.md @@ -1,4 +1,4 @@ - + # PRD — Loop scaffolding, opt-in in `bootstrap`/`adopt` (M1 brick 2) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/loop-walkthrough.md b/docs/prd/loop-walkthrough.md index f215e83..02984ec 100644 --- a/docs/prd/loop-walkthrough.md +++ b/docs/prd/loop-walkthrough.md @@ -1,4 +1,4 @@ - + # PRD — Loop walkthrough + validation suite (show how to use the loop on a fresh project) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/realize-skill.md b/docs/prd/realize-skill.md index 93d2fdb..5100197 100644 --- a/docs/prd/realize-skill.md +++ b/docs/prd/realize-skill.md @@ -1,4 +1,4 @@ - + # PRD — /groundrules:realize (the forward bridge: approved plan → partitioned backlog) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/tdd-gate.md b/docs/prd/tdd-gate.md index c36960d..198edce 100644 --- a/docs/prd/tdd-gate.md +++ b/docs/prd/tdd-gate.md @@ -1,4 +1,4 @@ - + # PRD — TDD-before-loop gate (acceptance test = the loop's back pressure) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/template-refinement-regimes.md b/docs/prd/template-refinement-regimes.md index cfdfcb9..fc9f8a8 100644 --- a/docs/prd/template-refinement-regimes.md +++ b/docs/prd/template-refinement-regimes.md @@ -1,4 +1,4 @@ - + # PRD — Template refinement: route work by regime in the generated CLAUDE.md > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prd/vision-skill.md b/docs/prd/vision-skill.md index cbfefa7..6c3df04 100644 --- a/docs/prd/vision-skill.md +++ b/docs/prd/vision-skill.md @@ -1,4 +1,4 @@ - + # PRD — /groundrules:vision (interactive VISION builder) > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/docs/prototypes/loop/LOOP.md b/docs/prototypes/loop/LOOP.md index 4e8c07b..1636b36 100644 --- a/docs/prototypes/loop/LOOP.md +++ b/docs/prototypes/loop/LOOP.md @@ -1,4 +1,4 @@ - + # LOOP — the fixed prompt, replayed each iteration This is the prompt `run-loop.sh` feeds to a **fresh** agent every iteration. It is intentionally fixed: diff --git a/docs/prototypes/loop/README.md b/docs/prototypes/loop/README.md index a7183c6..cca79ec 100644 --- a/docs/prototypes/loop/README.md +++ b/docs/prototypes/loop/README.md @@ -1,4 +1,4 @@ - + # Prototype — minimal runnable loop (M1, brick 1) > **Status: prototype, NOT shipped.** These files are a proof-of-concept for the diff --git a/docs/prototypes/loop/fixture/TODO.md b/docs/prototypes/loop/fixture/TODO.md index 0c48732..97a8e8b 100644 --- a/docs/prototypes/loop/fixture/TODO.md +++ b/docs/prototypes/loop/fixture/TODO.md @@ -1,4 +1,4 @@ - + # TODO — slugify fixture Backlog for the minimal-loop fixture. Tasks are `- [ ]` (ready) / `- [x]` (done). The loop takes the diff --git a/docs/prototypes/loop/maker.md b/docs/prototypes/loop/maker.md index 8340883..56a94d8 100644 --- a/docs/prototypes/loop/maker.md +++ b/docs/prototypes/loop/maker.md @@ -1,4 +1,4 @@ - + # Role: Maker You implement **one** atomic task from the backlog, then report. You are one half of a maker/verifier diff --git a/docs/prototypes/loop/verifier.md b/docs/prototypes/loop/verifier.md index e52e724..f2732f2 100644 --- a/docs/prototypes/loop/verifier.md +++ b/docs/prototypes/loop/verifier.md @@ -1,4 +1,4 @@ - + # Role: Verifier You review **one** maker turn and return **PASS** or **REJECT**. You are an independent reviewer, not a diff --git a/evals/README.md b/evals/README.md index 97f5103..e6617f8 100644 --- a/evals/README.md +++ b/evals/README.md @@ -1,4 +1,4 @@ - + # `evals/` — the executable suite over this plugin's own configuration Maintainer-side tooling. It tests **groundrules' own configuration** — the instructions in diff --git a/intake/INTENT.md b/intake/INTENT.md index 22ac2af..703b685 100644 --- a/intake/INTENT.md +++ b/intake/INTENT.md @@ -1,4 +1,4 @@ - + # Intake / Intent — groundrules Raw upstream content (paste, email copy, call transcript, PO doc, etc.) describing the project intent. diff --git a/intake/README.md b/intake/README.md index 0176efe..ade7ae8 100644 --- a/intake/README.md +++ b/intake/README.md @@ -1,4 +1,4 @@ - + # intake/ — Upstream notes This folder contains anything written **before** starting the project that provides domain context: diff --git a/skills/apply-best-practices/SKILL.md b/skills/apply-best-practices/SKILL.md index 1ac6867..ac9fc6f 100644 --- a/skills/apply-best-practices/SKILL.md +++ b/skills/apply-best-practices/SKILL.md @@ -75,7 +75,7 @@ For each selected recommendation: paths: - "..." --- - + # Title ... diff --git a/skills/bootstrap/SKILL.md b/skills/bootstrap/SKILL.md index d8896da..d834673 100644 --- a/skills/bootstrap/SKILL.md +++ b/skills/bootstrap/SKILL.md @@ -375,7 +375,7 @@ Only surface this if `.claude/settings.json` doesn't already carry a project-sco ## Important rules - **NEVER overwrite a file without explicit confirmation** (see phase 4). -- **Always** add `` at the top of each generated file (the templates already contain it). +- **Always** add `` at the top of each generated file (the templates already contain it). - **Idempotence**: if the user re-runs the skill, resume mode detects already-up-to-date files and does nothing. - **Surface errors**: if a step fails (e.g. `gh repo create` returns an error), don't pretend it worked. Show the error, propose an action. - **Keep `.groundrules.json`**: it's the source of truth for resume mode and for `apply-best-practices`. diff --git a/skills/bootstrap/templates/ADOPTION-LOG.md.tpl b/skills/bootstrap/templates/ADOPTION-LOG.md.tpl index 6fa0780..6df0dc1 100644 --- a/skills/bootstrap/templates/ADOPTION-LOG.md.tpl +++ b/skills/bootstrap/templates/ADOPTION-LOG.md.tpl @@ -1,4 +1,4 @@ - + # Adoption log — {{PROJECT_NAME}} > A **dated, frozen** record of the `/groundrules:adopt` run on **{{DATE}}**: what was here, and what diff --git a/skills/bootstrap/templates/AGENT-EVALS.md.tpl b/skills/bootstrap/templates/AGENT-EVALS.md.tpl index 4411f5d..1023c06 100644 --- a/skills/bootstrap/templates/AGENT-EVALS.md.tpl +++ b/skills/bootstrap/templates/AGENT-EVALS.md.tpl @@ -1,4 +1,4 @@ - + # Agent evals — {{PROJECT_NAME}} > A log of the **agent's own** observed failure modes on this project — recurring mistakes, diff --git a/skills/bootstrap/templates/ARCHITECTURE.md.tpl b/skills/bootstrap/templates/ARCHITECTURE.md.tpl index 29f468f..d2c2a65 100644 --- a/skills/bootstrap/templates/ARCHITECTURE.md.tpl +++ b/skills/bootstrap/templates/ARCHITECTURE.md.tpl @@ -1,4 +1,4 @@ - + # Architecture — {{PROJECT_NAME}} **Living** snapshot of the current architecture. Updated as the structure evolves. diff --git a/skills/bootstrap/templates/CHANGELOG.md.tpl b/skills/bootstrap/templates/CHANGELOG.md.tpl index 03173dd..6ade1d2 100644 --- a/skills/bootstrap/templates/CHANGELOG.md.tpl +++ b/skills/bootstrap/templates/CHANGELOG.md.tpl @@ -1,4 +1,4 @@ - + # Changelog All notable changes to this project are documented in this file. diff --git a/skills/bootstrap/templates/CLAUDE.md.tpl b/skills/bootstrap/templates/CLAUDE.md.tpl index 5f5dea5..f1329bb 100644 --- a/skills/bootstrap/templates/CLAUDE.md.tpl +++ b/skills/bootstrap/templates/CLAUDE.md.tpl @@ -1,4 +1,4 @@ - + # CLAUDE.md — {{PROJECT_NAME}} > This file is **mutable and iterative**. Update it after every Claude mistake or newly discovered convention. Target: < 200 lines. diff --git a/skills/bootstrap/templates/DATA_MODEL.md.tpl b/skills/bootstrap/templates/DATA_MODEL.md.tpl index 3af041f..1d5e65f 100644 --- a/skills/bootstrap/templates/DATA_MODEL.md.tpl +++ b/skills/bootstrap/templates/DATA_MODEL.md.tpl @@ -1,4 +1,4 @@ - + # Data Model — {{PROJECT_NAME}} **Living** description of the data model. Update it whenever the schema changes. diff --git a/skills/bootstrap/templates/DESIGN_SYSTEM.md.tpl b/skills/bootstrap/templates/DESIGN_SYSTEM.md.tpl index 95accf3..707236c 100644 --- a/skills/bootstrap/templates/DESIGN_SYSTEM.md.tpl +++ b/skills/bootstrap/templates/DESIGN_SYSTEM.md.tpl @@ -1,4 +1,4 @@ - + # Design System — {{PROJECT_NAME}} **Living** reference of the visual identity and UI components. diff --git a/skills/bootstrap/templates/GLOSSARY.md.tpl b/skills/bootstrap/templates/GLOSSARY.md.tpl index b9c66ee..2fd865e 100644 --- a/skills/bootstrap/templates/GLOSSARY.md.tpl +++ b/skills/bootstrap/templates/GLOSSARY.md.tpl @@ -1,4 +1,4 @@ - + # Glossary — {{PROJECT_NAME}} Domain vocabulary for the project. One entry per term, alphabetical order. diff --git a/skills/bootstrap/templates/I18N.md.tpl b/skills/bootstrap/templates/I18N.md.tpl index 6150274..e316c15 100644 --- a/skills/bootstrap/templates/I18N.md.tpl +++ b/skills/bootstrap/templates/I18N.md.tpl @@ -1,4 +1,4 @@ - + # Internationalization (i18n) — {{PROJECT_NAME}} **Living** strategy for multilingual support. diff --git a/skills/bootstrap/templates/INBOX.md.tpl b/skills/bootstrap/templates/INBOX.md.tpl index e91f416..eb568c3 100644 --- a/skills/bootstrap/templates/INBOX.md.tpl +++ b/skills/bootstrap/templates/INBOX.md.tpl @@ -1,4 +1,4 @@ - + # INBOX — {{PROJECT_NAME}} What was handed to this project **from outside**, not yet triaged. A colleague, a ticket, another diff --git a/skills/bootstrap/templates/LEARNINGS.md.tpl b/skills/bootstrap/templates/LEARNINGS.md.tpl index 5747eea..5d80ad2 100644 --- a/skills/bootstrap/templates/LEARNINGS.md.tpl +++ b/skills/bootstrap/templates/LEARNINGS.md.tpl @@ -1,4 +1,4 @@ - + # Learnings — {{PROJECT_NAME}} Rules learned from corrections and non-trivial discoveries during the project. Reverse-chronological order (newest at the top). **Re-read at session start.** diff --git a/skills/bootstrap/templates/PLAN.md.tpl b/skills/bootstrap/templates/PLAN.md.tpl index 20bdc78..bf4c84a 100644 --- a/skills/bootstrap/templates/PLAN.md.tpl +++ b/skills/bootstrap/templates/PLAN.md.tpl @@ -1,4 +1,4 @@ - + # PLAN — {{PROJECT_NAME}} **Active** plan/todo for the project. Maintained by Claude during work. diff --git a/skills/bootstrap/templates/PRD.md.tpl b/skills/bootstrap/templates/PRD.md.tpl index b590b89..9d88af8 100644 --- a/skills/bootstrap/templates/PRD.md.tpl +++ b/skills/bootstrap/templates/PRD.md.tpl @@ -1,4 +1,4 @@ - + # PRD — {{FEATURE}} > Product Requirements Document for a single feature. Written **before** building, so the agent diff --git a/skills/bootstrap/templates/PROCESS.md.tpl b/skills/bootstrap/templates/PROCESS.md.tpl index 6e36ee7..19ac63c 100644 --- a/skills/bootstrap/templates/PROCESS.md.tpl +++ b/skills/bootstrap/templates/PROCESS.md.tpl @@ -1,4 +1,4 @@ - + # Process — {{PROJECT_NAME}} > The **working method contract** for this project: how we work together, phase by phase, with explicit validation gates. This is neither the intent (`intake/`) nor the vision (`docs/VISION.md`) — it's the *how we proceed*. Claude must follow it and **never skip a phase**. diff --git a/skills/bootstrap/templates/README.md.tpl b/skills/bootstrap/templates/README.md.tpl index 1631075..bc437ef 100644 --- a/skills/bootstrap/templates/README.md.tpl +++ b/skills/bootstrap/templates/README.md.tpl @@ -1,4 +1,4 @@ - + # {{PROJECT_NAME}} {{DESCRIPTION}} diff --git a/skills/bootstrap/templates/RELEASE.md.tpl b/skills/bootstrap/templates/RELEASE.md.tpl index f7594c8..7a34b30 100644 --- a/skills/bootstrap/templates/RELEASE.md.tpl +++ b/skills/bootstrap/templates/RELEASE.md.tpl @@ -1,4 +1,4 @@ - + # Release — {{PROJECT_NAME}} > Operational **runbook** for shipping. The CHANGELOG records *what* shipped; this file records *how* to ship safely. Update it whenever a release reveals a fragility (pair it with a `docs/LEARNINGS.md` entry). diff --git a/skills/bootstrap/templates/ROADMAP.md.tpl b/skills/bootstrap/templates/ROADMAP.md.tpl index 2ab264a..abe1c69 100644 --- a/skills/bootstrap/templates/ROADMAP.md.tpl +++ b/skills/bootstrap/templates/ROADMAP.md.tpl @@ -1,4 +1,4 @@ - + # Roadmap — {{PROJECT_NAME}} **Long-term** breakdown into deliverable milestones / increments. diff --git a/skills/bootstrap/templates/SECURITY.md.tpl b/skills/bootstrap/templates/SECURITY.md.tpl index 5fdfee3..1caba4c 100644 --- a/skills/bootstrap/templates/SECURITY.md.tpl +++ b/skills/bootstrap/templates/SECURITY.md.tpl @@ -1,4 +1,4 @@ - + # Security & Compliance — {{PROJECT_NAME}} **Living** document of security and compliance (GDPR / privacy) choices. diff --git a/skills/bootstrap/templates/adr-template.md b/skills/bootstrap/templates/adr-template.md index 9385089..7a60ce7 100644 --- a/skills/bootstrap/templates/adr-template.md +++ b/skills/bootstrap/templates/adr-template.md @@ -1,4 +1,4 @@ - + # NNNN — Short decision title **Date**: YYYY-MM-DD diff --git a/skills/bootstrap/templates/decisions-README.md.tpl b/skills/bootstrap/templates/decisions-README.md.tpl index 9c86e0c..313bc41 100644 --- a/skills/bootstrap/templates/decisions-README.md.tpl +++ b/skills/bootstrap/templates/decisions-README.md.tpl @@ -1,4 +1,4 @@ - + # Architecture Decisions (ADR) This folder contains the project's **Architecture Decision Records**: each structural decision made during the project is recorded in a file. diff --git a/skills/bootstrap/templates/docs-VISION.md.tpl b/skills/bootstrap/templates/docs-VISION.md.tpl index 0fbd734..4107e28 100644 --- a/skills/bootstrap/templates/docs-VISION.md.tpl +++ b/skills/bootstrap/templates/docs-VISION.md.tpl @@ -1,4 +1,4 @@ - + # Vision — {{PROJECT_NAME}} > Synthesis of the project intent. Source: {{INTENT_SOURCE}}. Update when intent evolves (rare; tactical decisions go in `docs/decisions/`). diff --git a/skills/bootstrap/templates/intake-INTENT.md.tpl b/skills/bootstrap/templates/intake-INTENT.md.tpl index 7b11cee..75fec0d 100644 --- a/skills/bootstrap/templates/intake-INTENT.md.tpl +++ b/skills/bootstrap/templates/intake-INTENT.md.tpl @@ -1,4 +1,4 @@ - + # Intake / Intent — {{PROJECT_NAME}} Raw upstream content (paste, email excerpt, call transcript, PO doc, etc.) describing the project intent. diff --git a/skills/bootstrap/templates/intake-README.md.tpl b/skills/bootstrap/templates/intake-README.md.tpl index 78d1e1a..18e5131 100644 --- a/skills/bootstrap/templates/intake-README.md.tpl +++ b/skills/bootstrap/templates/intake-README.md.tpl @@ -1,4 +1,4 @@ - + # intake/ — Upstream notes This folder contains anything written **before** starting the project that provides domain context: diff --git a/skills/bootstrap/templates/loop/CLAUDE-invariants.md b/skills/bootstrap/templates/loop/CLAUDE-invariants.md index 1a09776..7cfe32c 100644 --- a/skills/bootstrap/templates/loop/CLAUDE-invariants.md +++ b/skills/bootstrap/templates/loop/CLAUDE-invariants.md @@ -1,4 +1,4 @@ - + ## Invariants diff --git a/skills/bootstrap/templates/loop/LOOP.md b/skills/bootstrap/templates/loop/LOOP.md index fcddf04..2cc4ccc 100644 --- a/skills/bootstrap/templates/loop/LOOP.md +++ b/skills/bootstrap/templates/loop/LOOP.md @@ -1,4 +1,4 @@ - + # LOOP — the maker prompt, replayed each iteration This is the prompt `loop/run-loop.sh` feeds to a **fresh** agent at the start of every iteration. It is diff --git a/skills/bootstrap/templates/loop/README.md.tpl b/skills/bootstrap/templates/loop/README.md.tpl index 636335f..12264ef 100644 --- a/skills/bootstrap/templates/loop/README.md.tpl +++ b/skills/bootstrap/templates/loop/README.md.tpl @@ -1,4 +1,4 @@ - + # Loop — autonomous maker/verifier execution for {{PROJECT_NAME}} This directory makes {{PROJECT_NAME}} executable by an **autonomous loop**, not only interactively. It diff --git a/skills/bootstrap/templates/loop/backlog.md b/skills/bootstrap/templates/loop/backlog.md index c0813cd..1403f6c 100644 --- a/skills/bootstrap/templates/loop/backlog.md +++ b/skills/bootstrap/templates/loop/backlog.md @@ -1,4 +1,4 @@ - + # Loop backlog The tasks the autonomous loop is allowed to execute. **The loop reads only this file** — never diff --git a/skills/bootstrap/templates/loop/maker.md b/skills/bootstrap/templates/loop/maker.md index e6705d5..d2e08e1 100644 --- a/skills/bootstrap/templates/loop/maker.md +++ b/skills/bootstrap/templates/loop/maker.md @@ -1,4 +1,4 @@ - + # Role: Maker You implement **one** atomic task from `loop/backlog.md`, then report. You are one half of a diff --git a/skills/bootstrap/templates/loop/verifier.md b/skills/bootstrap/templates/loop/verifier.md index d4bc720..3f926be 100644 --- a/skills/bootstrap/templates/loop/verifier.md +++ b/skills/bootstrap/templates/loop/verifier.md @@ -1,4 +1,4 @@ - + # Role: Verifier You review **one** maker turn and return **PASS** or **REJECT**. You are an independent reviewer, not a diff --git a/skills/bootstrap/templates/media-README.md.tpl b/skills/bootstrap/templates/media-README.md.tpl index c33a505..e53e8a9 100644 --- a/skills/bootstrap/templates/media-README.md.tpl +++ b/skills/bootstrap/templates/media-README.md.tpl @@ -1,4 +1,4 @@ - + # docs/media/ — Visual assets Images, mockups, screenshots, videos, audio, diagrams — anything binary and visual. diff --git a/skills/verify-bootstrap/SKILL.md b/skills/verify-bootstrap/SKILL.md index 531bdc4..b78a09d 100644 --- a/skills/verify-bootstrap/SKILL.md +++ b/skills/verify-bootstrap/SKILL.md @@ -41,7 +41,7 @@ Read the **first 10 lines** of the file (to accommodate a YAML frontmatter that paths: - "..." --- - + ``` ### 2.3 Version match diff --git a/test/check-adr-index.sh b/test/check-adr-index.sh index 81d7d90..b203258 100755 --- a/test/check-adr-index.sh +++ b/test/check-adr-index.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# generated-by: groundrules v1.12.0 +# generated-by: groundrules v1.13.0 # # check-adr-index.sh — every ADR file has a row in the index, and every row points at a file. # diff --git a/test/loop/QUICKSTART.md b/test/loop/QUICKSTART.md index afb5f86..34eab26 100644 --- a/test/loop/QUICKSTART.md +++ b/test/loop/QUICKSTART.md @@ -1,4 +1,4 @@ - + # Quickstart — your first loop, in 5 steps The everyday rhythm with groundrules: **a fresh project → ask in plain words → set a goal (a failing diff --git a/test/loop/README.md b/test/loop/README.md index 2892fd5..73e6de6 100644 --- a/test/loop/README.md +++ b/test/loop/README.md @@ -1,4 +1,4 @@ - + # test/loop — loop walkthrough + validation suite How to **use the groundrules loop** on a fresh project, in a way that also **validates** it. Spec'd in diff --git a/test/loop/TUTORIAL.md b/test/loop/TUTORIAL.md index 0d41a3c..f2a92d3 100644 --- a/test/loop/TUTORIAL.md +++ b/test/loop/TUTORIAL.md @@ -1,4 +1,4 @@ - + # Tutorial — learn the loop by building Conway's Game of Life By the end of this (~15 min) you'll have watched an **autonomous loop implement Conway's Game of Life diff --git a/test/loop/WALKTHROUGH.md b/test/loop/WALKTHROUGH.md index f7da0f7..252d61b 100644 --- a/test/loop/WALKTHROUGH.md +++ b/test/loop/WALKTHROUGH.md @@ -1,4 +1,4 @@ - + # Loop walkthrough — from an empty folder to a working loop This shows **how to use the groundrules loop** end-to-end on a fresh project, and **doubles as the diff --git a/test/loop/fixtures/game-of-life/PRD.md b/test/loop/fixtures/game-of-life/PRD.md index 7c63db5..7600d9b 100644 --- a/test/loop/fixtures/game-of-life/PRD.md +++ b/test/loop/fixtures/game-of-life/PRD.md @@ -1,4 +1,4 @@ - + # PRD — Game of Life (banc d'essai du loop Groundrules) > Objet : sujet minimal servant à valider le mécanisme de loop goal-driven. diff --git a/test/loop/fixtures/sample-plan.md b/test/loop/fixtures/sample-plan.md index 1210ef3..71e2666 100644 --- a/test/loop/fixtures/sample-plan.md +++ b/test/loop/fixtures/sample-plan.md @@ -1,4 +1,4 @@ - + # Sample approved plan — feed this to `/groundrules:realize` A deliberately **mixed** plan so the walkthrough shows `realize` partitioning correctly. Paste this (or