mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.0 — one config file, and a process weight you choose
`project.yaml` at the repo root is now the single source of truth for a project's configuration, replacing `production/stage.txt`, `production/review-mode.txt` and `.claude/docs/technical-preferences.md` (all three still read as a fallback; nothing is force-deleted). **`modes.rigor` — one question instead of six.** `minimal`, `standard` or `full` fronts six knobs: `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`, `modes.review_mode` and `team.size`. It defaults to `minimal`, which is a change from 1.0's behaviour: the heavier tier was measured costing several times more to reach working code without producing a better result, and returning nothing when a fresh developer inherited the project. Pin `modes.rigor: standard` to keep 1.0's process level. Also in this release: - `/settings` to view or change any setting, and `project.local.yaml` for per-developer preferences that should not be committed. - `system_overrides` to hold one system to a higher standard than the rest of the project, and `testing.strict` to set per test type whether missing evidence blocks a story or warns. - A story that changes anything the player sees is not closed until the game has been launched, observed, and a screenshot retained in `production/qa/evidence/`. A parse check is not a run. This holds at every rigor level, including `minimal`, where automated tests are waived but the look is not. - The code root is engine-specific and enforced as such: Godot `src/`, Unity `Assets/`, Unreal `Source/<Module>/`. Two of the three will not build a project laid out any other way. - Migration tooling for existing projects: `.claude/scripts/migrate-v1-config.sh` converts a 1.0 layout, non-destructively by default, with a report to review before `--finalize` deletes anything. - Ask-before-write holds regardless of personal automation settings. Upgrading from 1.0 or earlier: see UPGRADING.md. Full list of changes: CHANGELOG.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016xvzG3i7pWQg4LjyDwWMXd
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5
Claude Opus 5
parent
984023ddac
commit
d05699707f
@@ -1,13 +1,16 @@
|
||||
---
|
||||
name: propagate-design-change
|
||||
description: "When a GDD is revised, scans all ADRs and the traceability index to identify which architectural decisions are now potentially stale. Produces a change impact report and guides the user through resolution."
|
||||
description: "A GDD changed — scan ADRs and the traceability index for now-stale architectural decisions. Impact report, guides resolution."
|
||||
argument-hint: "[path/to/changed-gdd.md]"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep, Write, Bash, Task
|
||||
allowed-tools: Read, Glob, Grep, Write, Bash, Agent, AskUserQuestion
|
||||
model: sonnet
|
||||
agent: technical-director
|
||||
---
|
||||
|
||||
!`source "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/yaml-helper.sh" 2>/dev/null && resolve_config --keys automation,workflow,system_overrides`
|
||||
|
||||
|
||||
|
||||
# Propagate Design Change
|
||||
|
||||
When a GDD changes, architectural decisions written against it may no longer be
|
||||
@@ -18,6 +21,20 @@ what the GDD now says, and guides the user through resolution.
|
||||
|
||||
---
|
||||
|
||||
Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md`
|
||||
(collaborative asks always · guided major-only · autonomous logs and proceeds;
|
||||
`automation_always_ask` categories always prompt — ADR/schema impacts here fall
|
||||
under `schema_changes` and `architecture_decisions`).
|
||||
|
||||
**Workflow tier**: resolve for the **changed GDD's system** (per
|
||||
`.claude/docs/workflow-modes.md`): use the
|
||||
`system_overrides` row for that system if the block lists one, else the
|
||||
project value. (A system pinned `minimal` has no ADRs even on a `standard`
|
||||
project — so its change is N/A.) It scopes the cascade: `full` cascades across all
|
||||
ADRs; `standard` checks only critical (Foundation-layer) ADRs plus any ADR
|
||||
referencing the changed GDD; `minimal` is **not applicable** — no ADRs to cascade.
|
||||
See Step 4.
|
||||
|
||||
## 1. Validate Argument
|
||||
|
||||
A GDD path argument is **required**. If missing, fail with:
|
||||
@@ -29,29 +46,46 @@ Verify the file exists. If not, fail with:
|
||||
|
||||
---
|
||||
|
||||
## 2. Read the Changed GDD
|
||||
## 2. Diff the GDD Against Its Previous Version
|
||||
|
||||
Read the current GDD in full.
|
||||
|
||||
---
|
||||
|
||||
## 3. Read the Previous Version
|
||||
|
||||
Run git to get the previous committed version:
|
||||
**Ask git what changed — do not read two whole documents and compare them by
|
||||
eye.** The previous form of this step read the current GDD in full *and*
|
||||
`git show`-ed the full committed version, then diffed them mentally: two entire
|
||||
documents in context to find what is usually a handful of lines, and a model
|
||||
comparing 400-line documents will eventually miss an edit. Git cannot.
|
||||
|
||||
```bash
|
||||
git show HEAD:design/gdd/[filename].md
|
||||
git diff HEAD -- design/gdd/[filename].md
|
||||
```
|
||||
|
||||
If that is empty, the change may already be committed — widen to the commit that
|
||||
last touched it:
|
||||
|
||||
```bash
|
||||
git diff HEAD~1 HEAD -- design/gdd/[filename].md
|
||||
```
|
||||
|
||||
If the file has no git history (new file), report:
|
||||
> "No previous version in git — this appears to be a new GDD, not a revision.
|
||||
> Nothing to propagate."
|
||||
|
||||
If git returns the previous version, do a conceptual diff:
|
||||
If the diff is empty **and** the file has history, report that plainly — "no
|
||||
uncommitted or last-commit changes to `[file]`" — and ask which revision to
|
||||
propagate. An empty diff is not "no impact"; it means nothing changed *here*.
|
||||
|
||||
From the diff hunks:
|
||||
- Identify sections that changed (new rules, removed rules, modified formulas,
|
||||
changed acceptance criteria, changed tuning knobs)
|
||||
- Identify sections that are unchanged
|
||||
- Produce a change summary:
|
||||
changed acceptance criteria, changed tuning knobs). The `@@` hunk headers name
|
||||
the enclosing section, so the changed-section list falls out of the diff itself.
|
||||
- Read the surrounding section from the current GDD **only** where a hunk is too
|
||||
small to interpret on its own (a changed number whose meaning depends on the
|
||||
rule above it). That is a targeted read of one section, not the document.
|
||||
- Sections with no hunk are unchanged — by construction, not by inspection.
|
||||
---
|
||||
|
||||
## 3. Produce the Change Summary
|
||||
|
||||
From the hunks resolved in step 2:
|
||||
|
||||
```
|
||||
## Change Summary: [GDD filename]
|
||||
@@ -68,23 +102,77 @@ Key changes affecting architecture:
|
||||
- [Change 2]
|
||||
```
|
||||
|
||||
**Downstream GDD impact via the registry.** If `design/registry/entities.yaml`
|
||||
exists, it already records which other GDDs depend on this system's facts —
|
||||
compute the affected set from it rather than re-reading every GDD:
|
||||
```
|
||||
Grep pattern="source: design/gdd/[filename]" path="design/registry/entities.yaml" output_mode="content" -A 6
|
||||
```
|
||||
For each entity/constant/formula this GDD **owns** whose value the diff changed,
|
||||
its `referenced_by:` list is the set of downstream GDDs that may now be
|
||||
inconsistent — report them under "Downstream GDDs to re-check". **If
|
||||
`design/registry/entities.yaml` does not exist or has no entries** (it ships as
|
||||
an empty stub until `/design-system` populates it), skip this — the ADR cascade
|
||||
below still runs.
|
||||
|
||||
---
|
||||
|
||||
## 4. Load Architecture Inputs
|
||||
|
||||
Read all ADRs in `docs/architecture/`:
|
||||
- For each ADR, read the full file
|
||||
- Extract the "GDD Requirements Addressed" table
|
||||
- Note which GDD documents and requirement IDs each ADR references
|
||||
Read ADRs in `docs/architecture/` **per the resolved tier**:
|
||||
- **`full`** — read **all** ADRs.
|
||||
- **`standard`** — read only **critical (Foundation-layer) ADRs** plus any ADR
|
||||
that references the changed GDD.
|
||||
- **`minimal`** — **not applicable**: there are no ADRs to cascade. Report "No ADR
|
||||
cascade at minimal workflow — design change recorded; no architecture impact
|
||||
analysis." and stop here.
|
||||
|
||||
Read `docs/architecture/architecture-traceability.md` if it exists.
|
||||
**Establish the denominator first.** Glob the in-scope ADRs (per the tier above).
|
||||
Call the count **N**. If N is 0: "No ADRs found in `docs/architecture/` — nothing
|
||||
to cascade." Stop.
|
||||
|
||||
Report: "Loaded [N] ADRs. [M] reference [gdd filename]."
|
||||
**Scan the requirement tables — do not full-read the ADRs at this step:**
|
||||
```
|
||||
Grep pattern="## GDD Requirements Addressed" glob="docs/architecture/adr-*.md" output_mode="content" -A 15
|
||||
```
|
||||
**Recall net — an ADR may cite the changed GDD in prose without tabling it:**
|
||||
```
|
||||
Grep pattern="[changed-gdd-basename]" glob="docs/architecture/adr-*.md" output_mode="files_with_matches"
|
||||
```
|
||||
Take the **union** of the two results as the affected set **M**. This turns
|
||||
N × ~200 lines into N × ~15 lines; §5 full-reads only the M.
|
||||
|
||||
Interpret the result — a zero-match scan is **never** "no impact" by default:
|
||||
|
||||
| Result | Meaning | Action |
|
||||
|---|---|---|
|
||||
| **M ≥ 1** | Normal. | Proceed. The N − M non-matching ADRs are *out of scope for this cascade* — do not describe them as verified unaffected. |
|
||||
| **Both scans 0, N > 0** | Ambiguous — either no ADR references this GDD, or the ADRs lack requirement tables. | Run `Grep pattern="## GDD Requirements Addressed" glob="docs/architecture/adr-*.md" output_mode="files_with_matches"`. If that is **also** empty: "[N] ADRs found, none contains a 'GDD Requirements Addressed' section — traceability cannot be computed (a `gate-pre-production` blocker). Run `/architecture-decision [adr] retrofit`." If it is **non-empty**: the tables exist and genuinely none reference this GDD — "No ADR references [gdd] — no architecture impact." |
|
||||
|
||||
Read `docs/architecture/requirements-traceability.md` if it exists.
|
||||
|
||||
Report: "Loaded [N] ADRs by scan. [M] reference [gdd filename] ([X] via
|
||||
requirements table, [Y] via prose reference only)."
|
||||
|
||||
---
|
||||
|
||||
## 5. Impact Analysis
|
||||
|
||||
Now read each ADR in the affected set **M** for its reasoning, not just its
|
||||
table — judging whether a decision is still valid needs the ADR's `## Context`
|
||||
and `## Decision` (and `## Consequences` where present), not scan output. **Do
|
||||
not attempt the judgement below from scan output.**
|
||||
|
||||
This read is unbounded only up to a point — check size first
|
||||
(`Bash: wc -c "docs/architecture/[adr-file].md"`):
|
||||
- **Under ~50KB** — one full `Read` is fine and cheapest at this size.
|
||||
- **~50KB or larger** — map headings first
|
||||
(`Grep pattern="^## " path="docs/architecture/[adr-file].md" output_mode="content" -n`),
|
||||
then bounded-`Read` only `## Context`, `## Decision`, and `## Consequences`.
|
||||
An unbounded `Read` on a large ADR hits the 25k-token cap and, unrecovered,
|
||||
the only path forward is paging through the entire remainder — measured at
|
||||
103k tokens on a 34k-token ADR, most of it content this analysis never uses.
|
||||
|
||||
For each ADR that references the changed GDD:
|
||||
|
||||
Compare the ADR's "GDD Requirements Addressed" entries against the changed sections
|
||||
@@ -153,7 +241,7 @@ ADRs referencing this GDD: [M]
|
||||
- `lean` → skip. Note: "TD-CHANGE-IMPACT skipped — Lean mode." Proceed to Phase 7.
|
||||
- `full` → spawn as normal.
|
||||
|
||||
Spawn `technical-director` via Task using gate **TD-CHANGE-IMPACT** (`.claude/docs/director-gates.md`).
|
||||
Spawn `technical-director` via `Agent` using gate **TD-CHANGE-IMPACT** (`.claude/docs/director-gates/td-change-impact.md`).
|
||||
|
||||
Pass: the full Design Change Impact Report from Phase 6 (change summary, all affected ADRs with their Still Valid / Needs Review / Likely Superseded classifications, and recommended actions).
|
||||
|
||||
@@ -189,7 +277,7 @@ For ADRs marked **Superseded**:
|
||||
|
||||
## 8. Update Traceability Index
|
||||
|
||||
If `docs/architecture/architecture-traceability.md` exists:
|
||||
If `docs/architecture/requirements-traceability.md` exists:
|
||||
- Add the changed GDD requirements to the "Superseded Requirements" table:
|
||||
|
||||
```markdown
|
||||
@@ -232,6 +320,10 @@ Based on the resolution decisions, suggest:
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
**Applies in `collaborative` mode (the default).** For `guided` and
|
||||
`autonomous` modes, see `.claude/docs/automation-modes.md` — the rules below
|
||||
describe what collaborative mode requires, not universal behavior.
|
||||
|
||||
1. **Read silently** — compute the full impact before presenting anything
|
||||
2. **Show the full report first** — let the user see the scope before asking for action
|
||||
3. **Ask per-ADR** — don't batch decisions; each affected ADR may need different treatment
|
||||
|
||||
Reference in New Issue
Block a user