mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.3 — long skills keep their later steps
Fix release for 1.1.2: the 14 longest skills keep their later phases after a compaction, a question nobody answered is never taken as an answer, settings read the same from a subfolder, the commit check works for a project in a subfolder of a larger repository, every skill opens with a title, and the shipped allow rules no longer approve deleting a branch or writing files without asking. Details in CHANGELOG.md; upgrade steps in UPGRADING.md (v1.1.2 → v1.1.3). Refs #83 Refs #133 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0185en4t76fPn7315q4c3nko
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
b21fa0f7f2
commit
be8993bbc5
@@ -0,0 +1,246 @@
|
||||
# /architecture-decision — Step 5: Generate the ADR
|
||||
|
||||
> Part of `/architecture-decision`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## 5. Generate the ADR
|
||||
|
||||
**In this file:**
|
||||
|
||||
- The ADR template
|
||||
- 5.5 Engine Specialist Validation
|
||||
- 5.6 Technical Director Strategic Review, with the review mode check
|
||||
- 5.7 GDD Sync Check: found, none found, could not check
|
||||
- Write approval
|
||||
- Update Architecture Registry, and the registry append logic
|
||||
|
||||
Following this format:
|
||||
|
||||
```markdown
|
||||
# ADR-[NNNN]: [Title]
|
||||
|
||||
## Status
|
||||
[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
|
||||
|
||||
## Date
|
||||
[Date of decision]
|
||||
|
||||
## Last Verified
|
||||
[YYYY-MM-DD — when this ADR was last confirmed accurate against the current
|
||||
engine version and design. Update this date when you re-read and confirm it is
|
||||
still correct, even if nothing changed.]
|
||||
|
||||
## Decision Makers
|
||||
[Who was involved in this decision]
|
||||
|
||||
## Summary
|
||||
[2 sentences: what problem this ADR solves, and what was decided. Written for
|
||||
tiered context loading — a skill scanning 20 ADRs uses this to decide whether to
|
||||
read the full decision. Be specific: name the system, the problem, and the
|
||||
chosen approach.]
|
||||
|
||||
## Engine Compatibility
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | [e.g. Godot 4.6] |
|
||||
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input] |
|
||||
| **Knowledge Risk** | [LOW / MEDIUM / HIGH — from VERSION.md] |
|
||||
| **References Consulted** | [List engine-reference docs read, e.g. `docs/engine-reference/godot/modules/physics.md`] |
|
||||
| **Post-Cutoff APIs Used** | [Any APIs from post-LLM-cutoff versions this decision depends on, or "None"] |
|
||||
| **Verification Required** | [Specific behaviours to test before shipping, or "None"] |
|
||||
|
||||
## ADR Dependencies
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Depends On** | [ADR-NNNN (must be Accepted before this can be implemented), or "None"] |
|
||||
| **Enables** | [ADR-NNNN (this ADR unlocks that decision), or "None"] |
|
||||
| **Blocks** | [Epic/Story name — cannot start until this ADR is Accepted, or "None"] |
|
||||
| **Ordering Note** | [Any sequencing constraint that isn't captured above] |
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
[What problem are we solving? Why does this decision need to be made now?]
|
||||
|
||||
### Constraints
|
||||
- [Technical constraints]
|
||||
- [Timeline constraints]
|
||||
- [Resource constraints]
|
||||
- [Compatibility requirements]
|
||||
|
||||
### Requirements
|
||||
- [Must support X]
|
||||
- [Must perform within Y budget]
|
||||
- [Must integrate with Z]
|
||||
|
||||
## Decision
|
||||
|
||||
[The specific technical decision made, described in enough detail for someone
|
||||
to implement it.]
|
||||
|
||||
### Architecture Diagram
|
||||
[ASCII diagram or description of the system architecture this creates]
|
||||
|
||||
### Key Interfaces
|
||||
[API contracts or interface definitions this decision creates]
|
||||
|
||||
### Implementation Guidelines
|
||||
[Specific guidance for the programmer implementing this decision — the rules a
|
||||
`/create-control-manifest` or `/dev-story` run should follow. State mandates as
|
||||
"must / must never" so they extract cleanly.]
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative 1: [Name]
|
||||
- **Description**: [How this would work]
|
||||
- **Pros**: [Advantages]
|
||||
- **Cons**: [Disadvantages]
|
||||
- **Rejection Reason**: [Why this was not chosen]
|
||||
|
||||
### Alternative 2: [Name]
|
||||
- **Description**: [How this would work]
|
||||
- **Pros**: [Advantages]
|
||||
- **Cons**: [Disadvantages]
|
||||
- **Rejection Reason**: [Why this was not chosen]
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- [Good outcomes of this decision]
|
||||
|
||||
### Negative
|
||||
- [Trade-offs and costs accepted]
|
||||
|
||||
## Risks
|
||||
- [Things that could go wrong]
|
||||
- [Mitigation for each risk]
|
||||
|
||||
## GDD Requirements Addressed
|
||||
|
||||
| GDD System | Requirement | How This ADR Addresses It |
|
||||
|------------|-------------|--------------------------|
|
||||
| [system-name].md | [specific rule, formula, or performance constraint from that GDD] | [how this decision satisfies it] |
|
||||
|
||||
## Performance Implications
|
||||
- **CPU**: [Expected impact]
|
||||
- **Memory**: [Expected impact]
|
||||
- **Load Time**: [Expected impact]
|
||||
- **Network**: [Expected impact, if applicable]
|
||||
|
||||
## Migration Plan
|
||||
[If this changes existing code, how do we get from here to there?]
|
||||
|
||||
## Validation Criteria
|
||||
[How will we know this decision was correct? What metrics or tests?]
|
||||
|
||||
## Related
|
||||
- [Links to related ADRs — note if supersedes, contradicts, or depends on]
|
||||
- [Links to related design documents]
|
||||
```
|
||||
|
||||
5.5. **Engine Specialist Validation** — Before saving, spawn the **primary engine specialist** via `Agent` to validate the drafted ADR:
|
||||
- Resolve the primary specialist: `<engine>-specialist` derived from `engine.name` in `project.yaml` (Godot→`godot-specialist`, Unity→`unity-specialist`, Unreal→`unreal-specialist`); if `engine.name` is absent or empty, read the Primary line of the `## Engine Specialists` section in `.claude/docs/technical-preferences.md`
|
||||
- If no engine is configured (neither source yields an engine), skip this step **Record ``Engine validation: NOT ASSESSED — no engine configured (`engine.name` unset in `project.yaml`)`` in this run's output.** A skipped check that says nothing is indistinguishable from a check that passed; the reader cannot tell engine guidance was never sought.
|
||||
- Spawn `subagent_type: [primary specialist]` with: the ADR's Engine Compatibility section, Decision section, Key Interfaces, and the engine reference docs path. Ask them to:
|
||||
1. Confirm the proposed approach is idiomatic for the pinned engine version
|
||||
2. Flag any APIs or patterns that are deprecated or changed post-training-cutoff
|
||||
3. Identify engine-specific risks or gotchas not captured in the current ADR draft
|
||||
- If the specialist identifies a **blocking issue** (wrong API, deprecated approach, engine version incompatibility): revise the Decision and Engine Compatibility sections accordingly, then confirm the changes with the user before proceeding
|
||||
- If the specialist finds **minor notes** only: incorporate them into the ADR's Risks subsection
|
||||
|
||||
**Review mode check** — apply before spawning TD-ADR:
|
||||
- `solo` → skip. Note: "TD-ADR skipped — Solo mode." Proceed to Step 5.7 (GDD sync check).
|
||||
- `lean` → skip (not a PHASE-GATE). Note: "TD-ADR skipped — Lean mode." Proceed to Step 5.7 (GDD sync check).
|
||||
- `full` → spawn as normal.
|
||||
|
||||
5.6. **Technical Director Strategic Review** — After the engine specialist validation, spawn `technical-director` via `Agent` using gate **TD-ADR** (`.claude/docs/director-gates/td-adr.md`):
|
||||
- Pass: the ADR file path (or draft content), engine version, domain, any existing ADRs in the same domain
|
||||
- The TD validates architectural coherence (is this decision consistent with the whole system?) — distinct from the engine specialist's API-level check
|
||||
- On CONCERNS: show them to the user verbatim and ask with the standard options from `director-gates.md` — `Revise flagged items` / `Accept and proceed` / `Discuss further`. Revise the flagged Decision or Alternatives sections only on `Revise flagged items`.
|
||||
- On REJECT: show the blockers verbatim and revise the Decision or Alternatives sections before proceeding.
|
||||
- A revised draft still reaches the user through the write approval below; nothing is written before it. A `NOT ASSESSED` answer is not an approval — name the missing input (`director-gates.md`).
|
||||
|
||||
5.7. **GDD Sync Check** — Before presenting the write approval, scan all GDDs
|
||||
referenced in the "GDD Requirements Addressed" section for naming inconsistencies
|
||||
with the ADR's Key Interfaces and Decision sections (renamed signals, API methods,
|
||||
or data types). If any are found, surface them as a **prominent warning block**
|
||||
immediately before the write approval — not as a footnote:
|
||||
|
||||
```
|
||||
⚠️ GDD SYNC REQUIRED
|
||||
[gdd-filename].md uses names this ADR has renamed:
|
||||
[old_name] → [new_name_from_adr]
|
||||
[old_name_2] → [new_name_2_from_adr]
|
||||
The GDD must be updated before or alongside writing this ADR to prevent
|
||||
developers reading the GDD from implementing the wrong interface.
|
||||
```
|
||||
|
||||
**This check has three outcomes, not two.** The two above are "found" and "none
|
||||
found"; the third is **could not check**, and until now it fell through the
|
||||
silent branch and rendered exactly like a clean result.
|
||||
|
||||
- **None found** — print one line, do not stay silent:
|
||||
`GDD sync: checked [N] referenced GDD(s), no naming inconsistencies.`
|
||||
A silent pass is indistinguishable from a check that never ran, and this one
|
||||
guards against developers implementing the wrong interface from a stale GDD.
|
||||
- **Could not check** — the ADR has no `GDD Requirements Addressed` section, it
|
||||
names no GDDs, or a named GDD does not exist on disk. Print:
|
||||
`GDD sync: NOT ASSESSED — [which reason, and which files]`
|
||||
Do **not** treat an ADR that references no GDDs as one whose GDDs are
|
||||
consistent. Nothing was compared.
|
||||
|
||||
Only the warning block itself is conditional; the check always reports.
|
||||
|
||||
5. **Write approval** — Use `AskUserQuestion`:
|
||||
|
||||
If GDD sync issues were found:
|
||||
- "ADR draft is complete. How would you like to proceed?"
|
||||
- [A] Write ADR + update GDD in the same pass
|
||||
- [B] Write ADR only — I'll update the GDD manually
|
||||
- [C] Not yet — I need to review further
|
||||
|
||||
If no GDD sync issues:
|
||||
- "ADR draft is complete. May I write it?"
|
||||
- [A] Write ADR to `docs/architecture/adr-[NNNN]-[slug].md`
|
||||
- [B] Not yet — I need to review further
|
||||
|
||||
If yes to any write option, write the file, creating the directory if needed.
|
||||
For option [A] with GDD update: also update the GDD file(s) to use the new names.
|
||||
|
||||
6. **Update Architecture Registry**
|
||||
|
||||
Scan the written ADR for new architectural stances that should be registered:
|
||||
- State it claims ownership of
|
||||
- Interface contracts it defines (signal signatures, method APIs)
|
||||
- Performance budget it claims
|
||||
- API choices it makes explicitly
|
||||
- Patterns it bans (Consequences → Negative or explicit "do not use X")
|
||||
|
||||
Present candidates:
|
||||
```
|
||||
Registry candidates from this ADR:
|
||||
NEW state ownership: player_stamina → stamina-system
|
||||
NEW interface contract: stamina_depleted signal
|
||||
NEW performance budget: stamina-system: 0.5ms/frame
|
||||
NEW forbidden pattern: polling stamina each frame (use signal instead)
|
||||
EXISTING (referenced_by update only): player_health → already registered ✅
|
||||
```
|
||||
|
||||
**Registry append logic**: When writing to `docs/registry/architecture.yaml`, do NOT assume sections are empty. The file may already have entries from previous ADRs written in this session. Before each Edit call:
|
||||
1. Read the current state of `docs/registry/architecture.yaml`
|
||||
2. Find the correct section (state_ownership, interfaces, forbidden_patterns, api_decisions)
|
||||
3. Append the new entry AFTER the last existing entry in that section — do not try to replace a `[]` placeholder that may no longer exist
|
||||
4. If the section has entries already, use the closing content of the last entry as the `old_string` anchor, and append the new entry after it
|
||||
|
||||
**BLOCKING — do not write to `docs/registry/architecture.yaml` without explicit user approval.**
|
||||
|
||||
Ask using `AskUserQuestion`:
|
||||
- "May I update `docs/registry/architecture.yaml` with these [N] new stances?"
|
||||
- Options: "Yes — update the registry", "Not yet — I want to review the candidates", "Skip registry update"
|
||||
|
||||
Only proceed if the user selects yes. If yes: append new entries. Never modify existing entries — if a stance is
|
||||
changing, set the old entry to `status: superseded_by: ADR-[NNNN]` and add the new entry.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user