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
@@ -13,7 +13,6 @@ Resolved above — use as-is. `/adopt` also inspects `project.yaml` and the lega
|
||||
config files directly when reporting and writing migration state; that raw
|
||||
inspection is deliberate and separate from the resolved values above.
|
||||
|
||||
|
||||
# Adopt — Brownfield Template Adoption
|
||||
|
||||
This skill audits an existing project's artifacts for **format compliance** with
|
||||
@@ -53,510 +52,31 @@ only the required docs/sections (optional sections are informational, not gaps);
|
||||
|
||||
## Phase 1: Detect Project State
|
||||
|
||||
Emit one line before reading: `"Scanning project artifacts..."` — this confirms the
|
||||
skill is running during the silent read phase.
|
||||
|
||||
Then read silently before presenting anything else.
|
||||
|
||||
### Existence check
|
||||
- `project.stage` in `project.yaml` (fallback `production/stage.txt`) — if either is present, use that value (authoritative phase)
|
||||
- `design/gdd/game-concept.md` (or, at the minimal tier, `design/game-brief.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)
|
||||
- `project.yaml` (`engine.name`) / `.claude/docs/technical-preferences.md` — engine configured?
|
||||
- `docs/engine-reference/` — engine reference docs present?
|
||||
- Glob `docs/adoption-plan-*.md` — note the filename of the most recent prior plan if any exist
|
||||
|
||||
### Infer phase (if no project.stage / stage.txt)
|
||||
Use the same heuristic as `/project-stage-detect`:
|
||||
- 10+ source files in the code root → Production
|
||||
- Stories in `production/epics/` → Pre-Production
|
||||
- ADRs exist → Technical Setup
|
||||
- systems-index.md exists → Systems Design
|
||||
- game-concept.md (or `design/game-brief.md`) exists → Concept
|
||||
- Nothing → Fresh (not a brownfield project — suggest `/start`)
|
||||
|
||||
If the project appears fresh (no artifacts at all), use `AskUserQuestion`:
|
||||
- "This looks like a fresh project — no existing artifacts found. `/adopt` is for
|
||||
projects with work to migrate. What would you like to do?"
|
||||
- "Run `/start` — begin guided first-time onboarding"
|
||||
- "My artifacts are in a non-standard location — help me find them"
|
||||
- "Cancel"
|
||||
|
||||
Then stop — do not proceed with the audit regardless of which option the user picks
|
||||
(each option leads to a different skill or manual investigation).
|
||||
|
||||
Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."
|
||||
|
||||
---
|
||||
**Read `references/1-detect.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## Phase 2: Format Audit
|
||||
|
||||
For each artifact type in scope (based on argument mode **and the resolved
|
||||
workflow tier**), check not just that the file exists but that it contains the
|
||||
internal structure the template requires. At `minimal`, scope the audit to
|
||||
`design/game-brief.md` — do not audit for GDDs, ADRs, or UX specs (they are not expected).
|
||||
Steps 2e (the Engine reference row only), 2f (project config) and 2g (v1.0
|
||||
migration check) run at every tier.
|
||||
|
||||
### 2a: GDD Format Audit
|
||||
|
||||
**Gather section presence deterministically — do not read the GDDs to count
|
||||
headings.** For each GDD discovered in Phase 1, pass its path explicitly to the
|
||||
structure-check script:
|
||||
|
||||
```
|
||||
Bash: bash .claude/scripts/gdd-structure-check.sh [path-to-gdd]
|
||||
```
|
||||
|
||||
**Pass paths one at a time; do not invoke it bare.** The no-argument form sweeps
|
||||
`design/gdd/` only, and a brownfield project's GDDs are not guaranteed to live
|
||||
there — pass whatever paths Phase 1 found. The script prints a `PRESENT:` list
|
||||
and, when applicable, an `ABSENT:` list per file. It reports **presence only**
|
||||
and makes no REQUIRED/ADVISORY judgment (that is the tier logic below), and it
|
||||
already accepts `## Detailed Design` as satisfying the `Detailed Rules`
|
||||
requirement, so do not flag that alias as missing.
|
||||
|
||||
If the script prints `Not found:` for a path or errors, that is a **discovery
|
||||
failure, not a format gap** — report it as "could not audit [path]" and do not
|
||||
count it as a missing-sections finding.
|
||||
|
||||
**Then apply the workflow tier** resolved above to each file's PRESENT/ABSENT
|
||||
lists. Which sections are **required** (a miss = gap) vs **advisory** (a miss =
|
||||
informational):
|
||||
- **`full`** — all 8 sections are required.
|
||||
- **`standard`** — the 5 required (Overview, Detailed Rules, Edge Cases,
|
||||
Dependencies, Acceptance Criteria) + Formulas for any system that defines
|
||||
numeric rules (rates, curves, thresholds, costs — the system's `Category` is a
|
||||
hint, not the test); Player Fantasy and Tuning Knobs are advisory.
|
||||
- **`minimal`** — GDDs are not expected; audit `design/game-brief.md` instead,
|
||||
against `.claude/docs/templates/game-brief.md`: each of the six required fields
|
||||
present and not a placeholder; the three one-liners advisory. Any GDD that
|
||||
does exist is checked at the `standard` bar, advisorily.
|
||||
|
||||
The script's 8 canonical labels are: Overview, Player Fantasy, Detailed Rules,
|
||||
Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
|
||||
|
||||
A section reported PRESENT can still be an empty heading. For each GDD, also
|
||||
record with a targeted grep (not a full read):
|
||||
- Placeholder-only sections — `Grep pattern="\[To be designed\]"` (or an
|
||||
equivalent empty/single-line body) marks a present-but-unwritten section.
|
||||
- The `**Status**:` header field — `Grep pattern="^>?[[:space:]]*\*\*Status\*\*:"`.
|
||||
Valid values: `Draft`, `In Design`, `Designed`, `In Review`, `Approved`,
|
||||
`Implemented`, `Needs Revision`.
|
||||
|
||||
> **The `>?` is load-bearing, and so are `Draft`/`Implemented`.** Both emitters
|
||||
> write this field inside a blockquote — `.claude/docs/templates/game-design-document.md`
|
||||
> and `/design-system` produce `> **Status**: …` — so an anchor of
|
||||
> `^\*\*Status\*\*:` matches nothing and reports *every* template-compliant GDD
|
||||
> as missing its Status. The template's own value list offers `Draft` and
|
||||
> `Implemented`, so both must count as valid.
|
||||
|
||||
### 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-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 | `project.stage` in `project.yaml` (fallback `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/requirements-traceability.md` | MEDIUM — no persistent matrix |
|
||||
|
||||
At `workflow: minimal` only the Engine reference row applies. The TR registry,
|
||||
control manifest and its version stamp, sprint status, stage file and
|
||||
traceability matrix are not on the minimal path, so their absence is not a gap.
|
||||
|
||||
### 2f: Project Config Audit
|
||||
|
||||
Read `project.yaml` (the primary config store) and `.claude/docs/technical-preferences.md` (legacy mirror). A setting counts as configured if EITHER source has a real value (in technical-preferences.md, `[TO BE CONFIGURED]` means unconfigured):
|
||||
- `engine.name`/`version`/`language`/`rendering`/`physics` (else the Engine/Language/Rendering/Physics fields) → HIGH if unconfigured in both (ADR skills fail)
|
||||
- `naming.*` (else Naming conventions) → MEDIUM
|
||||
- `performance.*` (else Performance budgets) → MEDIUM
|
||||
- Forbidden Patterns, Allowed Libraries (technical-preferences.md only — not migrated to project.yaml) → LOW (starts empty by design)
|
||||
|
||||
### 2g: v1.0 Migration Check
|
||||
|
||||
A project is a **v1.0 project needing migration** when `project.yaml` does NOT
|
||||
exist at the repo root AND at least one legacy file does: `production/stage.txt`,
|
||||
`production/review-mode.txt`, or a `.claude/docs/technical-preferences.md` with
|
||||
real values.
|
||||
|
||||
"Real values" means one of the keys the converter actually migrates — Engine,
|
||||
Language, Rendering, Physics, the naming, platform and performance fields,
|
||||
Framework, or the specialists. Not merely "some bullet is filled in": the
|
||||
shipped template ships one prose default (`- **Required Tests**: …`) that is
|
||||
never migrated, and counting it made every fresh clone read as a v1.0 project.
|
||||
|
||||
Do not hand-migrate. Run the converter, which is deterministic and covered by
|
||||
the framework's own test suite:
|
||||
|
||||
```bash
|
||||
bash .claude/scripts/migrate-v1-config.sh --dry-run
|
||||
```
|
||||
|
||||
The dry run writes nothing; record what it lists for the report. Do not run the
|
||||
converter during the audit — Phase 2 reads silently. The migration is
|
||||
classified BLOCKING in Phase 3, heads the plan, and **Phase 7 offers it as the
|
||||
first action**: report what the dry run listed, then ask "May I run the
|
||||
converter? It writes `project.yaml` and `production/migration-report.md`." If
|
||||
the user approves, run it without `--dry-run`. It
|
||||
writes `project.yaml` plus `production/migration-report.md` and **deletes
|
||||
nothing** — the whole operation stays reversible with `git checkout`.
|
||||
|
||||
Then tell the user to read `production/migration-report.md` before running:
|
||||
|
||||
```bash
|
||||
bash .claude/scripts/migrate-v1-config.sh --finalize
|
||||
```
|
||||
|
||||
`--finalize` deletes a legacy file only after proving its value is present in
|
||||
`project.yaml`; on mismatch it deletes nothing and exits 4. It never deletes
|
||||
`technical-preferences.md`, which still holds Forbidden Patterns and Allowed
|
||||
Libraries.
|
||||
|
||||
**If the script refuses with exit 3**, do not work around it. Exit 3 means one
|
||||
of two things, and the message says which:
|
||||
|
||||
- **the values DISAGREE** — two sources of truth and no way to know which the
|
||||
user edited last. Surface it and let them decide.
|
||||
- **a `production/migration-report.md` is already present** — a migration ran
|
||||
here, so these are post-migration leftovers and `--finalize` is the next step,
|
||||
not a second `migrate`.
|
||||
|
||||
Both files merely *existing* is not exit 3 and must not be reported as a
|
||||
conflict: `/start` writes `production/stage.txt` on every new v1.1 project as a
|
||||
mirror, so agreement is the normal state. The script says
|
||||
`the legacy files mirror it (values agree)` and exits 0 for that.
|
||||
|
||||
Classify as **BLOCKING** in Phase 3: until migration runs, every skill reads
|
||||
config through the legacy fallback chain, and v1.1 settings are unavailable.
|
||||
|
||||
---
|
||||
**Read `references/2-format-audit.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
**Read `references/3-classify.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## 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]` (the gate into the phase the project is in; at Concept there is none — Concept is the default stage, nothing to run) → writes `project.stage` in `project.yaml` (and legacy `stage.txt`) authoritatively
|
||||
|
||||
**At `workflow: minimal` the plan prescribes none of this sequence.** None of it
|
||||
is on the minimal path: ADRs are not expected, the brief's build order is the
|
||||
plan (no `/sprint-plan`), and nothing there runs `/gate-check`. The plan's
|
||||
Step 3 says so in one line and names the path's next step instead —
|
||||
`/create-stories` when no stories exist, else `/dev-story`.
|
||||
|
||||
**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."
|
||||
|
||||
---
|
||||
**Read `references/4-migration-plan.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## 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-stories or /story-readiness
|
||||
MEDIUM: [N] — quality degradation
|
||||
LOW: [N] — optional improvements
|
||||
|
||||
Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]
|
||||
```
|
||||
|
||||
Before asking to write, show a **Gap Preview**:
|
||||
- List every BLOCKING gap as a one-line bullet describing the actual problem
|
||||
(e.g. `systems-index.md: 3 rows have parenthetical status values`,
|
||||
`adr-0002.md: missing ## Status section`). No counts — show the actual items.
|
||||
- Show HIGH / MEDIUM / LOW as counts only (e.g. `HIGH: 4, MEDIUM: 2, LOW: 1`).
|
||||
|
||||
This gives the user enough context to judge scope before committing to writing the file.
|
||||
|
||||
If a prior adoption plan was detected in Phase 1, add a note:
|
||||
> "A previous plan exists at `docs/adoption-plan-[prior-date].md`. The new plan will
|
||||
> reflect current project state — it does not diff against the prior run."
|
||||
|
||||
Use `AskUserQuestion`:
|
||||
- "Ready to write the migration plan?"
|
||||
- "Yes — write `docs/adoption-plan-[date].md`"
|
||||
- "Show me the full plan preview first (don't write yet)"
|
||||
- "Cancel — I'll handle migration manually"
|
||||
|
||||
If the user picks "Show me the full plan preview", output the complete plan as a
|
||||
fenced markdown block. Then ask again with the same three options.
|
||||
|
||||
---
|
||||
**Read `references/5-summary.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## 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**: v1.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
|
||||
|
||||
[At `workflow: minimal`, replace 3a–3d with one line: "Not on the minimal path —
|
||||
the brief's build order is the plan. Next: `/create-stories` (or `/dev-story`
|
||||
once stories exist)."]
|
||||
|
||||
### 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]` (the gate into the phase the project is in;
|
||||
at Concept there is none — Concept is the default stage, nothing to run)
|
||||
**Time**: 5 min
|
||||
- [ ] `project.stage` in `project.yaml` written (legacy `production/stage.txt` also updated)
|
||||
|
||||
---
|
||||
|
||||
## 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 6b: Report Review Mode
|
||||
|
||||
**Do not write a review mode.** `modes.review_mode` is one of the six knobs
|
||||
`modes.rigor` fronts: pinning it in `project.yaml` shadows the rigor expansion, and
|
||||
the legacy `production/review-mode.txt` sits *above* that expansion in resolution,
|
||||
so either write would freeze director-review depth for good — the rule `/start`
|
||||
and `project.yaml`'s header comment both state.
|
||||
|
||||
Report the value the bootstrap above resolved instead: "Review mode resolves to
|
||||
`[value]` — from `modes.rigor`, unless something pins it." If the user wants a
|
||||
different depth, point them to changing `modes.rigor`, or to pinning it on purpose
|
||||
with `/settings --local modes.review_mode=<full|lean|solo>` (a personal override in
|
||||
`project.local.yaml`).
|
||||
|
||||
---
|
||||
**Read `references/6-write.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## 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 using `AskUserQuestion`. Choose the first
|
||||
branch that applies:
|
||||
|
||||
**If Phase 2g found a v1.0 project needing migration:** offer the converter run
|
||||
described there — report what the dry run listed and ask "May I run the
|
||||
converter? It writes `project.yaml` and `production/migration-report.md`."
|
||||
Every other fix reads config through it, so it comes first.
|
||||
|
||||
**If there are parenthetical status values in systems-index.md:**
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent fix is `systems-index.md` — [N] rows have parenthetical status
|
||||
values (e.g. `Needs Revision (see notes)`) that break /gate-check,
|
||||
/create-stories, and /architecture-review right now. I can fix these in-place."
|
||||
- "Fix it now — edit systems-index.md"
|
||||
- "I'll fix it myself"
|
||||
- "Done — leave me with the plan"
|
||||
|
||||
**If ADRs are missing `## Status` (and no parenthetical issue):**
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent fix is adding `## Status` to [N] ADR(s): [list filenames].
|
||||
Without it, /story-readiness silently passes all ADR checks. Start with
|
||||
[first affected filename]?"
|
||||
- "Yes — retrofit [first affected filename] now"
|
||||
- "Retrofit all [N] ADRs one by one"
|
||||
- "I'll handle ADRs myself"
|
||||
|
||||
**If GDDs are missing Acceptance Criteria (and no blocking issues above):**
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent gap is missing Acceptance Criteria in [N] GDD(s):
|
||||
[list filenames]. Without them, /create-stories can't generate stories.
|
||||
Start with [highest-priority GDD filename]?"
|
||||
- "Yes — add Acceptance Criteria to [GDD filename] now"
|
||||
- "Do all [N] GDDs one by one"
|
||||
- "I'll handle GDDs myself"
|
||||
|
||||
**Otherwise, if any BLOCKING or HIGH gap remains** (one no branch above names —
|
||||
e.g. a missing TR registry):
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent remaining gap is [first BLOCKING or HIGH item in the plan] —
|
||||
[one line on what it breaks]. Start on it now?"
|
||||
- "Yes — start on [item]"
|
||||
- "Show me that plan item first"
|
||||
- "Done — leave me with the plan"
|
||||
|
||||
**If no BLOCKING or HIGH gaps exist:**
|
||||
Use `AskUserQuestion`:
|
||||
- "No blocking gaps — this project is template-compatible. What next?"
|
||||
- "Walk me through the medium-priority improvements"
|
||||
- "Run /project-stage-detect for a broader health check"
|
||||
- "Done — I'll work through the plan at my own pace"
|
||||
|
||||
> **Adoption plan saved to `docs/adoption-plan-[date].md`.** Re-run `/adopt` at any time to re-check remaining gaps as you complete them.
|
||||
|
||||
---
|
||||
**Read `references/7-first-action.md` now and follow it** — this phase's steps are in that file, not here. Read it again if the conversation was compacted or resumed during this phase.
|
||||
|
||||
## Collaborative Protocol
|
||||
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# /adopt — Phase 1: Detect Project State
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## Phase 1: Detect Project State
|
||||
|
||||
Emit one line before reading: `"Scanning project artifacts..."` — this confirms the
|
||||
skill is running during the silent read phase.
|
||||
|
||||
Then read silently before presenting anything else.
|
||||
|
||||
### Existence check
|
||||
- `project.stage` in `project.yaml` (fallback `production/stage.txt`) — if either is present, use that value (authoritative phase)
|
||||
- `design/gdd/game-concept.md` (or, at the minimal tier, `design/game-brief.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)
|
||||
- `project.yaml` (`engine.name`) / `.claude/docs/technical-preferences.md` — engine configured?
|
||||
- `docs/engine-reference/` — engine reference docs present?
|
||||
- Glob `docs/adoption-plan-*.md` — note the filename of the most recent prior plan if any exist
|
||||
|
||||
### Infer phase (if no project.stage / stage.txt)
|
||||
Use the same heuristic as `/project-stage-detect`:
|
||||
- 10+ source files in the code root → Production
|
||||
- Stories in `production/epics/` → Pre-Production
|
||||
- ADRs exist → Technical Setup
|
||||
- systems-index.md exists → Systems Design
|
||||
- game-concept.md (or `design/game-brief.md`) exists → Concept
|
||||
- Nothing → Fresh (not a brownfield project — suggest `/start`)
|
||||
|
||||
If the project appears fresh (no artifacts at all), use `AskUserQuestion`:
|
||||
- "This looks like a fresh project — no existing artifacts found. `/adopt` is for
|
||||
projects with work to migrate. What would you like to do?"
|
||||
- "Run `/start` — begin guided first-time onboarding"
|
||||
- "My artifacts are in a non-standard location — help me find them"
|
||||
- "Cancel"
|
||||
|
||||
Then stop — do not proceed with the audit regardless of which option the user picks
|
||||
(each option leads to a different skill or manual investigation).
|
||||
|
||||
Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."
|
||||
|
||||
---
|
||||
@@ -0,0 +1,200 @@
|
||||
# /adopt — Phase 2: Format Audit
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## Phase 2: Format Audit
|
||||
|
||||
**In this file:**
|
||||
|
||||
- 2a: GDD Format Audit
|
||||
- 2b: ADR Format Audit
|
||||
- 2c: systems-index.md Format Audit
|
||||
- 2d: Story Format Audit
|
||||
- 2e: Infrastructure Audit
|
||||
- 2f: Project Config Audit
|
||||
- 2g: v1.0 Migration Check
|
||||
|
||||
For each artifact type in scope (based on argument mode **and the resolved
|
||||
workflow tier**), check not just that the file exists but that it contains the
|
||||
internal structure the template requires. At `minimal`, scope the audit to
|
||||
`design/game-brief.md` — do not audit for GDDs, ADRs, or UX specs (they are not expected).
|
||||
Steps 2e (the Engine reference row only), 2f (project config) and 2g (v1.0
|
||||
migration check) run at every tier.
|
||||
|
||||
### 2a: GDD Format Audit
|
||||
|
||||
**Gather section presence deterministically — do not read the GDDs to count
|
||||
headings.** For each GDD discovered in Phase 1, pass its path explicitly to the
|
||||
structure-check script:
|
||||
|
||||
```
|
||||
Bash: bash .claude/scripts/gdd-structure-check.sh [path-to-gdd]
|
||||
```
|
||||
|
||||
**Pass paths one at a time; do not invoke it bare.** The no-argument form sweeps
|
||||
`design/gdd/` only, and a brownfield project's GDDs are not guaranteed to live
|
||||
there — pass whatever paths Phase 1 found. The script prints a `PRESENT:` list
|
||||
and, when applicable, an `ABSENT:` list per file. It reports **presence only**
|
||||
and makes no REQUIRED/ADVISORY judgment (that is the tier logic below), and it
|
||||
already accepts `## Detailed Design` as satisfying the `Detailed Rules`
|
||||
requirement, so do not flag that alias as missing.
|
||||
|
||||
If the script prints `Not found:` for a path or errors, that is a **discovery
|
||||
failure, not a format gap** — report it as "could not audit [path]" and do not
|
||||
count it as a missing-sections finding.
|
||||
|
||||
**Then apply the workflow tier** resolved above to each file's PRESENT/ABSENT
|
||||
lists. Which sections are **required** (a miss = gap) vs **advisory** (a miss =
|
||||
informational):
|
||||
- **`full`** — all 8 sections are required.
|
||||
- **`standard`** — the 5 required (Overview, Detailed Rules, Edge Cases,
|
||||
Dependencies, Acceptance Criteria) + Formulas for any system that defines
|
||||
numeric rules (rates, curves, thresholds, costs — the system's `Category` is a
|
||||
hint, not the test); Player Fantasy and Tuning Knobs are advisory.
|
||||
- **`minimal`** — GDDs are not expected; audit `design/game-brief.md` instead,
|
||||
against `.claude/docs/templates/game-brief.md`: each of the six required fields
|
||||
present and not a placeholder; the three one-liners advisory. Any GDD that
|
||||
does exist is checked at the `standard` bar, advisorily.
|
||||
|
||||
The script's 8 canonical labels are: Overview, Player Fantasy, Detailed Rules,
|
||||
Formulas, Edge Cases, Dependencies, Tuning Knobs, Acceptance Criteria.
|
||||
|
||||
A section reported PRESENT can still be an empty heading. For each GDD, also
|
||||
record with a targeted grep (not a full read):
|
||||
- Placeholder-only sections — `Grep pattern="\[To be designed\]"` (or an
|
||||
equivalent empty/single-line body) marks a present-but-unwritten section.
|
||||
- The `**Status**:` header field — `Grep pattern="^>?[[:space:]]*\*\*Status\*\*:"`.
|
||||
Valid values: `Draft`, `In Design`, `Designed`, `In Review`, `Approved`,
|
||||
`Implemented`, `Needs Revision`.
|
||||
|
||||
> **The `>?` is load-bearing, and so are `Draft`/`Implemented`.** Both emitters
|
||||
> write this field inside a blockquote — `.claude/docs/templates/game-design-document.md`
|
||||
> and `/design-system` produce `> **Status**: …` — so an anchor of
|
||||
> `^\*\*Status\*\*:` matches nothing and reports *every* template-compliant GDD
|
||||
> as missing its Status. The template's own value list offers `Draft` and
|
||||
> `Implemented`, so both must count as valid.
|
||||
|
||||
### 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-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 | `project.stage` in `project.yaml` (fallback `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/requirements-traceability.md` | MEDIUM — no persistent matrix |
|
||||
|
||||
At `workflow: minimal` only the Engine reference row applies. The TR registry,
|
||||
control manifest and its version stamp, sprint status, stage file and
|
||||
traceability matrix are not on the minimal path, so their absence is not a gap.
|
||||
|
||||
### 2f: Project Config Audit
|
||||
|
||||
Read `project.yaml` (the primary config store) and `.claude/docs/technical-preferences.md` (legacy mirror). A setting counts as configured if EITHER source has a real value (in technical-preferences.md, `[TO BE CONFIGURED]` means unconfigured):
|
||||
- `engine.name`/`version`/`language`/`rendering`/`physics` (else the Engine/Language/Rendering/Physics fields) → HIGH if unconfigured in both (ADR skills fail)
|
||||
- `naming.*` (else Naming conventions) → MEDIUM
|
||||
- `performance.*` (else Performance budgets) → MEDIUM
|
||||
- Forbidden Patterns, Allowed Libraries (technical-preferences.md only — not migrated to project.yaml) → LOW (starts empty by design)
|
||||
|
||||
### 2g: v1.0 Migration Check
|
||||
|
||||
A project is a **v1.0 project needing migration** when `project.yaml` does NOT
|
||||
exist at the repo root AND at least one legacy file does: `production/stage.txt`,
|
||||
`production/review-mode.txt`, or a `.claude/docs/technical-preferences.md` with
|
||||
real values.
|
||||
|
||||
"Real values" means one of the keys the converter actually migrates — Engine,
|
||||
Language, Rendering, Physics, the naming, platform and performance fields,
|
||||
Framework, or the specialists. Not merely "some bullet is filled in": the
|
||||
shipped template ships one prose default (`- **Required Tests**: …`) that is
|
||||
never migrated, and counting it made every fresh clone read as a v1.0 project.
|
||||
|
||||
Do not hand-migrate. Run the converter, which is deterministic and covered by
|
||||
the framework's own test suite:
|
||||
|
||||
```bash
|
||||
bash .claude/scripts/migrate-v1-config.sh --dry-run
|
||||
```
|
||||
|
||||
The dry run writes nothing; record what it lists for the report. Do not run the
|
||||
converter during the audit — Phase 2 reads silently. The migration is
|
||||
classified BLOCKING in Phase 3, heads the plan, and **Phase 7 offers it as the
|
||||
first action**: report what the dry run listed, then ask "May I run the
|
||||
converter? It writes `project.yaml` and `production/migration-report.md`." If
|
||||
the user approves, run it without `--dry-run`. It
|
||||
writes `project.yaml` plus `production/migration-report.md` and **deletes
|
||||
nothing** — the whole operation stays reversible with `git checkout`.
|
||||
|
||||
Then tell the user to read `production/migration-report.md` before running:
|
||||
|
||||
```bash
|
||||
bash .claude/scripts/migrate-v1-config.sh --finalize
|
||||
```
|
||||
|
||||
`--finalize` deletes a legacy file only after proving its value is present in
|
||||
`project.yaml`; on mismatch it deletes nothing and exits 4. It never deletes
|
||||
`technical-preferences.md`, which still holds Forbidden Patterns and Allowed
|
||||
Libraries.
|
||||
|
||||
**If the script refuses with exit 3**, do not work around it. Exit 3 means one
|
||||
of two things, and the message says which:
|
||||
|
||||
- **the values DISAGREE** — two sources of truth and no way to know which the
|
||||
user edited last. Surface it and let them decide.
|
||||
- **a `production/migration-report.md` is already present** — a migration ran
|
||||
here, so these are post-migration leftovers and `--finalize` is the next step,
|
||||
not a second `migrate`.
|
||||
|
||||
Both files merely *existing* is not exit 3 and must not be reported as a
|
||||
conflict: `/start` writes `production/stage.txt` on every new v1.1 project as a
|
||||
mirror, so agreement is the normal state. The script says
|
||||
`the legacy files mirror it (values agree)` and exits 0 for that.
|
||||
|
||||
Classify as **BLOCKING** in Phase 3: until migration runs, every skill reads
|
||||
config through the legacy fallback chain, and v1.1 settings are unavailable.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,29 @@
|
||||
# /adopt — Phase 3: Classify and Prioritise Gaps
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,53 @@
|
||||
# /adopt — Phase 4: Build the Migration Plan
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## 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]` (the gate into the phase the project is in; at Concept there is none — Concept is the default stage, nothing to run) → writes `project.stage` in `project.yaml` (and legacy `stage.txt`) authoritatively
|
||||
|
||||
**At `workflow: minimal` the plan prescribes none of this sequence.** None of it
|
||||
is on the minimal path: ADRs are not expected, the brief's build order is the
|
||||
plan (no `/sprint-plan`), and nothing there runs `/gate-check`. The plan's
|
||||
Step 3 says so in one line and names the path's next step instead —
|
||||
`/create-stories` when no stories exist, else `/dev-story`.
|
||||
|
||||
**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."
|
||||
|
||||
---
|
||||
@@ -0,0 +1,48 @@
|
||||
# /adopt — Phase 5: Present Summary and Ask to Write
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## 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-stories or /story-readiness
|
||||
MEDIUM: [N] — quality degradation
|
||||
LOW: [N] — optional improvements
|
||||
|
||||
Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]
|
||||
```
|
||||
|
||||
Before asking to write, show a **Gap Preview**:
|
||||
- List every BLOCKING gap as a one-line bullet describing the actual problem
|
||||
(e.g. `systems-index.md: 3 rows have parenthetical status values`,
|
||||
`adr-0002.md: missing ## Status section`). No counts — show the actual items.
|
||||
- Show HIGH / MEDIUM / LOW as counts only (e.g. `HIGH: 4, MEDIUM: 2, LOW: 1`).
|
||||
|
||||
This gives the user enough context to judge scope before committing to writing the file.
|
||||
|
||||
If a prior adoption plan was detected in Phase 1, add a note:
|
||||
> "A previous plan exists at `docs/adoption-plan-[prior-date].md`. The new plan will
|
||||
> reflect current project state — it does not diff against the prior run."
|
||||
|
||||
Use `AskUserQuestion`:
|
||||
- "Ready to write the migration plan?"
|
||||
- "Yes — write `docs/adoption-plan-[date].md`"
|
||||
- "Show me the full plan preview first (don't write yet)"
|
||||
- "Cancel — I'll handle migration manually"
|
||||
|
||||
If the user picks "Show me the full plan preview", output the complete plan as a
|
||||
fenced markdown block. Then ask again with the same three options.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,113 @@
|
||||
# /adopt — Phases 6 and 6b: Write the Adoption Plan and Report Review Mode
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## Phase 6: Write the Adoption Plan
|
||||
|
||||
**In this file:**
|
||||
|
||||
- Phase 6: the adoption plan template, then the write
|
||||
- Phase 6b: Report Review Mode
|
||||
|
||||
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**: v1.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
|
||||
|
||||
[At `workflow: minimal`, replace 3a–3d with one line: "Not on the minimal path —
|
||||
the brief's build order is the plan. Next: `/create-stories` (or `/dev-story`
|
||||
once stories exist)."]
|
||||
|
||||
### 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]` (the gate into the phase the project is in;
|
||||
at Concept there is none — Concept is the default stage, nothing to run)
|
||||
**Time**: 5 min
|
||||
- [ ] `project.stage` in `project.yaml` written (legacy `production/stage.txt` also updated)
|
||||
|
||||
---
|
||||
|
||||
## 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 6b: Report Review Mode
|
||||
|
||||
**Do not write a review mode.** `modes.review_mode` is one of the six knobs
|
||||
`modes.rigor` fronts: pinning it in `project.yaml` shadows the rigor expansion, and
|
||||
the legacy `production/review-mode.txt` sits *above* that expansion in resolution,
|
||||
so either write would freeze director-review depth for good — the rule `/start`
|
||||
and `project.yaml`'s header comment both state.
|
||||
|
||||
Report the value the bootstrap above resolved instead: "Review mode resolves to
|
||||
`[value]` — from `modes.rigor`, unless something pins it." If the user wants a
|
||||
different depth, point them to changing `modes.rigor`, or to pinning it on purpose
|
||||
with `/settings --local modes.review_mode=<full|lean|solo>` (a personal override in
|
||||
`project.local.yaml`).
|
||||
|
||||
---
|
||||
@@ -0,0 +1,62 @@
|
||||
# /adopt — Phase 7: Offer First Action
|
||||
|
||||
> Part of `/adopt`. `SKILL.md` names when to read this file; the settings it
|
||||
> resolved and the rules under its later headings still apply here.
|
||||
|
||||
## 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 using `AskUserQuestion`. Choose the first
|
||||
branch that applies:
|
||||
|
||||
**If Phase 2g found a v1.0 project needing migration:** offer the converter run
|
||||
described there — report what the dry run listed and ask "May I run the
|
||||
converter? It writes `project.yaml` and `production/migration-report.md`."
|
||||
Every other fix reads config through it, so it comes first.
|
||||
|
||||
**If there are parenthetical status values in systems-index.md:**
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent fix is `systems-index.md` — [N] rows have parenthetical status
|
||||
values (e.g. `Needs Revision (see notes)`) that break /gate-check,
|
||||
/create-stories, and /architecture-review right now. I can fix these in-place."
|
||||
- "Fix it now — edit systems-index.md"
|
||||
- "I'll fix it myself"
|
||||
- "Done — leave me with the plan"
|
||||
|
||||
**If ADRs are missing `## Status` (and no parenthetical issue):**
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent fix is adding `## Status` to [N] ADR(s): [list filenames].
|
||||
Without it, /story-readiness silently passes all ADR checks. Start with
|
||||
[first affected filename]?"
|
||||
- "Yes — retrofit [first affected filename] now"
|
||||
- "Retrofit all [N] ADRs one by one"
|
||||
- "I'll handle ADRs myself"
|
||||
|
||||
**If GDDs are missing Acceptance Criteria (and no blocking issues above):**
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent gap is missing Acceptance Criteria in [N] GDD(s):
|
||||
[list filenames]. Without them, /create-stories can't generate stories.
|
||||
Start with [highest-priority GDD filename]?"
|
||||
- "Yes — add Acceptance Criteria to [GDD filename] now"
|
||||
- "Do all [N] GDDs one by one"
|
||||
- "I'll handle GDDs myself"
|
||||
|
||||
**Otherwise, if any BLOCKING or HIGH gap remains** (one no branch above names —
|
||||
e.g. a missing TR registry):
|
||||
Use `AskUserQuestion`:
|
||||
- "The most urgent remaining gap is [first BLOCKING or HIGH item in the plan] —
|
||||
[one line on what it breaks]. Start on it now?"
|
||||
- "Yes — start on [item]"
|
||||
- "Show me that plan item first"
|
||||
- "Done — leave me with the plan"
|
||||
|
||||
**If no BLOCKING or HIGH gaps exist:**
|
||||
Use `AskUserQuestion`:
|
||||
- "No blocking gaps — this project is template-compatible. What next?"
|
||||
- "Walk me through the medium-priority improvements"
|
||||
- "Run /project-stage-detect for a broader health check"
|
||||
- "Done — I'll work through the plan at my own pace"
|
||||
|
||||
> **Adoption plan saved to `docs/adoption-plan-[date].md`.** Re-run `/adopt` at any time to re-check remaining gaps as you complete them.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user