ksh999000/Claude-Code-Game-Studios
1
0
Fork 0
mirror of https://github.com/Donchitos/Claude-Code-Game-Studios.git synced 2026-06-27 04:51:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Pipeline integrity + brownfield adoption system

Browse Source 
Pipeline integrity (4 fixes for snapshot-vs-live-reference problem):
- NEW docs/architecture/tr-registry.yaml: persistent stable TR-IDs per GDD
  requirement; /architecture-review bootstraps and appends, never renumbers
- /create-control-manifest: added Manifest Version stamp to header
- /create-epics-stories: stories embed TR-ID reference (not quoted text),
  Manifest Version from manifest, ADR status gate (Proposed → Blocked)
- /story-done: TR-ID registry lookup at review time, manifest staleness check
- /story-readiness: ADR Accepted check, TR-ID validity, manifest version check
- /review-all-gdds + /architecture-review: fixed parenthetical status values
  ("Needs Revision" only, no parentheticals that break exact-match reads)

Workflow infrastructure:
- NEW /help skill: context-aware "what's next" using workflow-catalog.yaml
- NEW .claude/docs/workflow-catalog.yaml: YAML-driven phase/step sequence
- /sprint-plan + /sprint-status: sprint-status.yaml machine-written tracking

Brownfield adoption system (migrate, not replace):
- NEW /adopt skill: format compliance audit (not existence check); classifies
  gaps BLOCKING/HIGH/MEDIUM/LOW; produces docs/adoption-plan-[date].md with
  numbered migration plan; never regenerates existing artifacts
- /design-system retrofit [path]: fills only missing GDD sections, preserves
  all existing content
- /architecture-decision retrofit [path]: adds missing ADR sections (Status,
  ADR Dependencies, Engine Compatibility) without touching existing content
- /start option D: split into D1 (early-stage) and D2 (has GDDs/ADRs → adopt)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-03-11 18:46:07 +11:00
parent b1cad29b68
commit 0bbf25ec31
16 changed files with 1261 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

369
.claude/skills/adopt/SKILL.md Normal file
View File

@@ -0,0 +1,369 @@
---
name: adopt
description: "Brownfield onboarding — audits existing project artifacts for template format compliance (not just existence), classifies gaps by impact, and produces a numbered migration plan. Run this when joining an in-progress project or upgrading from an older template version. Distinct from /project-stage-detect (which checks what exists) — this checks whether what exists will actually work with the template's skills."
argument-hint: "[focus: full | gdds | adrs | stories | infra]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, AskUserQuestion
context: fork
agent: technical-director
---
# Adopt — Brownfield Template Adoption
This skill audits an existing project's artifacts for **format compliance** with
the template's skill pipeline, then produces a prioritised migration plan.
**This is not `/project-stage-detect`.**
`/project-stage-detect` answers: *what exists?*
`/adopt` answers: *will what exists actually work with the template's skills?*
A project can have GDDs, ADRs, and stories — and every format-sensitive skill
will still fail silently or produce wrong results if those artifacts are in the
wrong internal format.
**Output:** `docs/adoption-plan-[date].md` — a persistent, checkable migration plan.
**Argument modes:**
- **No argument / `full`**: Complete audit — all artifact types
- **`gdds`**: GDD format compliance only
- **`adrs`**: ADR format compliance only
- **`stories`**: Story format compliance only
- **`infra`**: Infrastructure artifact gaps only (registry, manifest, sprint-status, stage.txt)
---
## Phase 1: Detect Project State
Read silently before presenting anything.
### Existence check
- `production/stage.txt` — if present, read it (authoritative phase)
- `design/gdd/game-concept.md` — concept exists?
- `design/gdd/systems-index.md` — systems index exists?
- Count GDD files: `design/gdd/*.md` (excluding game-concept.md and systems-index.md)
- Count ADR files: `docs/architecture/adr-*.md`
- Count story files: `production/epics/**/*.md` (excluding EPIC.md)
- `.claude/docs/technical-preferences.md` — engine configured?
- `docs/engine-reference/` — engine reference docs present?
### Infer phase (if no stage.txt)
Use the same heuristic as `/project-stage-detect`:
- 10+ source files in `src/` → Production
- Stories in `production/epics/` → Pre-Production
- ADRs exist → Technical Setup
- systems-index.md exists → Systems Design
- game-concept.md exists → Concept
- Nothing → Fresh (not a brownfield project — suggest `/start`)
If the project appears fresh (no artifacts at all), stop:
> "This looks like a fresh project with no existing artifacts. Run `/start`
> instead — `/adopt` is for projects that already have work to migrate."
Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."
---
## Phase 2: Format Audit
For each artifact type in scope (based on argument mode), check not just that
the file exists but that it contains the internal structure the template requires.
### 2a: GDD Format Audit
For each GDD file found, check for the 8 required sections by scanning headings:
| Required Section | Heading pattern to look for |
|---|---|
| Overview | `## Overview` |
| Player Fantasy | `## Player Fantasy` |
| Detailed Rules / Design | `## Detailed` or `## Core Rules` or `## Detailed Design` |
| Formulas | `## Formulas` or `## Formula` |
| Edge Cases | `## Edge Cases` |
| Dependencies | `## Dependencies` or `## Depends` |
| Tuning Knobs | `## Tuning` |
| Acceptance Criteria | `## Acceptance` |
For each GDD, record:
- Which sections are present
- Which sections are missing
- Whether it has any content in present sections or just placeholder text
(`[To be designed]` or equivalent)
Also check: does each GDD have a `**Status**:` field in its header block?
Valid values: `In Design`, `Designed`, `In Review`, `Approved`, `Needs Revision`.
### 2b: ADR Format Audit
For each ADR file found, check for these critical sections:
| Section | Impact if missing |
|---|---|
| `## Status` | **BLOCKING** — `/story-readiness` ADR status check silently passes everything |
| `## ADR Dependencies` | HIGH — dependency ordering in `/architecture-review` breaks |
| `## Engine Compatibility` | HIGH — post-cutoff API risk is unknown |
| `## GDD Requirements Addressed` | MEDIUM — traceability matrix loses coverage |
| `## Performance Implications` | LOW — not pipeline-critical |
For each ADR, record: which sections present, which missing, current Status value
if the Status section exists.
### 2c: systems-index.md Format Audit
If `design/gdd/systems-index.md` exists:
1. **Parenthetical status values** — Grep for any Status cell containing
parentheses: `"Needs Revision ("`, `"In Progress ("`, etc.
These break exact-string matching in `/gate-check`, `/create-epics-stories`,
and `/architecture-review`. **BLOCKING.**
2. **Valid status values** — check that Status column values are only from:
`Not Started`, `In Progress`, `In Review`, `Designed`, `Approved`, `Needs Revision`
Flag any unrecognised values.
3. **Column structure** — check that the table has at minimum: System name,
Layer, Priority, Status columns. Missing columns degrade skill functionality.
### 2d: Story Format Audit
For each story file found:
- **`Manifest Version:` field** — present in story header? (LOW — auto-passes if absent)
- **TR-ID reference** — does story contain `TR-[a-z]+-[0-9]+` pattern? (MEDIUM — no staleness tracking)
- **ADR reference** — does story reference at least one ADR? (check for `ADR-` pattern)
- **Status field** — present and readable?
- **Acceptance criteria** — does the story have a checkbox list (`- [ ]`)?
### 2e: Infrastructure Audit
| Artifact | Path | Impact if missing |
|---|---|---|
| TR registry | `docs/architecture/tr-registry.yaml` | HIGH — no stable requirement IDs |
| Control manifest | `docs/architecture/control-manifest.md` | HIGH — no layer rules for stories |
| Manifest version stamp | In manifest header: `Manifest Version:` | MEDIUM — staleness checks blind |
| Sprint status | `production/sprint-status.yaml` | MEDIUM — `/sprint-status` falls back to markdown |
| Stage file | `production/stage.txt` | MEDIUM — phase auto-detect unreliable |
| Engine reference | `docs/engine-reference/[engine]/VERSION.md` | HIGH — ADR engine checks blind |
| Architecture traceability | `docs/architecture/architecture-traceability.md` | MEDIUM — no persistent matrix |
### 2f: Technical Preferences Audit
Read `.claude/docs/technical-preferences.md`. Check each field for `[TO BE CONFIGURED]`:
- Engine, Language, Rendering, Physics → HIGH if unconfigured (ADR skills fail)
- Naming conventions → MEDIUM
- Performance budgets → MEDIUM
- Forbidden Patterns, Allowed Libraries → LOW (starts empty by design)
---
## Phase 3: Classify and Prioritise Gaps
Organise every gap found across all audits into four severity tiers:
**BLOCKING** — Will cause template skills to silently produce wrong results *right now*.
Examples: ADR missing Status field, systems-index parenthetical status values,
engine not configured when ADRs exist.
**HIGH** — Will cause stories to be generated with missing safety checks, or
infrastructure bootstrapping will fail.
Examples: ADRs missing Engine Compatibility, GDDs missing Acceptance Criteria
(stories can't be generated from them), tr-registry.yaml missing.
**MEDIUM** — Degrades quality and pipeline tracking but does not break functionality.
Examples: GDDs missing Tuning Knobs or Formulas sections, stories missing TR-IDs,
sprint-status.yaml missing.
**LOW** — Retroactive improvements that are nice-to-have but not urgent.
Examples: Stories missing Manifest Version stamps, GDDs missing Open Questions section.
Count totals per tier. If zero BLOCKING and zero HIGH gaps: report that the project
is template-compatible and only advisory improvements remain.
---
## Phase 4: Build the Migration Plan
Compose a numbered, ordered action plan. Ordering rules:
1. BLOCKING gaps first (must fix before any pipeline skill runs reliably)
2. HIGH gaps next, infrastructure before GDD/ADR content (bootstrapping needs correct formats)
3. MEDIUM gaps ordered: GDD gaps before ADR gaps before story gaps (stories depend on GDDs and ADRs)
4. LOW gaps last
For each gap, produce a plan entry with:
- A clear problem statement (one sentence, no jargon)
- The exact command to fix it, if a skill handles it
- Manual steps if it requires direct editing
- A time estimate (rough: 5 min / 30 min / 1 session)
- A checkbox `- [ ]` for tracking
**Special case — systems-index parenthetical status values:**
This is always the first item if present. Show the exact values that need changing
and the exact replacement text. Offer to fix this immediately before writing the plan.
**Special case — ADRs missing Status field:**
For each affected ADR, the fix is:
`/architecture-decision retrofit docs/architecture/adr-[NNNN]-[slug].md`
List each ADR as a separate checkable item.
**Special case — GDDs missing sections:**
For each affected GDD, list which sections are missing and the fix:
`/design-system retrofit design/gdd/[filename].md`
**Infrastructure bootstrap ordering** — always present in this sequence:
1. Fix ADR formats first (registry depends on reading ADR Status fields)
2. Run `/architecture-review` → bootstraps `tr-registry.yaml`
3. Run `/create-control-manifest` → creates manifest with version stamp
4. Run `/sprint-plan update` → creates `sprint-status.yaml`
5. Run `/gate-check [phase]` → writes `stage.txt` authoritatively
**Existing stories** — note explicitly:
> "Existing stories continue to work with all template skills — all new format
> checks auto-pass when the fields are absent. They won't benefit from TR-ID
> staleness tracking or manifest version checks until they're regenerated. This
> is intentional: do not regenerate stories that are already in progress."
---
## Phase 5: Present Summary and Ask to Write
Present a compact summary before writing:
```
## Adoption Audit Summary
Phase detected: [phase]
Engine: [configured / NOT CONFIGURED]
GDDs audited: [N] ([X] fully compliant, [Y] with gaps)
ADRs audited: [N] ([X] fully compliant, [Y] with gaps)
Stories audited: [N]
Gap counts:
BLOCKING: [N] — template skills will malfunction without these fixes
HIGH: [N] — unsafe to run /create-epics-stories or /story-readiness
MEDIUM: [N] — quality degradation
LOW: [N] — optional improvements
Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]
```
Ask: "May I write the full migration plan to `docs/adoption-plan-[date].md`?"
---
## Phase 6: Write the Adoption Plan
If approved, write `docs/adoption-plan-[date].md` with this structure:
```markdown
# Adoption Plan
> **Generated**: [date]
> **Project phase**: [phase]
> **Engine**: [name + version, or "Not configured"]
> **Template version**: v0.4.0+
Work through these steps in order. Check off each item as you complete it.
Re-run `/adopt` anytime to check remaining gaps.
---
## Step 1: Fix Blocking Gaps
[One sub-section per blocking gap with problem, fix command, time estimate, checkbox]
---
## Step 2: Fix High-Priority Gaps
[One sub-section per high gap]
---
## Step 3: Bootstrap Infrastructure
### 3a. Register existing requirements (creates tr-registry.yaml)
Run `/architecture-review` — even if ADRs already exist, this run bootstraps
the TR registry from your existing GDDs and ADRs.
**Time**: 1 session (review can be long for large codebases)
- [ ] tr-registry.yaml created
### 3b. Create control manifest
Run `/create-control-manifest`
**Time**: 30 min
- [ ] docs/architecture/control-manifest.md created
### 3c. Create sprint tracking file
Run `/sprint-plan update`
**Time**: 5 min (if sprint plan already exists as markdown)
- [ ] production/sprint-status.yaml created
### 3d. Set authoritative project stage
Run `/gate-check [current-phase]`
**Time**: 5 min
- [ ] production/stage.txt written
---
## Step 4: Medium-Priority Gaps
[One sub-section per medium gap]
---
## Step 5: Optional Improvements
[One sub-section per low gap]
---
## What to Expect from Existing Stories
Existing stories continue to work with all template skills. New format checks
(TR-ID validation, manifest version staleness) auto-pass when the fields are
absent — so nothing breaks. They won't benefit from staleness tracking until
regenerated. Do not regenerate stories that are in progress or done.
---
## Re-run
Run `/adopt` again after completing Step 3 to verify all blocking and high gaps
are resolved. The new run will reflect the current state of the project.
```
---
## Phase 7: Offer First Action
After writing the plan, don't stop there. Pick the single highest-priority gap
and offer to handle it immediately:
If there are parenthetical status values in systems-index.md:
> "The most urgent fix is the systems-index.md status values — this breaks
> multiple skills right now. I can fix these in-place in under 2 minutes.
> Shall I edit the file now?"
If ADRs are missing Status fields:
> "The most urgent fix is adding Status fields to your ADRs. Shall I start
> with `docs/architecture/adr-0001.md` using `/architecture-decision retrofit`?"
If GDDs are missing Acceptance Criteria:
> "The most important GDD gap is missing Acceptance Criteria — without these,
> `/create-epics-stories` can't generate stories. Shall I start with
> `design/gdd/[highest-priority-system].md` using `/design-system retrofit`?"
Use `AskUserQuestion`:
- "What would you like to do now?"
- Options: "Fix [most urgent gap] now", "Review the full plan first",
"I'll work through the plan myself", "Run `/project-stage-detect` for broader context"
---
## Collaborative Protocol
1. **Read silently** — complete the full audit before presenting anything
2. **Show the summary first** — let the user see scope before asking to write
3. **Ask before writing** — always confirm before creating the adoption plan file
4. **Offer, don't force** — the plan is advisory; the user decides what to fix and when
5. **One action at a time** — after handing off the plan, offer one specific next step,
not a list of six things to do simultaneously
6. **Never regenerate existing artifacts** — only fill gaps in what exists;
do not rewrite GDDs, ADRs, or stories that already have content