@playcraft/cli 0.0.40 → 0.0.42

package/project-template/templates/project-state.template.md

@@ -0,0 +1,237 @@
+# Project State
+
+## Workflow spec
+
+| Field                   | Value                                                                 |
+| ----------------------- | --------------------------------------------------------------------- |
+| **workflowSpecVersion** | `convergence-v1`                                                      |
+| **Changelog**           | [docs/team/workflow-changelog.md](../docs/team/workflow-changelog.md) |
+
+<!--
+  convergence-v1: Three convergence loops — design_check (Gate #1/#2b) → ui_pass/ui_review/ui_rework → gameplay_pass/load_check → Gate #3.
+  Visual baseline (designer-handoff-v2): Phase 1 = MC + ASR; Phase 2 Designer = audio + digit strip + VisualAtom status only.
+-->
+
+## User Intent
+
+> {{user_intent — ≤2 sentences; do NOT restate Style Direction or five-axis tables from design-brief}}
+
+## Gate #1 Options
+
+<!--
+  Gate #1 only — orchestrator reads this + design-brief. One row per option; no Style Direction prose.
+  Delete this section after Gate #1 passes.
+-->
+
+| Option | Mechanic | Dimension | Interaction | Narrative | Arc   | Risk             | Recommended |
+| ------ | -------- | --------- | ----------- | --------- | ----- | ---------------- | ----------- |
+| A      | {{…}}    | {{…}}     | {{…}}       | {{L0–L3}} | {{…}} | {{low/med/high}} | {{yes/no}}  |
+| B      | {{…}}    | {{…}}     | {{…}}       | {{…}}     | {{…}} | {{…}}            | {{yes/no}}  |
+
+## Current Stage
+
+**{{current_stage}}** — {{stage_description}}
+
+`pm` → `style_exploration` → `production` → `ui_pass` → `ui_review` ⇄ `ui_rework` → `gameplay_pass` → `done`
+
+<!-- Stage definitions: see CLAUDE.md § Stage Model -->
+
+## Gates
+
+> Only the **orchestrator** runs `AskUserQuestion` toward the user. Sub-agents set `pending` and STOP.
+
+| Gate               | Status             | Notes                                                                        |
+| ------------------ | ------------------ | ---------------------------------------------------------------------------- |
+| #1 Direction       | {{passed/pending}} | Orchestrator confirms after PM four docs + Reviewer design_check + STOP      |
+| #2a MC selection   | {{passed/pending}} | Orchestrator picks A/B/C → sets `selectedMcOption` below                     |
+| #2b MC + ASR final | {{passed/pending}} | Reviewer design_check → Orchestrator confirms MC + ASR → `stage: production` |
+| #3 Dev acceptance  | {{passed/pending}} | Reviewer load_check pass → user opens devUrl (orchestrator link only)        |
+
+## Agent handoff
+
+> Sub-agents and orchestrator **must** read/write this block before STOP or invoke. See `docs/team/collaboration.md` § Agent Handoff.
+
+```yaml
+subagent: none
+subagent_stop: false
+waiting_for: orchestrator
+gate_pending: null
+next_orchestrator_action: null
+last_completed_by: null
+rework_round: 0
+block_reason: null
+```
+
+<!--
+Examples (copy structure on STOP — do not leave nulls):
+
+PM Gate #1 STOP:
+  subagent: pm
+  subagent_stop: true
+  waiting_for: user_gate
+  gate_pending: "1"
+  next_orchestrator_action: "Run Gate #1 AskUserQuestion"
+  last_completed_by: pm
+  rework_round: 0
+
+Designer Gate #2a STOP:
+  subagent: designer
+  subagent_stop: true
+  waiting_for: user_gate
+  gate_pending: "2a"
+  next_orchestrator_action: "Run Gate #2a"
+  last_completed_by: designer
+
+Developer ui_pass STOP:
+  subagent: developer
+  subagent_stop: true
+  waiting_for: orchestrator
+  gate_pending: null
+  next_orchestrator_action: "Invoke @reviewer ui_diff"
+  last_completed_by: developer
+
+Reviewer ui_diff pass STOP:
+  subagent: reviewer
+  subagent_stop: true
+  waiting_for: orchestrator
+  gate_pending: null
+  next_orchestrator_action: "Set stage=gameplay_pass, invoke @developer"
+  last_completed_by: reviewer
+-->
+
+## Gate resume fields
+
+| Field            | Value                                              |
+| ---------------- | -------------------------------------------------- |
+| selectedMcOption | {{A / B / C — set by orchestrator after Gate #2a}} |
+| uiReworkRound    | {{0–5 — incremented by Reviewer on ui_diff fail}}  |
+
+## Dev Preview
+
+| Field          | Value                                                                        |
+| -------------- | ---------------------------------------------------------------------------- |
+| devCommand     | npm run dev                                                                  |
+| devScript      | {{from package.json scripts.dev}}                                            |
+| devUrl         | {{http://... — Developer records when ready; orchestrator uses for Gate #3}} |
+| devStatus      | pending / ui_ready / ready / blocked_upstream / failed                       |
+| devBlockers    | {{list: assetPath, issue, routeTo (TA/Designer/PM), status}}                 |
+| devStartedBy   | developer / reviewer / orchestrator                                          |
+| devLastChecked | {{ISO timestamp}}                                                            |
+| loadCheck      | pending / passed / failed                                                    |
+| loadCheckNotes | {{console errors, white screen, load time}}                                  |
+
+## UI Review
+
+| Field            | Value                                      |
+| ---------------- | ------------------------------------------ |
+| uiReviewStatus   | pending / passed / failed                  |
+| uiReworkRound    | {{0–5}}                                    |
+| uiDiffReportPath | logs/review-report.md                      |
+| uiDiffNotes      | {{summary of MC vs screenshot comparison}} |
+
+<!--
+devStatus:
+  pending           — ui_pass or gameplay_pass not finished
+  ui_ready          — UI shell complete (scene switch, layout, simple states); safe to invoke Reviewer ui_diff
+  ready             — gameplay_pass complete; safe to invoke Reviewer load_check
+  blocked_upstream  — Developer waiting on TA/Designer rework (orchestrator re-invokes)
+  failed            — dev server could not start; document error
+
+Developer MUST NOT set ui_ready/ready while devBlockers has open items.
+-->
+
+## File Index
+
+### PM Output
+
+| File                                    | Description                                   | Status     |
+| --------------------------------------- | --------------------------------------------- | ---------- |
+| [design-brief.md](docs/design-brief.md) | Style Direction + experience flow (mechanics) | {{status}} |
+| [layout-spec.md](docs/layout-spec.md)   | Paths, palette hex, assetMapping, atlas       | {{status}} |
+| [atom-plan.json](docs/atom-plan.json)   | skillsMatch + atoms[] (machine contract)      | {{status}} |
+| [atom-plan.md](docs/atom-plan.md)       | Acceptance criteria + Context enrichments     | {{status}} |
+
+### Designer Output
+
+| File/Directory                                    | Description                               | Status     |
+| ------------------------------------------------- | ----------------------------------------- | ---------- |
+| [style-exploration.md](docs/style-exploration.md) | Style options + concept mockups (Phase 1) | {{status}} |
+| [designer-log.md](logs/designer-log.md)           | Work log + delivery manifest              | {{status}} |
+| `assets/images/`                                  | Key creative samples (Designer)           | {{status}} |
+| `assets/audio/`                                   | BGM + SFX (original generation)           | {{status}} |
+| `assets/bundles/`                                 | Designer atom bundles                     | {{status}} |
+
+### Technical Artist Output
+
+| File/Directory              | Description                                                      | Status     |
+| --------------------------- | ---------------------------------------------------------------- | ---------- |
+| [ta-log.md](logs/ta-log.md) | Work log + compliance report                                     | {{status}} |
+| `assets/images/`            | Completed asset set (TA completions + sprite sheets + processed) | {{status}} |
+| `assets/audio/`             | Post-processed audio (compress/trim/loop)                        | {{status}} |
+| `assets/bundles/`           | TA atom bundles                                                  | {{status}} |
+
+### Developer Output
+
+| File/Directory                            | Description                                            | Status     |
+| ----------------------------------------- | ------------------------------------------------------ | ---------- |
+| [developer-log.md](logs/developer-log.md) | Work log + Dev self-check + devUrl + upstream blockers | {{status}} |
+| `game/gameplay/`                          | PGS + state machine                                    | {{status}} |
+| `game/config/`                            | Level configuration                                    | {{status}} |
+| `game/scenes/`                            | Scene definitions                                      | {{status}} |
+| `game/index.html`                         | Entry point                                            | {{status}} |
+
+### Reviewer Output
+
+| File                                                      | Description                                 | Status     |
+| --------------------------------------------------------- | ------------------------------------------- | ---------- |
+| [review-report.md](logs/review-report.md)                 | design_check / ui_diff / load_check reports | {{status}} |
+| [intent-clarifications.md](docs/intent-clarifications.md) | Agent-to-agent Q&A (ICP)                    | {{status}} |
+
+## Production Pipeline (Serial)
+
+<!-- Only relevant when stage = production or transitioning to ui_pass -->
+
+| Wave | Agent            | Status     | Notes                                      |
+| ---- | ---------------- | ---------- | ------------------------------------------ |
+| 1    | Designer         | {{status}} | Ph.2: audio + digit + VisualAtom status    |
+| 2    | Technical Artist | {{status}} | Spec Quick-Check → bulk → Compliance green |
+
+<!-- Wave 3 Developer runs in stage = ui_pass — not tracked here -->
+
+## Intent Clarification Tracking
+
+<!-- Monitor ICP activity during production -->
+
+| Metric                                     | Value      |
+| ------------------------------------------ | ---------- |
+| Open questions in intent-clarifications.md | {{count}}  |
+| Unresolved for > 10 min                    | {{count}}  |
+| Designer questions received                | {{count}}  |
+| TA questions received                      | {{count}}  |
+| Developer questions received               | {{count}}  |
+| PM intervention needed                     | {{yes/no}} |
+
+<!--
+PM monitors this table:
+  - Open questions > 3 → PM must intervene
+  - Single Agent receives > 3 questions → record "intent transmission fault" in DAG Revisions
+-->
+
+<!--
+Orchestrator serial rules:
+  - Gate #2b passed → invoke @designer only (Wave 1)
+  - Wave 1 = done → invoke @technical-artist (Wave 2)
+  - Wave 2 = done → stage: ui_pass → invoke @developer
+  - Optional: 30s spot-check ta-log Compliance + contract paths exist before @developer
+-->
+
+## Progress Checkpoint
+
+<!--
+One row per major step — decision summary only, not full contract text.
+Gate #1 example Notes: "Option B recommended; Competence + match-3" (not a copy of design-brief).
+-->
+
+| #     | Stage     | Agent     | Action            | Result      | Notes                         |
+| ----- | --------- | --------- | ----------------- | ----------- | ----------------------------- |
+| {{n}} | {{stage}} | {{agent}} | {{what_was_done}} | {{outcome}} | {{key_decisions_or_blockers}} |

package/project-template/templates/review-report.template.md

@@ -0,0 +1,91 @@
+# Review Report
+
+> Fill **one section** matching the review mode orchestrator invoked: `design_check` | `ui_diff` | `load_check`.
+
+## Review Mode
+
+**{{design_check / ui_diff / load_check}}** — {{ISO timestamp}}
+
+## Verdict
+
+**{{pass / fail}}**
+
+---
+
+## design_check (Gate #1 / #2b)
+
+### Gate
+
+**{{#1 / #2b}}**
+
+### Checklist
+
+| Item               | Pass?      | Notes       |
+| ------------------ | ---------- | ----------- |
+| {{checklist item}} | {{yes/no}} | {{details}} |
+
+### Missing / defects
+
+| #     | Issue           | routeTo       |
+| ----- | --------------- | ------------- |
+| {{n}} | {{description}} | pm / designer |
+
+### Outcome
+
+{{pass → Run Gate / fail → re-invoke agent}}
+
+---
+
+## ui_diff (MC screenshot comparison)
+
+### devUrl
+
+{{http://...}}
+
+### Scene comparisons
+
+| Scene | Screenshot            | MC reference | Severity                 | Match?     | routeTo                   | Fix suggestion |
+| ----- | --------------------- | ------------ | ------------------------ | ---------- | ------------------------- | -------------- |
+| hook  | logs/ui-diff-hook.png | {{mc path}}  | {{critical/major/minor}} | {{yes/no}} | {{developer/ta/designer}} | {{fix}}        |
+
+### Summary
+
+- **uiReworkRound**: {{0–5}}
+- **Blocking issues**: {{count critical + major}}
+- **Minor only**: {{yes/no — does not block pass}}
+
+### Action Items
+
+| #     | Severity     | routeTo   | Action           |
+| ----- | ------------ | --------- | ---------------- |
+| {{n}} | {{severity}} | {{agent}} | {{specific fix}} |
+
+---
+
+## load_check (pre-Gate #3)
+
+### devUrl
+
+{{http://...}}
+
+### Checks
+
+| Check                  | Pass?      | Notes                     |
+| ---------------------- | ---------- | ------------------------- |
+| Page loads ≤10s        | {{yes/no}} | {{load time}}             |
+| No console Error logs  | {{yes/no}} | {{error summary or none}} |
+| game/index.html exists | {{yes/no}} | —                         |
+
+### Screenshot
+
+`logs/load-check.png`
+
+### Outcome
+
+{{pass → Run Gate #3 / fail → route Developer}}
+
+---
+
+## Summary
+
+{{one paragraph overall assessment for this review mode}}

package/project-template/templates/style-exploration.template.md

@@ -0,0 +1,93 @@
+# Style Exploration
+
+> Designer Phase 1 output (`designer-handoff-v2`). Gate #2 = narrative + style lock via **Master Composite (MC)** + **ASR** after option selection.
+
+## Style Direction Summary
+
+- **Art style**: {{art_style_from_brief}}
+- **Color mood**: {{color_mood}}
+- **Element theme**: {{element_theme}}
+- **References**: {{reference_games_or_styles}}
+- **Emotional Arc**: {{emotional_arc_from_brief}}
+
+## Options
+
+### Option {{A/B/C}}: {{option_name}}
+
+**Keywords**: {{3-5 keywords}}
+**Color temperature**: {{warm/cold/neutral}}
+**Art approach**: {{1-2 sentences}}
+**Alignment with design-brief**: {{brief alignment}}
+
+#### Master Composite (Gate #2a)
+
+| File                                                         | Description                                                 |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| `assets/images/storyboard/master_composite_option_{{a}}.png` | 5×9:16 panels: concept + Hook + Onboarding + End Card + CTA |
+
+**MC prompt** (summary or path to sidecar `.json`):
+
+```
+{{master_composite_prompt_summary}}
+```
+
+#### Panels (embedded in MC — not separate files)
+
+| Panel # | Label              | Time    | Visual intent                             |
+| ------- | ------------------ | ------- | ----------------------------------------- |
+| 1       | Main Gameplay      | —       | Full UI + all element types + static text |
+| 2       | Key Hook           | 0-3s    | {{hook intent}}                           |
+| 3       | Onboarding HUD     | 3-10s   | {{tutorial intent}}                       |
+| 4       | End Card           | 25-30s  | {{end card intent}}                       |
+| 5       | CTA Always Visible | in-game | {{persistent CTA}}                        |
+
+#### Experience Flow Design
+
+**Emotional Arc Visualization**:
+
+- Hook → {{visual signals}}
+- Tutorial → {{visual signals}}
+- Gameplay Peak → {{near-win signals}}
+- End Card → {{resolution signals}}
+
+**Near-Win Visual Composition**: {{description}}
+
+**Attention Guidance per Stage**: Hook / Tutorial / Gameplay / End Card — {{paths}}
+
+**Audio-Emotion Rhythm** (for Phase 2 BGM/SFX): {{per-stage audio notes}}
+
+---
+
+<!-- Repeat per option (2–3). Gate #2a: user picks A/B/C. Gate #2b: add ASR + Motion Notes below for selected option only. -->
+
+## Selected option (after Gate #2a)
+
+- **Selected**: {{A/B/C}}
+- **MC path**: `assets/images/storyboard/master_composite_option_{{X}}.png`
+
+### ASR (Gate #2b)
+
+| File                                                    | Role                    |
+| ------------------------------------------------------- | ----------------------- |
+| `assets/images/reference/ui_state_sheet_{{X}}.png`      | UI component states     |
+| `assets/images/reference/element_state_sheet_{{X}}.png` | Gameplay element states |
+
+Detail tables: `logs/designer-log.md` § ASR Coverage Matrix.
+
+### Motion Notes (Gate #2b)
+
+| Transition          | Type                | Duration | Notes |
+| ------------------- | ------------------- | -------- | ----- |
+| Hook → Tutorial     | {{fade/zoom/swipe}} | {{~ms}}  |       |
+| Tutorial → Gameplay |                     |          |       |
+| Gameplay → End Card |                     |          |       |
+
+## Recommendation
+
+{{Which option and why — ties to PM Emotional Arc}}
+
+## User Decision
+
+- **Selected option**: {{A/B/C}}
+- **User feedback**: {{adjustments}}
+- **Confirmed MC**: `assets/images/storyboard/master_composite_option_{{X}}.png`