the-frame-ai 0.11.4 → 0.13.0

package/README.md

@@ -325,6 +325,7 @@ These 7 commands cover 90% of solo dev work:
 
 | Command | When to use |
 |---------|-------------|
+| `/frame:test-plan` | After review, before ship — generates a manual "go check this as a user" checklist of what changed |
 | `/frame:ship` | Commit, optional push/PR, update memory |
 | `/frame:checkpoint` | Save a git tag before a risky change |
 | `/frame:rollback` | Roll back to a checkpoint |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-frame-ai",
-  "version": "0.11.4",
+  "version": "0.13.0",
   "description": "FRAME — Framework for AI-Assisted Solo Development",
   "type": "module",
   "bin": {

package/templates/commands/frame:init.md

@@ -1,4 +1,4 @@
-# /frame:init -- Project Initialization
+# /frame:init -- Project Initialization & Refresh
 
 > **This is a slash command** — run it inside Claude Code after `npx the-frame init` has already installed the framework.
 > It scans your codebase and fills MAP.md, CLAUDE.md, and CONTEXT.md.
@@ -6,9 +6,48 @@
 
 Scans the project and fills MAP.md, CLAUDE.md, and CONTEXT.md with a complete project map.
 
+**Re-runnable.** Run it again any time the project grows — new stack, new modules, new
+dependencies. On a second run it works in **REFRESH mode**: it updates the auto-generated
+sections and leaves your hand-written content untouched (see Step 0).
+
 ## Instructions
 
-### Step 0: Auto-detect Stack
+### Step 0: Detect run mode (FIRST RUN vs REFRESH)
+
+Check whether the project has already been mapped:
+
+```bash
+grep -l "filled by /frame:init\|to be filled after /frame:init" \
+  .planning/MAP.md CLAUDE.md .planning/CONTEXT.md 2>/dev/null
+```
+
+- **Placeholders still present** → **FIRST RUN**. Fill everything (Steps 6–10 as written).
+- **No placeholders** (files already have real content) → **REFRESH**. Follow the
+  **Refresh rules** below. Announce: "Project already mapped — running in REFRESH mode."
+
+#### Refresh rules (apply only in REFRESH mode)
+
+Sections are split into two groups. Never cross the line.
+
+| File | Auto-owned (regenerate) | User-owned (NEVER overwrite) |
+|------|-------------------------|------------------------------|
+| `CLAUDE.md` | Tech Stack, Architecture, Key Patterns | Code Conventions, Rules, Anti-Patterns, FRAME Framework |
+| `MAP.md` | Quick Facts, Architecture Pattern, Entry Points, Key Layers, Data Flow, Key Patterns, File Inventory | Tech Debt / Notes (append only — keep existing lines) |
+| `CONTEXT.md` | `## Technical Context` section only | everything else |
+| `STATE.md` | — | **DO NOT touch Phase/Status.** Only append a refresh note (Step 9). |
+| `memory/conventions.md` | — | merge/append only (Step 10) |
+| `memory/dependencies.md` | — | merge/append only (Step 10) |
+
+Before overwriting any auto-owned section, **back up the files once**:
+
+```bash
+mkdir -p .planning/.backup && cp CLAUDE.md .planning/MAP.md .planning/CONTEXT.md .planning/.backup/ 2>/dev/null
+```
+
+When you rewrite an auto-owned section, replace ONLY that section (match on its `##` heading,
+stop at the next `##`). Do not reflow or reword neighbouring user-owned sections.
+
+### Step 1: Auto-detect Stack
 
 Identify the project type by checking for these files:
 - `package.json` → Node.js/JS/TS (check framework: Next.js, Express, NestJS, Vue, Svelte, React)
@@ -23,7 +62,7 @@ Run: `ls -la` and `cat README.md 2>/dev/null | head -30`
 
 Record: **stack**, **language**, **framework**, **project type** (web/api/cli/library/mobile).
 
-### Step 1: Surface Scan
+### Step 2: Surface Scan
 
 Read the project config files (those that exist):
 - `package.json` / `go.mod` / `Cargo.toml` / `pyproject.toml` — dependencies, versions
@@ -32,7 +71,7 @@ Read the project config files (those that exist):
 - `Dockerfile` / `docker-compose.yml` — deployment
 - `README.md` — project description
 
-### Step 2: Structure Scan
+### Step 3: Structure Scan
 
 Adapt commands to the detected stack:
 
@@ -64,7 +103,7 @@ find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" \
   -not -path "*/target/*" -not -path "*/__pycache__/*" | head -40
 ```
 
-### Step 3: Patterns Scan
+### Step 4: Patterns Scan
 
 Look for patterns relevant to the detected stack:
 
@@ -93,7 +132,7 @@ find . -name "*_test.*" -o -name "*.test.*" -o -name "*.spec.*" \
   | grep -v node_modules | head -15
 ```
 
-### Step 4: Dependencies Scan
+### Step 5: Dependencies & Dynamics Scan
 
 Determine inter-module dependencies:
 
@@ -105,8 +144,6 @@ grep -r "^import\|^from\|^require\|^use " . \
 
 Check for: database, cache, queues, external APIs.
 
-### Step 5: Dynamics Scan
-
 Determine data flow and async patterns:
 
 ```
@@ -115,9 +152,11 @@ grep -r "async\|await\|goroutine\|channel\|Promise\|Observable\|WebSocket\|Event
   -l 2>/dev/null | head -10
 ```
 
-### Step 6: Fill MAP.md
+### Step 6: Fill / refresh MAP.md
 
-Write results to `.planning/MAP.md`:
+Write results to `.planning/MAP.md`. In REFRESH mode regenerate only the auto-owned
+sections (see Step 0) and **keep every existing line under `## Tech Debt / Notes`** —
+append new findings below them, don't replace.
 
 ```markdown
 # Project Map -- {Project Name}
@@ -159,46 +198,58 @@ Write results to `.planning/MAP.md`:
 
 ### Step 7: Update CLAUDE.md
 
-Fill in the placeholders in `CLAUDE.md` — this is the main file Claude reads on every run:
+Fill / refresh **only** these three sections — this is the main file Claude reads on every run:
 
-- **Tech Stack** — specific stack from step 0
-- **Architecture** — brief description from step 6
+- **Tech Stack** — specific stack from Step 1
+- **Architecture** — brief description from Step 6
 - **Key Patterns** — 3-5 patterns from the code
 
+In REFRESH mode, **do not touch** `Code Conventions`, `Rules`, `Anti-Patterns`, or
+`FRAME Framework` — the user may have customised them.
+
 ### Step 8: Update CONTEXT.md
 
-Fill in the `## Technical Context` section in `.planning/CONTEXT.md`:
+Fill / refresh the `## Technical Context` section in `.planning/CONTEXT.md`:
 - Project type and stack
 - Main entry points
 - Key dependencies
 
+Leave all other sections of CONTEXT.md untouched.
+
 ### Step 9: Update STATE.md
 
-Update `.planning/STATE.md`:
-```markdown
-## Current Position
-- Phase: SETUP
-- Status: MAP.md filled, project ready to work
-```
+- **FIRST RUN** — set the starting position:
+  ```markdown
+  ## Current Position
+  - Phase: SETUP
+  - Status: MAP.md filled, project ready to work
+  ```
+- **REFRESH** — **do not change Phase or Status** (the user may be mid-feature).
+  Only append one line to the activity/log section:
+  ```markdown
+  - {date}: project map refreshed via /frame:init
+  ```
 
-### Step 10: Fill memory from scan results
+### Step 10: Fill / merge memory from scan results
 
-Using data already gathered in steps 1-5, fill two memory files:
+Using data already gathered in Steps 2-5, update two memory files. **Merge, never
+overwrite** — read the existing file first, keep all current lines, add only what's new.
 
-**`.planning/memory/conventions.md`** — add what was detected:
+**`.planning/memory/conventions.md`** — add/confirm:
 - File naming pattern (kebab-case, camelCase, etc.)
 - Import style (named vs default, path aliases)
 - Git commit format (if `.gitmessage` or recent commits reveal a pattern)
 
-**`.planning/memory/dependencies.md`** — add:
+**`.planning/memory/dependencies.md`** — add/confirm:
 - Core dependencies (from package.json / go.mod / etc.)
 - Dev tools (test runner, linter, bundler)
 - Any "avoid" patterns spotted (e.g., deprecated packages)
 
-Only fill what was actually found — no placeholders.
+Only add what was actually found — no placeholders. If a line is already present, leave it.
 
 ### Step 11: Output completion checklist
 
+**FIRST RUN:**
 ```
 ╔══════════════════════════════════════════╗
 ║  FRAME INIT — Complete                   ║
@@ -221,11 +272,39 @@ Only fill what was actually found — no placeholders.
 ╚══════════════════════════════════════════╝
 ```
 
+**REFRESH** — print a changelog of what actually changed, so the user can eyeball it:
+```
+╔══════════════════════════════════════════╗
+║  FRAME INIT — Refresh complete           ║
+╠══════════════════════════════════════════╣
+║  Changes detected since last scan:       ║
+║    • Stack:     {what changed, or "—"}   ║
+║    • Deps:      {added / removed, or "—"}║
+║    • Structure: {new modules, or "—"}    ║
+║    • Patterns:  {new patterns, or "—"}   ║
+╠══════════════════════════════════════════╣
+║  Updated (auto sections only):           ║
+║    ✓ MAP.md   ✓ CLAUDE.md   ✓ CONTEXT.md ║
+║  Preserved: your Conventions / Rules /   ║
+║  Anti-Patterns / STATE phase / notes.    ║
+║  Backup: .planning/.backup/              ║
+╚══════════════════════════════════════════╝
+```
+
+If nothing meaningful changed, say so plainly: "No significant changes since the last scan."
+
 ## Result
 
 - `.planning/MAP.md` — complete project map
 - `CLAUDE.md` — stack and architecture sections filled
 - `.planning/CONTEXT.md` — technical context filled
-- `.planning/STATE.md` — status updated
+- `.planning/STATE.md` — status updated (FIRST RUN only)
 - `.planning/memory/conventions.md` — conventions from scan
 - `.planning/memory/dependencies.md` — dependencies from scan
+
+## Rules
+
+- Re-runnable: REFRESH mode never overwrites user-authored sections or resets STATE phase.
+- Back up auto-owned files to `.planning/.backup/` before rewriting them on refresh.
+- When refreshing a section, replace only that `##` block — leave neighbours byte-for-byte intact.
+- Only write what was actually found in the scan — no placeholders, no invented content.

package/templates/commands/frame:review.md

@@ -149,6 +149,13 @@ Create `docs/specs/{feature}/review.md`:
 - Status: Review complete, ready to ship
 ```
 
+On approve, suggest the next step:
+```
+✅ Review passed.
+   → Run /frame:test-plan to get a manual "what to check as a user" list before shipping,
+     or go straight to /frame:ship.
+```
+
 **If request changes:**
 ```markdown
 ## Current Position

package/templates/commands/frame:ship.md

@@ -20,14 +20,14 @@ Update `.planning/STATE.md` before starting:
 ```
 
 Read `.planning/STATE.md` and verify:
-- `Phase: REVIEW` ✓
+- `Phase:` is `REVIEW` OR `TEST` ✓ (TEST = manual test plan was generated after review)
 - `Status:` is `approve` OR `Shipped` OR contains `ready to ship` ✓ (not `request changes`)
 
 If conditions not met → **STOP**:
 ```
 ❌ Ship blocked. Review not completed or not approved.
    Current status: {status}
-   Run /frame:review first.
+   Run /frame:review first (optionally /frame:test-plan before shipping).
 ```
 
 Check `Deps Audit` in STATE.md:

package/templates/commands/frame:test-plan.md

@@ -0,0 +1,153 @@
+# /frame:test-plan -- Manual User Acceptance Checklist
+
+Generates a human-readable checklist of what YOU, as a user, should go and verify by hand after a feature is built. Not code tests (those are written during the task) — this is the "go click through it like a real user" list before shipping.
+
+Runs in the TEST phase, between REVIEW and SHIP.
+
+## Instructions
+
+Build a manual test plan for: **$ARGUMENTS** (if empty — use the current feature from STATE.md).
+
+### Step 0: Update STATE.md (start)
+
+Update `.planning/STATE.md` before any work:
+```markdown
+## Current Position
+- Phase: TEST
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Understand what changed
+
+Read context in order (skip what doesn't exist):
+- `.planning/STATE.md` — current feature, last completed tasks
+- `docs/specs/{feature}/spec.md` — what the feature is supposed to do (user-facing behavior)
+- `docs/specs/{feature}/plan.md` — which tasks were done, their Risk levels
+- `docs/specs/{feature}/review.md` — issues found in review (verify they were actually fixed)
+
+Then look at the real diff to ground the plan in what actually changed:
+```bash
+git diff --stat HEAD~1 HEAD 2>/dev/null || git diff --stat
+git diff --stat
+```
+
+**D-step**: You now have a concrete list of what changed — features, screens, flows, endpoints, behaviors.
+
+### Step 2: Turn changes into user-facing scenarios
+
+For each change, ask: *"What would a user actually do that touches this, and what should they see?"*
+
+Cover these categories (only the ones that apply):
+
+- **Happy path** — the main flow the feature was built for, step by step as a user.
+- **Edge cases** — empty states, long input, special characters, zero/many items, slow network, offline.
+- **Error handling** — wrong input, denied permissions, failed request — does the user see a clear message (not a blank screen or crash)?
+- **Regression** — existing flows near the changed code that could have broken. Use the diff to spot which screens/features sit next to the changes.
+- **Cross-cutting** — mobile/responsive, different roles/accounts, language (i18n), refresh/back button, browser reload.
+
+Each scenario must be written for a human to follow without reading code:
+- **What to do** — concrete steps ("Open X → click Y → enter Z")
+- **Expected** — what should happen ("see message «...», item appears in list")
+
+Skip anything already fully covered by automated tests that can't be observed in the UI — this plan is about what a user *sees and does*.
+
+### Step 3: Write the test plan file
+
+Create `docs/specs/{feature}/test-plan.md`:
+
+```markdown
+# Test Plan: {Feature}
+
+## Date
+{date}
+
+## What changed
+{2–4 bullets in plain language — what's new/different from a user's point of view}
+
+## How to verify (go do this as a user)
+
+### Happy path
+- [ ] **{Scenario}**
+  - Do: {steps}
+  - Expect: {result}
+
+### Edge cases
+- [ ] **{Scenario}**
+  - Do: {steps}
+  - Expect: {result}
+
+### Error handling
+- [ ] **{Scenario}**
+  - Do: {steps}
+  - Expect: {result}
+
+### Regression (things near the change that could break)
+- [ ] **{Scenario}**
+  - Do: {steps}
+  - Expect: {result}
+
+### Cross-cutting (mobile / roles / i18n / reload)
+- [ ] **{Scenario}**
+  - Do: {steps}
+  - Expect: {result}
+
+## Where to test
+- URL / screen / command: {from .frame/config.json devServer.url, or ask}
+
+## Notes
+{anything to watch for — known limitations, things review flagged}
+```
+
+Keep it tight: 5–12 scenarios total, prioritized by Risk from plan.md (high-risk tasks get more scenarios). A short list that gets done beats a long one that doesn't.
+
+### Step 4: Tell the user to go test
+
+Output the checklist location and a short summary:
+```
+📋 Test plan ready: docs/specs/{feature}/test-plan.md
+   {N} scenarios to check by hand.
+
+Top things to verify first:
+1. {highest-risk scenario}
+2. {next}
+3. {next}
+
+→ Go through the list, tick the boxes. When it passes, run /frame:ship.
+   If something fails → /frame:debug «what broke» or /frame:fast «fix».
+```
+
+For UI-heavy scenarios, optionally suggest:
+```
+For visual scenarios you can also run /frame:verify-ui to screenshot-check in a browser.
+```
+
+### Step 5: Update STATE.md (final)
+
+```markdown
+## Current Position
+- Phase: TEST
+- Feature: {feature}
+- Test Plan: docs/specs/{feature}/test-plan.md
+- Scenarios: {N}
+- Status: Test plan ready, ready to ship
+```
+
+## Rules
+
+- **User language, not code** — every scenario must be followable without reading the source.
+- **Grounded in the diff** — scenarios come from what actually changed, not generic boilerplate.
+- **Prioritize by Risk** — high-risk tasks from plan.md get the most attention.
+- **Don't run the tests** — this command produces the checklist; the user (or /frame:verify-ui) executes it.
+- **Short and finishable** — 5–12 scenarios, not 40.
+
+## When to Use
+
+- After `/frame:review` passes, before `/frame:ship`
+- Whenever you want a concrete "what do I click to be sure this works" list
+- Before shipping anything user-facing
+
+## Result
+
+- `docs/specs/{feature}/test-plan.md` created — manual user-acceptance checklist
+- `.planning/STATE.md` updated (Phase: TEST, ready to ship)