magic-spec 1.0.0

package/.agent/workflows/magic/plan.md

@@ -0,0 +1,12 @@
+---
+description: Workflow for creating and managing the implementation plan.
+---
+
+# Plan Workflow
+
+**Triggers:** *"Create plan"*, *"Generate plan"*, *"Update plan"*, *"Reprioritize"*
+**Scope:** Prioritization, phasing, dependency analysis, and implementation order.
+Specification authoring is handled by `specification.md`.
+
+> **Full implementation:** `.magic/plan.md`
+> Read that file before proceeding. Do not execute any steps until it is read.

package/.agent/workflows/magic/retrospective.md

@@ -0,0 +1,12 @@
+---
+description: Workflow for analyzing SDD usage and generating improvement recommendations.
+---
+
+# Retrospective Workflow
+
+**Triggers:** *"Run retrospective"*, *"Analyze SDD"*, *"SDD health check"*
+**Scope:** Collect statistics from `.design/` artifacts, generate observations and actionable recommendations.
+Does not modify specs, plans, tasks, or RULES.md — only writes to `.design/RETROSPECTIVE.md`.
+
+> **Full implementation:** `.magic/retrospective.md`
+> Read that file before proceeding. Do not execute any steps until it is read.

package/.agent/workflows/magic/rule.md

@@ -0,0 +1,12 @@
+---
+description: Workflow for manually adding or amending project conventions in RULES.md.
+---
+
+# Rule Workflow
+
+**Triggers:** *"Add rule"*, *"Add convention"*, *"Amend rule"*, *"Remove rule"*
+**Scope:** Direct management of RULES.md §7 Project Conventions.
+Automatic rule capture during spec work is handled by `specification.md`.
+
+> **Full implementation:** `.magic/rule.md`
+> Read that file before proceeding. Do not execute any steps until it is read.

package/.agent/workflows/magic/specification.md

@@ -0,0 +1,12 @@
+---
+description: Workflow for creating and managing project specifications.
+---
+
+# Specification Workflow
+
+**Triggers:** *"Create spec"*, *"Update spec"*, *"Audit specs"*, *"Review registry"*
+**Scope:** Specification authoring — what exists and how it is structured.
+Planning and execution are handled by `plan.md` and `task.md`.
+
+> **Full implementation:** `.magic/specification.md`
+> Read that file before proceeding. Do not execute any steps until it is read.

package/.agent/workflows/magic/task.md

@@ -0,0 +1,12 @@
+---
+description: Workflow for generating and executing implementation tasks.
+---
+
+# Task Workflow
+
+**Triggers:** *"Generate tasks"*, *"Create tasks"*, *"Start tasks"*, *"Next task"*, *"Continue"*, *"Update tasks"*, *"Sync tasks"*, *"Start parallel execution"*, *"Launch agents"*
+**Scope:** Task generation, execution tracking, parallelism, and agent coordination.
+Planning is handled by `plan.md`.
+
+> **Full implementation:** `.magic/task.md`
+> Read that file before proceeding. Do not execute any steps until it is read.

package/.magic/init.md

@@ -0,0 +1,63 @@
+---
+description: Automatic pre-flight check for .design/ directory initialization.
+---
+
+# Init — Automatic Pre-Flight Check
+
+Verifies that `.design/` exists and contains all required system files. If anything is missing — creates it automatically.
+
+> **This is NOT a user-facing workflow.** It is called automatically by every other workflow on first invocation. No manual command needed.
+
+## Agent Guidelines
+
+1. **Silent by Default**: When called automatically by another workflow, do not interrupt the user. Report init results briefly and continue with the original workflow.
+2. **Safe to Re-Run**: Skips files that already exist. Never overwrites existing `.design/` content.
+3. **First Run Only**: After successful initialization, suggest running the Spec Workflow to create the first specification.
+
+## When It Runs
+
+This check is embedded as **Step 0** in every workflow (`specification.md`, `plan.md`, `task.md`, `rule.md`, `retrospective.md`). The agent executes it before any workflow-specific logic.
+
+```mermaid
+graph TD
+    A["Any workflow triggered"] --> B{".design/ exists?"}
+    B -->|Yes| C{INDEX.md + RULES.md exist?}
+    B -->|No| D["Run init scripts"]
+    C -->|Yes| E["Continue with workflow"]
+    C -->|No| D
+    D --> F["Report: SDD initialized"]
+    F --> E
+```
+
+## Steps
+
+1. **Check `.design/`**: Verify directory exists.
+2. **Check system files**: Verify `INDEX.md` and `RULES.md` exist inside `.design/`.
+3. **If anything missing**: Detect OS and run the appropriate script:
+
+| OS | Script | Run with |
+| :--- | :--- | :--- |
+| macOS / Linux | `.magic/scripts/init.sh` | `bash .magic/scripts/init.sh` |
+| Windows | `.magic/scripts/init.ps1` | `pwsh .magic/scripts/init.ps1` |
+
+1. **Report result** (brief, inline with the calling workflow):
+
+    ```
+    SDD initialized — {YYYY-MM-DD}
+    Created: .design/INDEX.md, .design/RULES.md, .design/specifications/, .design/tasks/
+    Continuing with {workflow name}...
+    ```
+
+2. **If already initialized**: Skip silently. No output needed.
+
+## Directory Structure Created
+
+```plaintext
+.design/
+├── INDEX.md         # Spec registry
+├── RULES.md         # Project constitution
+├── specifications/  # Spec files go here
+└── tasks/           # Task files go here
+```
+
+`PLAN.md`, `TASKS.md`, and `RETROSPECTIVE.md` are created by their respective workflows — not by init.

package/.magic/plan.md

@@ -0,0 +1,289 @@
+---
+description: Workflow for creating and managing the implementation plan from existing specifications.
+---
+
+# Plan Workflow
+
+This workflow reads finalized specifications and produces a structured implementation plan (`.design/PLAN.md`).
+It operates **after** the Spec Workflow — specifications are its input, not its concern.
+
+> **Scope**: Prioritization, phasing, dependency analysis, and implementation order.
+> Specification authoring is handled by the **Spec Workflow** (`specification.md`).
+
+## Agent Guidelines
+
+**CRITICAL INSTRUCTIONS FOR AI:**
+
+1. **Specs First**: Never generate a plan without reading all spec files listed in `INDEX.md`. The plan reflects specs — it does not invent content.
+2. **Read Before Write**: Always read `.design/INDEX.md`, `.design/RULES.md`, and all spec files in `.design/specifications/` before producing any plan output.
+3. **Auto-Init**: If `.design/` or its system files are missing, automatically trigger the Init pre-flight check (`.magic/init.md`) before proceeding.
+4. **Confirm Before Commit**: Always show the proposed phase structure and dependency analysis to the user before writing `PLAN.md`.
+5. **No Duplication**: PLAN.md summarizes specs — it does not copy their content. Use references, not reproduction.
+6. **Dependency Integrity**: Never assign a spec to an earlier phase than its declared dependencies.
+7. **Checklist Before Done**: Every task must end with the *Task Completion Checklist*. A task is not complete until the checklist is presented.
+
+## Directory Structure
+
+```plaintext
+.design/
+├── INDEX.md # Input: registry of all specs
+├── RULES.md # Input: project conventions
+├── PLAN.md # Output: implementation plan (managed by Plan Workflow)
+├── specifications/ # Input: spec files (managed by Spec Workflow)
+│   └── *.md
+└── tasks/ # Output: task files (managed by Task Workflow)
+    ├── TASKS.md
+    └── phase-{n}.md
+```
+
+## Workflow Steps
+
+### Creating a New Plan
+
+Use when `.design/PLAN.md` does not exist or needs to be built from scratch.
+
+**Trigger phrase**: *"Create plan"* or *"Generate plan"*
+
+```mermaid
+graph TD
+    A[Trigger: Create Plan] --> B[Read INDEX.md + RULES.md]
+    B --> C[Read all spec files]
+    C --> D[Extract dependency graph]
+    D --> E[Identify critical path]
+    E --> F[Propose phase structure to user]
+    F -->|Approved| G[Write PLAN.md]
+    F -->|Adjusted| F
+    G --> H[Task Completion Checklist]
+```
+
+1. **Read INDEX.md**: Get the full list of existing spec files and their statuses. Path: `.design/INDEX.md`.
+2. **Read RULES.md**: Check for any project conventions that affect planning. Path: `.design/RULES.md`.
+3. **Read all spec files**: For each spec in `.design/specifications/`, extract:
+    - `Related Specifications` — direct dependencies
+    - `Status` — only `Stable` specs are ready for implementation; `Draft`/`RFC` specs are flagged
+    - `Implementation Notes` — if present, surface them in the plan
+4. **Build dependency graph**: Map which specs depend on which. Identify:
+    - **Roots** — specs with no dependencies (can start immediately)
+    - **Leaves** — specs nothing else depends on (can be deferred)
+    - **Critical path** — the longest dependency chain
+5. **Propose phase structure**: Show the user a draft before writing anything:
+
+    ```
+    Proposed Plan — {YYYY-MM-DD}
+
+    Dependency Graph (summary):
+      architecture.md → api.md, data-management.md, ui-components.md
+      data-management.md → settings-schema.md
+      ui-components.md → main-menu.md, settings-ui.md
+
+    Critical Path:
+      architecture.md → data-management.md → settings-schema.md
+
+    Proposed Phases:
+
+    Phase 1 — Foundation (suggested: start immediately)
+      - architecture.md [Draft] ← root, no dependencies
+      - api.md [Stable] ← depends on architecture.md
+      - settings-schema.md [Stable] ← depends on data-management.md
+
+    Phase 2 — Services & Data
+      - data-management.md [Draft] ← depends on architecture.md
+      - input-system.md [Draft] ← depends on architecture.md
+
+    Phase 3 — UI & Experience
+      - ui-components.md [Draft] ← depends on architecture.md
+      - main-menu.md [Draft] ← depends on ui-components.md, localization.md
+      - settings-ui.md [Draft] ← depends on settings-schema.md, ui-components.md
+      - localization.md [Draft] ← depends on ui-components.md, data-management.md
+
+    Phase 4 — Polish
+      - gameplay-config.md [Draft] ← depends on data-management.md
+
+    Unassigned (no spec file yet):
+      - Transition Orchestrator ← mentioned in specs but no .md file
+      - Theme Engine ← mentioned in specs but no .md file
+      - Accessibility ← mentioned in specs but no .md file
+
+    Flagged:
+      - 8 of 10 specs are in Draft status — plan will note implementation readiness per spec
+
+    Adjust phases or proceed? (yes / adjust)
+    ```
+
+6. **Write PLAN.md**: After user approval, create `.design/PLAN.md` using the *PLAN.md Template*.
+7. **Task Completion Checklist**: Present the checklist to the user.
+
+### Updating an Existing Plan
+
+Use when specs have changed, new specs were added, or the user wants to reprioritize.
+
+**Trigger phrase**: *"Update plan"* or *"Reprioritize"*
+
+```mermaid
+graph TD
+    A[Trigger: Update Plan] --> B[Read current PLAN.md]
+    B --> C[Read .design/INDEX.md — detect changes]
+    C --> D{What changed?}
+    D -->|New spec added| E[Propose phase assignment]
+    D -->|Spec status changed| F[Update status marker in place]
+    D -->|User reprioritizes| G[Show current structure, propose moves]
+    D -->|Spec deprecated| H[Move to Archived section]
+    E & F & G & H --> I[Confirm with user]
+    I -->|Approved| J[Write changes to PLAN.md]
+    J --> K[Task Completion Checklist]
+```
+
+#### New Spec Added
+
+When a spec appears in `INDEX.md` that is not yet in `PLAN.md`:
+
+```
+New spec detected: "{spec-name}.md"
+Dependencies: {list from Related Specifications}
+
+Suggested phase based on dependencies: Phase {N}
+
+Assign to:
+  1. Phase 1 — Foundation
+  2. Phase 2 — Services & Data
+  3. Phase 3 — UI & Experience
+  4. A new phase — describe it
+  5. Unassigned — add to backlog
+```
+
+#### Spec Status Changed
+
+When a spec transitions to `Stable`, update its marker in PLAN.md in place:
+
+```markdown
+- **{Spec Name}** ([{spec-name}.md](specifications/{spec-name}.md)) — `Stable ✓`
+```
+
+When a spec transitions to `Deprecated`, move its entry to the `Archived` section.
+
+#### Reprioritization
+
+When the user signals a change in order or priority:
+
+1. Show the current phase structure as a compact summary.
+2. Propose the specific moves with dependency impact noted:
+
+    ```
+    Moving settings-ui.md from Phase 3 → Phase 2.
+    ⚠️ Dependency warning: settings-ui.md depends on ui-components.md (currently Phase 3).
+    Moving it earlier would create a broken dependency chain.
+
+    Options:
+      a) Also move ui-components.md to Phase 2
+      b) Keep settings-ui.md in Phase 3
+    ```
+
+3. Wait for explicit confirmation before writing any changes.
+
+#### Phase Completion
+
+When all specs in a phase reach `Stable`:
+
+```markdown
+## Phase 1 — Foundation ✓ Completed {YYYY-MM-DD}
+```
+
+Propose activating the next phase if not already open.
+
+### Task Completion Checklist
+
+**Must be shown at the end of every plan operation — no exceptions.**
+
+```
+Plan Task Completion Checklist — {task description}
+
+Input Integrity
+  ☐ All spec files in INDEX.md were read before plan was written
+  ☐ No content copied from specs — only references used
+
+Dependency Integrity
+  ☐ No spec assigned to a phase earlier than its dependencies allow
+  ☐ Dependency graph reflects current Related Specifications in all specs
+  ☐ Unassigned items (no spec file) listed explicitly
+
+Status Accuracy
+  ☐ Each spec entry reflects its current status from INDEX.md
+  ☐ Draft/RFC specs flagged as not yet implementation-ready
+
+Structure
+  ☐ PLAN.md written to .design/ root (not inside subdirectory)
+  ☐ Critical path identified and documented
+  ☐ Archived section present for deprecated specs
+
+Confirmation
+  ☐ Phase structure confirmed by user before writing
+  ☐ Any dependency warnings surfaced and resolved
+```
+
+## Templates
+
+### PLAN.md Template
+
+```markdown
+# Implementation Plan
+
+**Version:** {X.Y.Z}
+**Generated:** {YYYY-MM-DD}
+**Based on:** .design/INDEX.md v{X.Y.Z}
+**Status:** Active
+
+## Overview
+
+Implementation plan derived from project specifications.
+Specs are the source of truth. To update: *"Update plan"*.
+
+## Dependency Graph
+
+```mermaid
+graph TD
+    architecture --> api
+    architecture --> data-management
+    architecture --> ui-components
+    data-management --> settings-schema
+    ui-components --> settings-ui
+    settings-schema --> settings-ui
+```
+
+## Critical Path
+
+`architecture.md` → `data-management.md` → `settings-schema.md` → `settings-ui.md`
+
+## Phase 1 — Foundation
+
+*Specs with no dependencies. Start here.*
+
+- **Core Architecture** ([architecture.md](specifications/architecture.md)) — `Draft`
+  - Dependencies: none (root)
+  - Notes: must be stable before Phase 2
+
+- **Public API** ([api.md](specifications/api.md)) — `Stable ✓`
+  - Dependencies: architecture.md
+
+## Phase 2 — {Phase Name}
+
+*...*
+
+- **{Spec Name}** ([{spec}.md](specifications/{spec}.md)) — `{Status}`
+  - Dependencies: {spec}.md
+  - Notes: {optional}
+
+## Unassigned (No Spec File Yet)
+
+- **{Name}** — referenced in {spec}.md
+
+## Archived
+
+<!-- Deprecated specs moved here -->
+
+## Plan History
+
+| Version | Date | Author | Description |
+| :--- | :--- | :--- | :--- |
+| 1.0.0 | YYYY-MM-DD | Agent | Initial plan |
+
+```