mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-06-27 04:51:46 +00:00
Release v0.3.0: /design-system, /map-systems, status line, UPGRADING guide (#2)
* Add UPGRADING.md migration guide and link from README Covers v0.1→v0.2 upgrade with three strategies (git merge, cherry-pick, manual copy), file safety categories, and post-upgrade verification steps. Structured to support future version sections. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Rename /design-systems to /map-systems + /design-system and fix all references Split the monolithic /design-systems skill into two focused skills: - /map-systems: systems decomposition and index creation - /design-system: guided section-by-section GDD authoring Updated all cross-references across 14 files: README, UPGRADING, WORKFLOW-GUIDE, quick-start, skills-reference, game-concept template, systems-index template, brainstorm, design-review, gate-check, project-stage-detect, setup-engine, and start skills. Fixed skill counts from 36 to 37 everywhere. Added /map-systems and /design-system to quick-start Paths A and B workflows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix cross-reference gaps, broken hooks, and stale workflow chains - Fix log-agent.sh parsing agent_type instead of agent_name (always logged "unknown") - Fix GDD status lifecycle: design-system now writes Approved/Designed/In Review - Clean up settings.local.json vestigial Bash grants from development - Delete orphaned docs marked for removal in UPGRADING.md - Add /design-system to next-steps in /start, /brainstorm, /setup-engine - Fix WORKFLOW-GUIDE: add /map-systems + /design-system to Appendix C Workflow 1 - Fix invalid /map-systems map argument in WORKFLOW-GUIDE Step 2.1 - Update map-systems frontmatter to document [system-name] argument - Update commit hook to validate all 8 required GDD sections (was 5) - Update README template count 28 → 29, add 5 missing templates to quick-start Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add custom status line with 7-stage production pipeline Introduces a status line showing context %, model name, and production stage at a glance. Aligns gate-check and project-stage-detect to a unified 7-stage model (Concept → Systems Design → Technical Setup → Pre-Production → Production → Polish → Release). Stage is determined by explicit override (production/stage.txt) or auto-detected from project artifacts. Epic/Feature/Task breadcrumb appears conditionally in Production+ stages via a structured STATUS block in active.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add v0.2→v0.3 upgrade guide and PR validation test suite - UPGRADING.md: add v0.2.0→v0.3.0 section documenting breaking rename of /design-systems→/map-systems, new /design-system skill, statusline.sh, gate-check stage advancement, and safe-to-overwrite file list Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
384
UPGRADING.md
Normal file
384
UPGRADING.md
Normal file
@@ -0,0 +1,384 @@
|
||||
# Upgrading Claude Code Game Studios
|
||||
|
||||
This guide covers upgrading your existing game project repo from one version
|
||||
of the template to the next.
|
||||
|
||||
**Find your current version** in your git log:
|
||||
```bash
|
||||
git log --oneline | grep -i "release\|setup"
|
||||
```
|
||||
Or check `README.md` for the version badge.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Upgrade Strategies](#upgrade-strategies)
|
||||
- [v0.2.0 → v0.3.0](#v020--v030)
|
||||
- [v0.1.0 → v0.2.0](#v010--v020)
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Strategies
|
||||
|
||||
There are three ways to pull in template updates. Choose based on how your
|
||||
repo is set up.
|
||||
|
||||
### Strategy A — Git Remote Merge (recommended)
|
||||
|
||||
Best when: you cloned the template and have your own commits on top of it.
|
||||
|
||||
```bash
|
||||
# Add the template as a remote (one-time setup)
|
||||
git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git
|
||||
|
||||
# Fetch the new version
|
||||
git fetch template main
|
||||
|
||||
# Merge into your branch
|
||||
git merge template/main --allow-unrelated-histories
|
||||
```
|
||||
|
||||
Git will flag conflicts only in files that both the template *and* you have
|
||||
changed. Resolve each one — your game content goes in, structural improvements
|
||||
come along for the ride. Then commit the merge.
|
||||
|
||||
**Tip:** The files most likely to conflict are `CLAUDE.md` and
|
||||
`.claude/docs/technical-preferences.md`, because you've filled them in with
|
||||
your engine and project settings. Keep your content; accept the structural changes.
|
||||
|
||||
---
|
||||
|
||||
### Strategy B — Cherry-pick specific commits
|
||||
|
||||
Best when: you only want one specific feature (e.g., just the new skill, not
|
||||
the full update).
|
||||
|
||||
```bash
|
||||
git remote add template https://github.com/Donchitos/Claude-Code-Game-Studios.git
|
||||
git fetch template main
|
||||
|
||||
# Cherry-pick the specific commit(s) you want
|
||||
git cherry-pick <commit-sha>
|
||||
```
|
||||
|
||||
Commit SHAs for each version are listed in the version sections below.
|
||||
|
||||
---
|
||||
|
||||
### Strategy C — Manual file copy
|
||||
|
||||
Best when: you didn't use git to set up the template (just downloaded a zip).
|
||||
|
||||
1. Download or clone the new version alongside your repo.
|
||||
2. Copy the files listed under **"Safe to overwrite"** directly.
|
||||
3. For files under **"Merge carefully"**, open both versions side-by-side
|
||||
and manually merge the structural changes while keeping your content.
|
||||
|
||||
---
|
||||
|
||||
## v0.2.0 → v0.3.0
|
||||
|
||||
**Released:** 2026-03-09
|
||||
**Commit range:** `e289ce9..HEAD`
|
||||
**Key themes:** `/design-system` GDD authoring, `/map-systems` rename, custom status line
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
#### `/design-systems` renamed to `/map-systems`
|
||||
|
||||
The `/design-systems` skill was renamed to `/map-systems` for clarity
|
||||
(decomposing = *mapping*, not *designing*).
|
||||
|
||||
**Action required:** Update any documentation, notes, or scripts that invoke
|
||||
`/design-systems`. The new invocation is `/map-systems`.
|
||||
|
||||
### What Changed
|
||||
|
||||
| Category | Changes |
|
||||
|----------|---------|
|
||||
| **New skills** | `/design-system` (guided GDD authoring, section-by-section) |
|
||||
| **Renamed skills** | `/design-systems` → `/map-systems` (breaking rename) |
|
||||
| **New files** | `.claude/statusline.sh`, `.claude/settings.json` statusline config |
|
||||
| **Skill updates** | `/gate-check` — writes `production/stage.txt` on PASS, new phase definitions |
|
||||
| **Skill updates** | `brainstorm`, `start`, `design-review`, `project-stage-detect`, `setup-engine` — cross-reference fixes |
|
||||
| **Bug fixes** | `log-agent.sh`, `validate-commit.sh` — hook execution fixed |
|
||||
| **Docs** | `UPGRADING.md` added, `README.md` updated, `WORKFLOW-GUIDE.md` updated |
|
||||
|
||||
---
|
||||
|
||||
### Files: Safe to Overwrite
|
||||
|
||||
**New files to add:**
|
||||
```
|
||||
.claude/skills/design-system/SKILL.md
|
||||
.claude/statusline.sh
|
||||
```
|
||||
|
||||
**Existing files to overwrite (no user content):**
|
||||
```
|
||||
.claude/skills/map-systems/SKILL.md ← was design-systems/SKILL.md
|
||||
.claude/skills/gate-check/SKILL.md
|
||||
.claude/skills/brainstorm/SKILL.md
|
||||
.claude/skills/start/SKILL.md
|
||||
.claude/skills/design-review/SKILL.md
|
||||
.claude/skills/project-stage-detect/SKILL.md
|
||||
.claude/skills/setup-engine/SKILL.md
|
||||
.claude/hooks/log-agent.sh
|
||||
.claude/hooks/validate-commit.sh
|
||||
README.md
|
||||
docs/WORKFLOW-GUIDE.md
|
||||
UPGRADING.md
|
||||
```
|
||||
|
||||
**Delete (replaced by rename):**
|
||||
```
|
||||
.claude/skills/design-systems/ ← entire directory; replaced by map-systems/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Files: Merge Carefully
|
||||
|
||||
#### `.claude/settings.json`
|
||||
|
||||
The new version adds a `statusLine` configuration block pointing to
|
||||
`.claude/statusline.sh`. If you haven't customized `settings.json`, overwriting
|
||||
is safe. Otherwise, add this block manually:
|
||||
|
||||
```json
|
||||
"statusLine": {
|
||||
"script": ".claude/statusline.sh"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### New Features
|
||||
|
||||
#### Custom Status Line
|
||||
|
||||
`.claude/statusline.sh` displays a 7-stage production pipeline breadcrumb in
|
||||
the terminal status line:
|
||||
|
||||
```
|
||||
ctx: 42% | claude-sonnet-4-6 | Systems Design
|
||||
```
|
||||
|
||||
In Production/Polish/Release stages, it also shows the active Epic/Feature/Task
|
||||
from `production/session-state/active.md` if a `<!-- STATUS -->` block is present:
|
||||
|
||||
```
|
||||
ctx: 42% | claude-sonnet-4-6 | Production | Combat System > Melee Combat > Hitboxes
|
||||
```
|
||||
|
||||
The current stage is auto-detected from project artifacts, or can be pinned by
|
||||
writing a stage name to `production/stage.txt`.
|
||||
|
||||
#### `/gate-check` Stage Advancement
|
||||
|
||||
When a gate PASS verdict is confirmed, `/gate-check` now writes the new stage
|
||||
name to `production/stage.txt`. This immediately updates the status line for all
|
||||
future sessions without requiring manual file edits.
|
||||
|
||||
---
|
||||
|
||||
### After Upgrading
|
||||
|
||||
1. **Delete the old skill directory:**
|
||||
```bash
|
||||
rm -rf .claude/skills/design-systems/
|
||||
```
|
||||
|
||||
2. **Test the status line** by starting a Claude Code session — you should see
|
||||
the stage breadcrumb in the terminal footer.
|
||||
|
||||
3. **Verify hook execution** still works:
|
||||
```bash
|
||||
bash .claude/hooks/log-agent.sh '{}' '{}'
|
||||
bash .claude/hooks/validate-commit.sh '{}' '{}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## v0.1.0 → v0.2.0
|
||||
|
||||
**Released:** 2026-02-21
|
||||
**Commit range:** `ad540fe..e289ce9`
|
||||
**Key themes:** Context Resilience, AskUserQuestion integration, `/map-systems` skill
|
||||
|
||||
### What Changed
|
||||
|
||||
| Category | Changes |
|
||||
|----------|---------|
|
||||
| **New skills** | `/start` (onboarding), `/map-systems` (systems decomposition), `/design-system` (guided GDD authoring) |
|
||||
| **New hooks** | `session-start.sh` (recovery), `detect-gaps.sh` (gap detection) |
|
||||
| **New templates** | `systems-index.md`, 3 collaborative-protocol templates |
|
||||
| **Context management** | Major rewrite — file-backed state strategy added |
|
||||
| **Agent updates** | 14 design/creative agents — AskUserQuestion integration |
|
||||
| **Skill updates** | All 7 `team-*` skills + `brainstorm` — AskUserQuestion at phase transitions |
|
||||
| **CLAUDE.md** | Slimmed from ~159 to ~60 lines; 5 doc imports instead of 10 |
|
||||
| **Hook updates** | All 8 hooks — Windows compatibility fixes, new features |
|
||||
| **Docs removed** | `docs/IMPROVEMENTS-PROPOSAL.md`, `docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md` |
|
||||
|
||||
---
|
||||
|
||||
### Files: Safe to Overwrite
|
||||
|
||||
These are pure infrastructure — you have not customized them. Copy the new
|
||||
versions directly with no risk to your project content.
|
||||
|
||||
**New files to add:**
|
||||
```
|
||||
.claude/skills/start/SKILL.md
|
||||
.claude/skills/map-systems/SKILL.md
|
||||
.claude/skills/design-system/SKILL.md
|
||||
.claude/docs/templates/systems-index.md
|
||||
.claude/docs/templates/collaborative-protocols/design-agent-protocol.md
|
||||
.claude/docs/templates/collaborative-protocols/implementation-agent-protocol.md
|
||||
.claude/docs/templates/collaborative-protocols/leadership-agent-protocol.md
|
||||
.claude/hooks/detect-gaps.sh
|
||||
.claude/hooks/session-start.sh
|
||||
production/session-state/.gitkeep
|
||||
docs/examples/README.md
|
||||
.github/ISSUE_TEMPLATE/bug_report.md
|
||||
.github/ISSUE_TEMPLATE/feature_request.md
|
||||
.github/PULL_REQUEST_TEMPLATE.md
|
||||
```
|
||||
|
||||
**Existing files to overwrite (no user content):**
|
||||
```
|
||||
.claude/skills/brainstorm/SKILL.md
|
||||
.claude/skills/design-review/SKILL.md
|
||||
.claude/skills/gate-check/SKILL.md
|
||||
.claude/skills/project-stage-detect/SKILL.md
|
||||
.claude/skills/setup-engine/SKILL.md
|
||||
.claude/skills/team-audio/SKILL.md
|
||||
.claude/skills/team-combat/SKILL.md
|
||||
.claude/skills/team-level/SKILL.md
|
||||
.claude/skills/team-narrative/SKILL.md
|
||||
.claude/skills/team-polish/SKILL.md
|
||||
.claude/skills/team-release/SKILL.md
|
||||
.claude/skills/team-ui/SKILL.md
|
||||
.claude/hooks/log-agent.sh
|
||||
.claude/hooks/pre-compact.sh
|
||||
.claude/hooks/session-stop.sh
|
||||
.claude/hooks/validate-assets.sh
|
||||
.claude/hooks/validate-commit.sh
|
||||
.claude/hooks/validate-push.sh
|
||||
.claude/rules/design-docs.md
|
||||
.claude/docs/hooks-reference.md
|
||||
.claude/docs/skills-reference.md
|
||||
.claude/docs/quick-start.md
|
||||
.claude/docs/directory-structure.md
|
||||
.claude/docs/context-management.md
|
||||
docs/COLLABORATIVE-DESIGN-PRINCIPLE.md
|
||||
docs/WORKFLOW-GUIDE.md
|
||||
README.md
|
||||
```
|
||||
|
||||
**Agent files to overwrite** (if you haven't written custom prompts into them):
|
||||
```
|
||||
.claude/agents/art-director.md
|
||||
.claude/agents/audio-director.md
|
||||
.claude/agents/creative-director.md
|
||||
.claude/agents/economy-designer.md
|
||||
.claude/agents/game-designer.md
|
||||
.claude/agents/level-designer.md
|
||||
.claude/agents/live-ops-designer.md
|
||||
.claude/agents/narrative-director.md
|
||||
.claude/agents/producer.md
|
||||
.claude/agents/systems-designer.md
|
||||
.claude/agents/technical-director.md
|
||||
.claude/agents/ux-designer.md
|
||||
.claude/agents/world-builder.md
|
||||
.claude/agents/writer.md
|
||||
```
|
||||
|
||||
If you *have* customized agent prompts, see "Merge carefully" below.
|
||||
|
||||
---
|
||||
|
||||
### Files: Merge Carefully
|
||||
|
||||
These files contain both template structure and your project-specific content.
|
||||
Do **not** overwrite them — merge the changes manually.
|
||||
|
||||
#### `CLAUDE.md`
|
||||
|
||||
The template version was slimmed from ~159 lines to ~60 lines. The key
|
||||
structural change: 5 doc imports were removed because they're auto-loaded
|
||||
by Claude Code anyway (agent-roster, skills-reference, hooks-reference,
|
||||
rules-reference, review-workflow).
|
||||
|
||||
**What to keep from your version:**
|
||||
- The `## Technology Stack` section (your engine/language choices)
|
||||
- Any project-specific additions you made
|
||||
|
||||
**What to adopt from the new version:**
|
||||
- Slimmer imports list (drop the 5 redundant `@` imports if present)
|
||||
- Updated collaboration protocol wording
|
||||
|
||||
#### `.claude/docs/technical-preferences.md`
|
||||
|
||||
If you ran `/setup-engine`, this file has your engine config, naming
|
||||
conventions, and performance budgets. Keep all of it. The template version
|
||||
is just the empty placeholder.
|
||||
|
||||
#### `.claude/docs/templates/game-concept.md`
|
||||
|
||||
Minor structural update — a `## Next Steps` section was added pointing to
|
||||
`/map-systems`. Add that section to your copy if you want the updated
|
||||
guidance, but it's not required.
|
||||
|
||||
#### `.claude/settings.json`
|
||||
|
||||
Check whether the new version adds any permission rules you want. The change
|
||||
was minor (schema update). If you haven't customized your `settings.json`,
|
||||
overwriting is safe.
|
||||
|
||||
#### Customized agent files
|
||||
|
||||
If you've added project-specific knowledge or custom behavior to any agent
|
||||
`.md` file, do a diff and manually add the new AskUserQuestion integration
|
||||
sections rather than overwriting. The change in each agent is a standardized
|
||||
collaborative protocol block at the end of the system prompt.
|
||||
|
||||
---
|
||||
|
||||
### Files: Delete
|
||||
|
||||
These files were removed in v0.2.0. If present in your repo, you can safely
|
||||
delete them — they're replaced by better-organized alternatives.
|
||||
|
||||
```
|
||||
docs/IMPROVEMENTS-PROPOSAL.md → superseded by WORKFLOW-GUIDE.md
|
||||
docs/MULTI-STAGE-DOCUMENT-WORKFLOW.md → content merged into context-management.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### After Upgrading
|
||||
|
||||
1. **Run `/project-stage-detect`** to verify the system reads your project
|
||||
correctly with the new detection logic.
|
||||
|
||||
2. **Run `/start`** once if you haven't used it — it now correctly identifies
|
||||
your stage and skips onboarding steps you've already done.
|
||||
|
||||
3. **Check `production/session-state/`** exists and is gitignored:
|
||||
```bash
|
||||
ls production/session-state/
|
||||
cat .gitignore | grep session-state
|
||||
```
|
||||
|
||||
4. **Test hook execution** — if you're on Windows, verify the new hooks run
|
||||
without errors in Git Bash:
|
||||
```bash
|
||||
bash .claude/hooks/detect-gaps.sh '{}' '{}'
|
||||
bash .claude/hooks/session-start.sh '{}' '{}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Each future version will have its own section in this file.*
|
||||
Reference in New Issue
Block a user