@codeyam/codeyam-cli 0.1.0-staging.e38f7bd → 0.1.0-staging.f777668

package/codeyam-cli/templates/commands/codeyam-diagnose.md

@@ -0,0 +1,481 @@
+# Debug Scenario or Analysis
+
+When a user asks to debug a scenario or analysis (e.g., `/codeyam-diagnose [ID]`), use this systematic process.
+
+## Goal & Rules
+
+**Goal:** Capture quality screenshots by fixing all errors, then document what was wrong.
+
+**Definition of Done** — debugging is NOT complete until one of:
+
+| Outcome                | What's Required                                                                                                                               |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **SUCCESS (DB Fix)**   | Issue fixed via database/config changes, screenshots recaptured, all files verified on disk AND visually inspected                            |
+| **SUCCESS (File Fix)** | Issue fixed via tmp folder edits, screenshots recaptured with `--capture-only`, all files verified AND visually inspected, changes documented |
+| **UNFIXABLE**          | Issue cannot be fixed locally (rare), documented in final report with full details                                                            |
+
+### KEY RULE 1: Never stop before capturing screenshots
+
+Category 4 ("engine bug") is a **diagnosis category, not a blocker**. You have full access to edit any file in `/tmp/codeyam/local-dev/{slug}/project/` — the "engine" just wrote those files as plain TypeScript/JavaScript. Every issue can be fixed locally.
+
+If you find yourself thinking "this requires an engine-level fix" or "this is blocked by a code generation bug" — **STOP**.
+
+- Fix the files in the tmp folder, then capture screenshots, THEN document the bug
+- Try at least 3 different approaches before asking the user whether to continue
+- Only stop when the user agrees or you've captured quality screenshots
+
+### KEY RULE 2: Original Repo vs Tmp Folder
+
+| Location                                                  | What's There                                                        | Use For                                               |
+| --------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
+| **Original Repo** (your working directory)                | Database (`.codeyam/db.sqlite3`), config, universal mocks, captures | **Run all `codeyam` commands here**                   |
+| **Tmp Folder** (`/tmp/codeyam/local-dev/{slug}/project/`) | Copy of project with mock injections, generated scenario files      | **Only edit files here — never run codeyam commands** |
+
+Running `codeyam recapture` from the tmp folder fails with "Not in a CodeYam project" because the database isn't there.
+
+### KEY RULE 3: Never modify client code
+
+Fix the **mock data or mock code** — never the client's components or application code. The client's code is sacred. Our job is to make the simulation environment correct. You CAN modify:
+
+- Database data (`.codeyam/db.sqlite3`) — in Original Repo
+- Universal mocks (`.codeyam/universal-mocks`) — in Original Repo
+- Generated files in tmp folder (`__codeyamMocks__/`, layouts, routes)
+
+### KEY RULE 4: `--capture-only` preserves tmp folder edits
+
+- `codeyam recapture ID` — regenerates files from database, then captures (overwrites tmp edits)
+- `codeyam recapture ID --capture-only` — captures without regenerating (preserves your edits)
+- `codeyam debug ID` — regenerates files only (also overwrites tmp edits)
+
+If you edited files in the tmp folder, you **MUST** use `--capture-only` when recapturing.
+
+---
+
+## Setup
+
+### Note Key Locations
+
+**Database:** The codeyam database relevant for this command should always be found in the repo where this command is called in the `.codeyam/db.sqlite3` file.
+
+**Logs:** Before debugging copy the original logs to a temorary location as the debugging will overwrite these logs and they are valuable for debugging issues.
+
+Original Logs Locaion: `/tmp/codeyam/local-dev/{slug}/codeyam/logs.txt`
+Temporary location: `/tmp/codeyam/local-dev/{slug}/debug/original-logs.txt`
+
+**Notice:** Both paths lead to "Recapture" and "Verify screenshots". There is no path that ends after just identifying a bug category. You must always capture quality screenshots before completing.
+
+---
+
+## MANDATORY: Session Context (Do This First!)
+
+Long debugging sessions cause context loss. To prevent forgetting critical information:
+
+### Step 1: Create Session Context File
+
+At the **very start** of debugging, create `.codeyam/debug-session.md` in the **original project directory**:
+
+```markdown
+# Debug Session Context
+
+## Key Locations
+
+- **Original Repo**: [FULL PATH]
+- **Tmp Folder**: /tmp/codeyam/local-dev/[PROJECT SLUG]/project
+- **Database**: [Original Repo]/.codeyam/db.sqlite3
+- **Logs**: /tmp/codeyam/local-dev/[PROJECT SLUG]/codeyam/log.txt
+
+## IDs
+
+- **Analysis ID**: [ID]
+- **Scenario ID**: [ID]
+- **Entity**: [NAME] at [FILE PATH]
+
+## URLs (fill in after codeyam debug)
+
+- **Scenario URL**: http://localhost:[PORT]/static/codeyam-sample
+```
+
+Re-read this file before running any `codeyam` command to avoid running commands from the wrong directory.
+
+### Copy Original Logs
+
+Copy logs before debugging overwrites them:
+
+- **From:** `/tmp/codeyam/local-dev/{slug}/codeyam/logs.txt`
+- **To:** `/tmp/codeyam/local-dev/{slug}/debug/original-logs.txt`
+
+---
+
+## Step 1: Check Database (MANDATORY FIRST STEP)
+
+**DO NOT run `codeyam debug` yet!** First check if other scenarios in the same analysis are also failing.
+
+```bash
+# Get analysis ID (if you have a scenario ID)
+sqlite3 .codeyam/db.sqlite3 "SELECT analysis_id FROM scenarios WHERE id = 'SCENARIO_ID'"
+
+# Check ALL scenarios for that analysis
+sqlite3 .codeyam/db.sqlite3 "
+SELECT s.id, s.name, json_extract(s.metadata, '$.screenshotPaths') as screenshots
+FROM scenarios s WHERE s.analysis_id = 'ANALYSIS_ID'"
+
+# Check for errors in scenario status
+sqlite3 .codeyam/db.sqlite3 "
+SELECT json_extract(status, '$.scenarios') FROM analyses WHERE id = 'ANALYSIS_ID'"
+```
+
+**If multiple scenarios failing, ASK THE USER** whether to fix just the requested one or all.
+
+### Check Existing Screenshots for Client-Side Errors
+
+Even if screenshots exist, view them with the Read tool and check for:
+
+- Red error boundaries or React error overlays
+- "Something went wrong" or similar error text
+- Blank/white screens that should have content
+
+If the screenshot shows errors, proceed to Step 2.
+
+---
+
+## Step 2: Run Debug Command
+
+```bash
+codeyam debug ANALYSIS_ID
+```
+
+Output includes: **project path**, **start command**, **URL**, **log path**. Update your session context file with these.
+
+---
+
+## Step 3: Identify Error Type
+
+Read the log file or error output to categorize:
+
+| Error Type                         | Symptoms                            | Likely Category   |
+| ---------------------------------- | ----------------------------------- | ----------------- |
+| **Syntax error in generated file** | `Unexpected token`, `Parse error`   | Category 4        |
+| **Runtime error**                  | `TypeError`, `ReferenceError`       | Category 1-3 or 4 |
+| **Missing mock**                   | `Cannot read property of undefined` | Category 1-2      |
+| **Wrong mock type**                | `X is not a function`               | Category 3-4      |
+
+---
+
+## Step 4: Diagnose Root Cause Category
+
+Determine WHERE in the pipeline the bug originated.
+
+### The 4 Error Categories
+
+| Category | What's Wrong                                     | Where to Check       | Fix                 |
+| -------- | ------------------------------------------------ | -------------------- | ------------------- |
+| **1**    | Missing attribute in `isolatedDataStructure`     | `entities.metadata`  | Re-analyze          |
+| **2**    | Attribute not merged into `mergedDataStructure`  | `analyses.metadata`  | Re-analyze          |
+| **3**    | Data structure complete, but scenario data wrong | `scenarios.metadata` | Edit mockData in DB |
+| **4**    | Data complete, but generated code wrong          | Files in `/tmp`      | Edit files directly |
+
+### Diagnostic Queries
+
+```bash
+# Category 1: Check isolatedDataStructure
+sqlite3 .codeyam/db.sqlite3 \
+  "SELECT json_extract(metadata, '$.isolatedDataStructure') FROM entities WHERE sha = 'ENTITY_SHA'" \
+  | python3 -m json.tool
+
+# Category 2: Check mergedDataStructure
+sqlite3 .codeyam/db.sqlite3 \
+  "SELECT json_extract(metadata, '$.mergedDataStructure') FROM analyses WHERE id = 'ANALYSIS_ID'" \
+  | python3 -m json.tool
+
+# Category 2 (also): scenariosDataStructure
+sqlite3 .codeyam/db.sqlite3 \
+  "SELECT json_extract(metadata, '$.scenariosDataStructure') FROM analyses WHERE id = 'ANALYSIS_ID'" \
+  | python3 -m json.tool
+
+# Category 3: Check scenario mockData
+sqlite3 .codeyam/db.sqlite3 \
+  "SELECT json_extract(metadata, '$.data.mockData') FROM scenarios WHERE id = 'SCENARIO_ID'" \
+  | python3 -m json.tool
+```
+
+### Diagnosis Flow
+
+Work through these checks in order — stop at the first failure:
+
+| Step | Check                                                                           | If wrong → |
+| ---- | ------------------------------------------------------------------------------- | ---------- |
+| 1    | **Start with the error** — what attribute/value is missing or wrong at runtime? | —          |
+| 2    | Is the attribute in `isolatedDataStructure`?                                    | Category 1 |
+| 3    | Is the attribute in `mergedDataStructure`?                                      | Category 2 |
+| 4    | Is `scenariosDataStructure` correct?                                            | Category 2 |
+| 5    | Does scenario `mockData` have correct values?                                   | Category 3 |
+| 6    | Is the generated mock code syntactically/semantically correct?                  | Category 4 |
+| 7    | Are imports correct? Environment variable entities mocked out?                  | Category 4 |
+
+If all database data looks correct but the generated code has syntax errors, wrong structure, or doesn't match the data → **Category 4**.
+
+---
+
+## Step 5: Fix the Issue
+
+Jump to the subsection matching your category:
+
+- **Categories 1-2** → Re-analyze
+- **Category 3** → Edit mockData in database
+- **Category 4** → Edit generated files in tmp folder
+
+### Categories 1-2 (Data Structure Issues)
+
+Re-run analysis:
+
+```bash
+codeyam analyze --entity EntityName path/to/file.tsx
+```
+
+### Category 3 (Scenario Data Issues)
+
+Fix mockData directly in the database:
+
+```bash
+# Export metadata
+sqlite3 .codeyam/db.sqlite3 "SELECT metadata FROM scenarios WHERE id = 'SCENARIO_ID'" > /tmp/metadata.json
+
+# Edit with Python
+python3 << 'EOF'
+import json
+with open('/tmp/metadata.json') as f:
+    data = json.loads(f.read())
+
+# Fix the mockData
+data['data']['mockData']['keyName'] = {"fixed": "value"}
+
+with open('/tmp/metadata_fixed.json', 'w') as f:
+    f.write(json.dumps(data))
+EOF
+
+# Update database
+python3 << 'EOF'
+import sqlite3, json
+with open('/tmp/metadata_fixed.json') as f:
+    metadata = f.read()
+conn = sqlite3.connect('.codeyam/db.sqlite3')
+conn.execute("UPDATE scenarios SET metadata = ? WHERE id = 'SCENARIO_ID'", (metadata,))
+conn.commit()
+conn.close()
+EOF
+```
+
+### Category 4 (Code Generation Issues) — Edit Files Directly
+
+Fix generated files in `/tmp/codeyam/local-dev/{slug}/project/`. Common locations:
+
+- **Generated mocks**: `__codeyamMocks__/MockData_*.tsx` or `__codeyamMocks__/MockCode_*.tsx`
+- **Scenario layouts**: `app/static/{projectSlug}/{analysisId}/{entitySlug}/{scenarioSlug}/`
+- **Route files**: `app/routes/` or `pages/` depending on framework
+
+Common fixes:
+
+- Syntax errors (missing brackets, commas, quotes)
+- Wrong import paths
+- Missing named or default exports
+- TypeScript type issues
+- Wrong mock data shape
+
+**Only fix GENERATED files** (mocks, layouts, routes) — never the client's application code. If a client component crashes, the fix is in the mock data or mock code.
+
+### Universal Mocks (for infrastructure dependencies)
+
+Use universal mocks to mock functions not in the dependency tree (middleware, startup functions needing env vars).
+
+**Mock path decision tree:**
+
+```
+Error source?
+├── node_modules package → .codeyam/universal-mocks/node_modules/{package}.ts
+│   Example: .codeyam/universal-mocks/node_modules/@prisma/client.ts
+└── Project file → .codeyam/universal-mocks/{same-path-as-original}
+    Example: .codeyam/universal-mocks/lib/db.ts
+```
+
+**Mock writing rules:**
+
+1. Read the original file first, note all export names exactly
+2. Export names MUST match exactly (case-sensitive)
+3. ALL code MUST be inside exports (no helper variables outside)
+4. Keep it minimal — empty methods are fine
+5. Validate: `codeyam validate-mock .codeyam/universal-mocks/{path}`
+
+### Track All Changes (MANDATORY)
+
+For every change, record for the final report:
+
+**Database changes:**
+
+| Table       | Record ID | Field Path                   | Before    | After       |
+| ----------- | --------- | ---------------------------- | --------- | ----------- |
+| `scenarios` | `abc123`  | `metadata.data.mockData.key` | `"wrong"` | `"correct"` |
+
+**File changes:**
+
+| File Path                                            | Change Description  |
+| ---------------------------------------------------- | ------------------- |
+| `/tmp/.../project/__codeyamMocks__/MockData_xyz.tsx` | Fixed missing comma |
+
+Include actual diffs for file changes.
+
+---
+
+## Step 6: Verify Fix
+
+### After Database Changes (Categories 1-3)
+
+1. Re-run `codeyam debug ANALYSIS_ID` to regenerate files with updated data
+2. Curl the URL to check for errors:
+   ```bash
+   curl -s http://localhost:PORT/static/codeyam-sample | head -50
+   ```
+3. Check for 200 response (no `statusCode:500`)
+
+If verification fails after database fixes, proceed to fix files directly (Category 4 approach).
+
+### After File Changes (Category 4)
+
+**Do NOT run `codeyam debug` again** — it overwrites your changes.
+
+1. Start the dev server manually from the tmp folder
+2. Curl the URL to check for errors
+3. For visual/rendering issues, ask the user to verify: _"Can you visit http://localhost:PORT/static/codeyam-sample and confirm the component renders correctly?"_
+
+---
+
+## Step 7: Recapture & Verify Screenshots
+
+### Choose Recapture Mode
+
+**Database-only changes:**
+
+```bash
+codeyam recapture SCENARIO_ID
+```
+
+**File changes (or mixed):**
+
+```bash
+codeyam recapture SCENARIO_ID --capture-only
+```
+
+### Verify Files Exist
+
+```bash
+sqlite3 .codeyam/db.sqlite3 "SELECT name, json_extract(metadata, '$.screenshotPaths') FROM scenarios WHERE analysis_id = 'ANALYSIS_ID'"
+find .codeyam/captures -name "*.png" -path "*ANALYSIS_ID*" -mmin -5
+```
+
+### Visually Inspect Screenshots
+
+Use the Read tool to view each screenshot. Check for:
+
+- Red error boundaries or React error overlays
+- "Something went wrong" or similar error text
+- Blank/white screens that should have content
+- Missing components or broken layouts
+
+If the screenshot shows a dedicated 500 page with no clear error, consider commenting out error boundary logic to expose the real error.
+
+**If screenshots show errors:** Go back to Step 5, check the log file (`tail -100 /tmp/codeyam/local-dev/{slug}/codeyam/log.txt`), fix remaining issues, and recapture again.
+
+---
+
+## Reference
+
+### Debug Report Template
+
+**Always produce this report** after debugging. Save to `.codeyam/debug-report.md`.
+
+```markdown
+## Debug Session Report
+
+### Issue Summary
+
+**Error:** `[Exact error message]`
+**Entity:** `[Entity name]` in `[file/path.tsx]`
+**Root Cause Category:** [1, 2, 3, or 4]
+**Outcome:** [Fixed via database changes / Fixed via file edits (engine bug) / Unfixable]
+
+### Affected Scenarios
+
+| Scenario ID | Name     | Analysis ID     | Status               |
+| ----------- | -------- | --------------- | -------------------- |
+| `[id]`      | `[name]` | `[analysis-id]` | [Fixed / Engine bug] |
+
+### Root Cause Category Determination
+
+**Category identified:** [1 / 2 / 3 / 4]
+**Evidence:**
+
+- [ ] **Category 1** (isolatedDataStructure): [What was missing/wrong?]
+- [ ] **Category 2** (mergedDataStructure): [What was missing/wrong?]
+- [ ] **Category 3** (scenario mockData): [What was wrong in LLM-generated data?]
+- [ ] **Category 4** (mock code writing): [What was wrong in generated code?]
+
+**How determined:** [Explain what you checked. Include relevant JSON snippets.]
+
+### Database Changes Made (if any)
+
+| Table     | Record ID | Field Path | Before  | After   |
+| --------- | --------- | ---------- | ------- | ------- |
+| `[table]` | `[id]`    | `[path]`   | `[old]` | `[new]` |
+
+**SQL/Python commands used:**
+[Include exact commands]
+
+### File Changes Made (if any)
+
+| File Path                                                | Change Description  |
+| -------------------------------------------------------- | ------------------- |
+| `/tmp/codeyam/local-dev/{slug}/project/path/to/file.tsx` | [Brief description] |
+
+**Diffs:**
+[Include actual diffs]
+
+**Recapture command used:**
+`codeyam recapture SCENARIO_ID [--capture-only]`
+
+### For Category 4 — Required Details
+
+**What the data looks like (correct):** [database data structure]
+**What the generated code looks like (wrong):** [problematic code]
+**What the generated code should look like:** [correct code]
+**Pattern/Edge case:** [Describe the pattern that causes this bug]
+
+### Verification
+
+- [ ] Scenario loads without errors (curl returns 200)
+- [ ] Screenshots recaptured successfully
+- [ ] Used `--capture-only` flag (if file changes were made)
+- [ ] Screenshot files verified to exist on disk
+- [ ] Screenshots visually inspected — no client-side errors visible
+- [ ] All changes documented for CodeYam team
+```
+
+### Saving & Uploading Report
+
+1. Save report to `.codeyam/debug-report.md`
+2. Ask user: "Would you like me to upload this debug report to CodeYam for the team to review?"
+3. If yes: `codeyam report --upload`
+
+### Helper Queries
+
+```bash
+# Get scenario details
+sqlite3 .codeyam/db.sqlite3 "SELECT id, analysis_id, name FROM scenarios WHERE id = 'ID'"
+
+# Get entity for analysis
+sqlite3 .codeyam/db.sqlite3 "SELECT e.name, e.file_path FROM entities e JOIN analyses a ON e.sha = a.entity_sha WHERE a.id = 'ANALYSIS_ID'"
+
+# List all scenarios for an analysis
+sqlite3 .codeyam/db.sqlite3 "SELECT id, name FROM scenarios WHERE analysis_id = 'ANALYSIS_ID'"
+
+# Check for dependent analyses
+sqlite3 .codeyam/db.sqlite3 "SELECT json_extract(metadata, '$.dependentAnalyses') FROM analyses WHERE id = 'ANALYSIS_ID'" | python3 -m json.tool
+```

package/codeyam-cli/templates/editor-step-hook.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+PostToolUse + Stop + UserPromptSubmit hook for editor mode step tracking.
+
+Reads .codeyam/editor-step.json and prints a reminder about the current step.
+Logs each firing to .codeyam/logs/editor-log.jsonl.
+If no state file exists, outputs nothing (not in editor mode or between features).
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+
+STEP_LABELS = {
+    1: "Plan",
+    2: "Prototype",
+    3: "Confirm",
+    4: "Deconstruct",
+    5: "Extract",
+    6: "Glossary",
+    7: "Analyze",
+    8: "App Scenarios",
+    9: "User Scenarios",
+    10: "Verify",
+    11: "Journal",
+    12: "Review",
+    13: "Present",
+}
+
+STEP_RESTRICTIONS = {
+    1: "Do NOT write any code. Plan and describe only. Wait for user confirmation.",
+    2: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
+    3: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
+    4: "Do NOT write any code. Read every file, identify all extractable pieces, write a numbered plan. Planning only.",
+    5: "Execute the extraction plan from step 4. Components first (no tests), then library functions via TDD. Page files must contain ZERO direct JSX.",
+    6: "Do NOT write application code or scenarios. Update the glossary only.",
+    7: "Create isolation routes for visual components, run tests for library functions. Register component scenarios via codeyam editor register.",
+    8: "Do NOT modify application code. Create and register app-level scenarios only.",
+    9: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
+    10: "Verify component isolation screenshots AND editor scenarios. After ANY code fix, re-register affected components. Fix only — do NOT add features.",
+    11: "Create or update the journal entry for this feature. Do NOT create a duplicate — check if one exists first.",
+    12: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors). Run codeyam editor audit. Do not proceed until all checks pass.",
+    13: "Show the results panel, present summary, then selection menu (AskUserQuestion): Save or make changes.",
+}
+
+
+def log_event(project_dir, event, data=None):
+    """Append a JSONL entry to .codeyam/logs/editor-log.jsonl."""
+    try:
+        logs_dir = os.path.join(project_dir, ".codeyam", "logs")
+        os.makedirs(logs_dir, exist_ok=True)
+        log_path = os.path.join(logs_dir, "editor-log.jsonl")
+        entry = {"ts": datetime.now(timezone.utc).isoformat(), "event": event}
+        if data:
+            entry.update(data)
+        with open(log_path, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass  # Logging is best-effort
+
+
+def detect_event():
+    """Detect whether this is a PostToolUse, Stop, or UserPromptSubmit hook from stdin."""
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return "unknown", {}
+        data = json.loads(raw)
+        # PostToolUse has tool_name; Stop has stop_hook_active; UserPromptSubmit has prompt
+        if "tool_name" in data:
+            return "post_tool_use", data
+        elif "stop_hook_active" in data:
+            return "stop", data
+        elif "prompt" in data:
+            return "user_prompt", data
+        return "unknown", data
+    except Exception:
+        return "unknown", {}
+
+
+def main():
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
+    prompt_path = os.path.join(project_dir, ".codeyam", "editor-user-prompt.txt")
+
+    # Detect event early so we can capture the user prompt even before state exists
+    event_type, event_data = detect_event()
+
+    # Capture the very first user prompt (before state file may exist).
+    # Save to a separate file so it persists across state transitions.
+    if event_type == "user_prompt" and not os.path.exists(prompt_path):
+        prompt_text = event_data.get("prompt", "").strip()
+        if prompt_text:
+            try:
+                os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+                with open(prompt_path, "w") as f:
+                    f.write(prompt_text)
+            except Exception:
+                pass  # Best-effort
+
+    if not os.path.exists(state_path):
+        return
+
+    try:
+        with open(state_path, "r") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return
+
+    step = state.get("step")
+    label = state.get("label", "Unknown")
+    feature = state.get("feature", "")
+
+    if not step:
+        return
+
+    # Log the hook firing
+    log_data = {"step": step, "label": label, "feature": feature, "hook": event_type}
+    if event_type == "post_tool_use":
+        log_data["tool"] = event_data.get("tool_name", "")
+    log_event(project_dir, "hook", log_data)
+
+    restriction = STEP_RESTRICTIONS.get(step, "")
+    next_cmd = f"codeyam editor {step + 1}" if step < 13 else "codeyam editor 1"
+
+    # UserPromptSubmit: concise workflow reminder injected before Claude processes the user's message
+    if event_type == "user_prompt":
+        lines = [
+            f'<user-prompt-submit-hook>',
+            f'Editor Mode — Step {step} ({label}): "{feature}"',
+        ]
+
+        # Include the active scenario so Claude knows what the user is looking at
+        active_scenario_path = os.path.join(project_dir, ".codeyam", "active-scenario.json")
+        try:
+            with open(active_scenario_path, "r") as f:
+                active = json.load(f)
+            scenario_name = (
+                active.get("scenarioName")
+                or active.get("scenarioSlug", "").replace("_", " ")
+            )
+            if scenario_name:
+                lines.append(
+                    f'The user is currently viewing scenario: "{scenario_name}". '
+                    "Assume any feedback refers to this scenario unless they say otherwise."
+                )
+        except (IOError, json.JSONDecodeError):
+            pass
+
+        if step == 13:
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE writing any code. "
+                "The change command gives you the post-change checklist. "
+                "If the user chose to commit, run `codeyam editor steps` after committing "
+                "to start the next feature."
+            )
+        else:
+            lines.append(
+                f"You are on step {step}. Follow the `codeyam editor` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
+            )
+        if restriction:
+            lines.append(restriction)
+        lines.append('</user-prompt-submit-hook>')
+        print("\n".join(lines))
+        return
+
+    lines = [
+        f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
+    ]
+    if restriction:
+        lines.append(restriction)
+
+    if event_type == "stop":
+        # Build colored progress tracker using ANSI escape codes
+        GREEN = "\033[32m"
+        BOLD_CYAN = "\033[1;36m"
+        DIM = "\033[2m"
+        RESET = "\033[0m"
+        tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
+        for i in range(1, 14):
+            lbl = STEP_LABELS[i].ljust(28)
+            num = f" {i}" if i < 10 else f"{i}"
+            content = f"{num}. {lbl}"
+            if i < step:
+                tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
+            elif i == step:
+                tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
+            else:
+                tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
+        tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+        lines.append("Present this progress tracker to the user (copy verbatim):")
+        lines.extend(tracker)
+        lines.append(
+            "For the CURRENT step (\u2192), show each checklist item with "
+            "\u2713 (done) or \u2717 (skipped + reason)."
+        )
+
+    lines.append(f"When this step is complete, run: {next_cmd}")
+
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()