the-frame-ai 0.1.0

package/templates/commands/frame:checkpoint.md

@@ -0,0 +1,158 @@
+# /frame:checkpoint -- Git Checkpoints
+
+> **When to use manually**: before a risky change that isn't covered by an automatic checkpoint
+> (e.g., editing config files, manual DB migrations, experimental refactors mid-session).
+> Automatic checkpoints already fire before each phase (research/plan/build/review) if `autoCheckpoint: true` in config.
+> Use this command when you want a checkpoint *outside* those phase boundaries.
+
+Manage checkpoints (git tags) before each phase.
+
+## Instructions
+
+Command: **$ARGUMENTS**
+
+### Routing
+
+Determine action from the first argument:
+- `list` -- show all checkpoints
+- `create <message>` -- create a manual checkpoint
+- `auto <phase>` -- automatic checkpoint before a phase
+
+---
+
+## Action: list
+
+Show all checkpoints for the current feature.
+
+```bash
+git tag -l "frame/checkpoint/*" --sort=-creatordate
+```
+
+### Output
+
+```
++======================================================================+
+|                    FRAME CHECKPOINTS                                  |
++======================================================================+
+|  frame/checkpoint/research-20260519-1430                              |
+|  frame/checkpoint/plan-20260519-1500                                  |
+|  frame/checkpoint/build-20260519-1530                                 |
+|                                                                      |
+|  Total: 3 checkpoints                                                |
+|  Max: 10                                                             |
++======================================================================+
+```
+
+---
+
+## Action: create
+
+Create a manual checkpoint.
+
+### Step 1: Check Max Checkpoints
+
+```bash
+COUNT=$(git tag -l "frame/checkpoint/*" | wc -l)
+```
+
+If COUNT >= 10, suggest removing old ones:
+```bash
+git tag -l "frame/checkpoint/*" --sort=creatordate | head -n 5
+```
+
+### Step 2: Create Tag
+
+```bash
+TIMESTAMP=$(date +%Y%m%d-%H%M)
+git tag "frame/checkpoint/manual-$TIMESTAMP" -m "Manual checkpoint: $MESSAGE"
+```
+
+### Step 3: Show Result
+
+```
++======================================================================+
+|                    CHECKPOINT CREATED                                 |
++======================================================================+
+|  Tag: frame/checkpoint/manual-{timestamp}                            |
+|  Message: {message}                                                  |
+|  Commit: {hash}                                                      |
+|                                                                      |
+|  Rollback: /frame:rollback --to manual-{timestamp}                   |
++======================================================================+
+```
+
+---
+
+## Action: auto
+
+Automatic checkpoint before a phase.
+
+### Step 1: Identify Phase
+
+Phase from the argument or from STATE.md:
+```bash
+grep -oP 'Phase: \K.*' .planning/STATE.md
+```
+
+### Step 2: Check Settings
+
+```json
+{
+  "autoCheckpoint": true,
+  "checkpointBefore": ["research", "plan", "build", "review"]
+}
+```
+
+If the phase is in checkpointBefore, create a checkpoint.
+
+### Step 3: Create Checkpoint
+
+```bash
+TIMESTAMP=$(date +%Y%m%d-%H%M)
+git tag "frame/checkpoint/$PHASE-$TIMESTAMP" -m "Auto checkpoint before $PHASE phase"
+```
+
+### Step 4: Clean Up Old Checkpoints if Needed
+
+```bash
+COUNT=$(git tag -l "frame/checkpoint/*" | wc -l)
+if [ "$COUNT" -gt 10 ]; then
+  git tag -l "frame/checkpoint/*" --sort=creatordate | head -n $((COUNT - 10)) | xargs git tag -d
+fi
+```
+
+---
+
+## Action: cleanup
+
+Remove checkpoints after a successful Ship.
+
+```bash
+# Delete all frame/checkpoint/* tags
+git tag -l "frame/checkpoint/*" | xargs git tag -d
+```
+
+### Output
+
+```
++======================================================================+
+|                    CHECKPOINTS CLEANED                                |
++======================================================================+
+|  Deleted: {count} checkpoints                                        |
+|  Reason: cleanupAfterShip                                            |
++======================================================================+
+```
+
+## Rules
+
+- **Git tags, not commits** -- do not pollute history
+- **Max 10 checkpoints** -- to avoid bloat
+- **cleanupAfterShip** -- removes checkpoints after a successful Ship
+- **Auto checkpoint** -- before each phase listed in checkpointBefore
+- **Timestamp format**: `%Y%m%d-%H%M`
+
+## Result
+
+- Checkpoint created via git tag
+- Old checkpoints automatically pruned
+- Cleanup after Ship

package/templates/commands/frame:cleanup-memory.md

@@ -0,0 +1,80 @@
+# /frame:cleanup-memory -- Memory Cleanup
+
+Cleans and updates memory files.
+
+## Instructions
+
+Run memory and artifact cleanup.
+
+### Step 1: Split patterns into Core and Archive
+
+Scan `.planning/memory/patterns.md` and apply the following rules:
+
+#### Promote to Core
+
+Move patterns from the `## Active` section to `## Core` if they meet **any** of:
+- `confidence: high` (confirmed 5+ times)
+- `confidence: medium` with `confirmed: >= 3` **and** `last:` within the last 90 days
+
+Core patterns are the default approaches that the Planner reads for decision-making.
+
+#### Stale-mark active patterns
+
+Scan patterns in `## Active` where `last:` is older than 90 days. Add `[stale]` to the header — do not delete:
+```markdown
+## Redis Sessions [stale, confidence: high, confirmed: 8x, added: 2025-11-01, last: 2025-12-10]
+```
+When a stale pattern is confirmed again, remove the `[stale]` tag and update `last:`.
+
+#### Archive low-confidence patterns
+
+Move patterns with `confidence: low` and `last:` older than 60 days to the `## Archived` section. If their `confirmed` count is now >= 2, promote to `medium` first.
+
+### Step 2: Trim metrics.md
+
+Keep only the last 4 weeks of data in `.planning/memory/metrics.md`.
+
+### Step 3: Trim wins.md
+
+Keep only the last 10 entries in `.planning/memory/wins.md`.
+
+### Step 4: Trim decisions.md
+
+Keep only the last 20 entries in `.planning/memory/decisions.md`. Move older ones to an `## Archived` section at the bottom.
+
+### Step 5: Stale-mark anti-patterns.md
+
+Scan `.planning/memory/anti-patterns.md`. For any entry not referenced in the last 90 days, add `[stale]` to its header — do not delete.
+
+### Step 6: Archive old specs
+
+```bash
+find docs/specs -mindepth 1 -maxdepth 1 -type d -mtime +90 2>/dev/null
+```
+
+If any are older than 90 days, move them to `docs/specs/archive/`.
+
+### Step 7: Check MAP.md
+
+Read `.planning/MAP.md` and extract the list of key directories from the architecture or key files section. For each directory listed, verify it exists on disk and report any that are missing.
+
+### Create report
+
+Create `.planning/reports/cleanup/{date}.md`:
+
+```markdown
+# Memory Cleanup -- {date}
+
+## Actions
+- [x] Core/Archive split: reviewed (N promoted, N stale-marked, N archived)
+- [x] Metrics: trimmed to 4 weeks
+- [x] Wins: trimmed to 10 entries
+- [x] Decisions: trimmed to 20 entries
+- [x] Anti-patterns: stale-marked (N)
+- [x] Specs archived: N
+- [x] MAP.md: verified (N missing)
+
+## Archived Specs
+- {spec1}
+- {spec2}
+```

package/templates/commands/frame:context.md

@@ -0,0 +1,64 @@
+# /frame:context -- Quick Context Digest
+
+> Shows a compact re-entry digest (git activity, current task, next step).
+> Different from `memory/context.md` — that file stores persistent project context written by agents.
+> This command *reads* that file (and STATE.md, git log) and presents a summary.
+
+Fast re-entry after a break: what happened, where you are, what's next.
+
+## Instructions
+
+### Step 1: Git activity (last 3 days)
+
+```bash
+git log --oneline --since="3 days ago"
+git diff HEAD~3 --stat 2>/dev/null || git diff --stat
+```
+
+### Step 2: Read state files
+
+Read in order:
+- `.planning/STATE.md` — current phase, feature, task
+- `.planning/pause-history/` — last pause-state if exists (most recent file)
+
+### Step 3: Find open tasks
+
+From STATE.md extract tasks list. Count: total, done, remaining.
+If `resumeHint` exists in pause-state — use it as the next step.
+Otherwise derive next step from the first unchecked task in plan.md (if exists).
+
+### Step 4: Output digest
+
+Print a compact summary:
+
+```
+╔══════════════════════════════════════════╗
+║  FRAME CONTEXT                           ║
+╠══════════════════════════════════════════╣
+║  Phase:    {phase}                       ║
+║  Feature:  {feature}                     ║
+║  Task:     {done}/{total}                ║
+║  Status:   {status}                      ║
+╠══════════════════════════════════════════╣
+║  Last 3 days:                            ║
+║    {commit 1}                            ║
+║    {commit 2}                            ║
+║    ...                                   ║
+╠══════════════════════════════════════════╣
+║  Changed files (diff HEAD~3):            ║
+║    {file 1} (+N -M)                      ║
+║    {file 2} (+N -M)                      ║
+╠══════════════════════════════════════════╣
+║  Next:     {resumeHint or next task}     ║
+╚══════════════════════════════════════════╝
+```
+
+If no commits in 3 days, show "No commits — fresh start?"
+If tasks remain: show count "X tasks left"
+
+## Rules
+
+- Output only — no STATE.md writes
+- Max 25 lines total
+- If STATE.md is missing: "Run /frame:init first"
+- Always show next step — never leave user without direction

package/templates/commands/frame:daily.md

@@ -0,0 +1,77 @@
+# /frame:daily -- Morning Briefing
+
+> **Start here** after any break. This is your single entry point — replaces `/frame:where` and `/frame:status` for daily use.
+> Use `/frame:status` only when you need a full technical dump (git, memory, blockers).
+
+One-call daily standup: what was done, what's next, any blockers.
+
+## Instructions
+
+### Step 1: Git activity (yesterday)
+
+```bash
+git log --oneline --since="yesterday" --until="now"
+git log --oneline --since="2 days ago" --until="yesterday"
+```
+
+### Step 2: Read planning files
+
+Read in order:
+- `.planning/STATE.md` — current phase, feature, tasks
+- `.planning/ROADMAP.md` — upcoming milestones (first 30 lines)
+- `.planning/memory/context.md` — blockers and current focus
+
+### Step 3: Check open tasks
+
+If plan.md exists for current feature:
+```bash
+find docs/specs -name "plan.md" | head -3
+```
+Count `[ ]` (open) vs `[x]` (done) tasks.
+
+### Step 4: Output briefing
+
+```
+╔══════════════════════════════════════════╗
+║  FRAME DAILY — {date}                    ║
+╠══════════════════════════════════════════╣
+║  Yesterday:                              ║
+║    {commit 1}                            ║
+║    {commit 2}                            ║
+║    (or "No commits yesterday")           ║
+╠══════════════════════════════════════════╣
+║  Current:                                ║
+║    Phase:   {phase}                      ║
+║    Feature: {feature}                    ║
+║    Tasks:   {done}/{total} done          ║
+╠══════════════════════════════════════════╣
+║  Next up:                                ║
+║    {next unchecked task or next phase}   ║
+╠══════════════════════════════════════════╣
+║  Blockers:  {blockers or "None"}         ║
+╠══════════════════════════════════════════╣
+║  Roadmap:   {next milestone}             ║
+╚══════════════════════════════════════════╝
+```
+
+### Step 5: Action item
+
+After the briefing box, always output one line:
+
+```
+→ Run: {command} — {one-line reason}
+```
+
+Pick the command based on context:
+- Has open tasks in plan.md → `/frame:build`
+- No plan.md yet → `/frame:research` or `/frame:fast`
+- Has blockers → `/frame:unstuck`
+- Phase is REVIEW → `/frame:review`
+- Phase is SHIP → `/frame:ship`
+
+## Rules
+
+- Output only — no file writes
+- Max 35 lines
+- If STATE.md missing: "Run /frame:init first"
+- Always end with the `→ Run:` action item — never leave without a concrete next command

package/templates/commands/frame:debug.md

@@ -0,0 +1,146 @@
+# /frame:debug -- Systematic Debugging
+
+4-phase debugging workflow: Reproduce -> Root Cause -> Fix -> Review.
+
+## Instructions
+
+Debug the problem: **$ARGUMENTS**
+
+### Step 0a: Initialize STATE.md
+
+Before starting, write to `STATE.md`:
+```markdown
+- Phase: DEBUG
+- Bug: {description from $ARGUMENTS}
+- Status: IN_PROGRESS
+- Current Phase: 1/4
+- Started: {timestamp}
+```
+
+> If the session is interrupted, the next session will know where to resume.
+
+### Step 0b: Severity Classification
+
+- **Critical** (auth, billing, data loss) → create `git stash`, work in a separate branch, warn the user before any code changes
+- **High** (main flow broken) → standard debug protocol
+- **Low** (UI, minor UX) → can defer, add to backlog
+
+### Step 0c: Check Memory
+
+Before any grep, check:
+- `memory/anti-patterns.md` → look for a similar symptom (may have been solved before)
+- `memory/decisions.md` → does the bug contradict an accepted decision
+- `memory/patterns.md` → understand expected behavior
+
+> A developer should not spend an hour on a bug that was already solved.
+
+### Phase 1: Reproduce
+
+**Goal**: Understand the problem and reproduce it.
+
+Update STATE.md: `Current Phase: 1/4`
+
+1. **Describe the problem**:
+   - What is happening?
+   - What is expected?
+   - Under what conditions?
+
+2. **Find related code**:
+   - `grep -r "{keywords}" --include="*.ts" --include="*.tsx" | head -20`
+   - Check `.planning/MAP.md` for navigation
+
+3. **Reproduce**:
+   - Run relevant tests
+   - Check logs
+   - Identify steps to reproduce
+
+> **Key principle**: do not fix until you have reproduced the problem.
+
+### Phase 2: Root Cause
+
+**Goal**: Find the root cause through deterministic steps.
+
+Update STATE.md: `Current Phase: 2/4`
+
+1. **[D]** `grep -n "{symptom}"` across the codebase → get specific files and lines
+2. **[P]** Read related files, understand data flow
+3. **[D]** Add `console.log` / temporary test to confirm hypothesis
+4. **[P]** Formulate root cause: where, why, what triggers it
+5. **[D]** Run isolated test to confirm root cause
+
+> **Key principle**: root cause is a confirmed fact, not an LLM guess.
+
+**If root cause not found within 30 minutes** → stop and run `/frame:forensics` for deep analysis.
+> Debug = quick fix for a known bug type. Forensics = investigation of a systemic problem.
+
+### Phase 3: Fix
+
+**Goal**: Fix the problem using TDD.
+
+Update STATE.md: `Current Phase: 3/4`
+
+1. **Write a regression test**:
+   - A test that reproduces the bug
+   - **D-step**: The test must FAIL (confirms the bug)
+
+2. **Fix the code**:
+   - Minimal fix for the root cause
+   - Do not change anything unnecessary
+
+3. **Verify the fix**:
+   - **D-step**: Regression test must PASS
+   - Run all tests: `{quality.commands.test}`
+   - Type check: `{quality.commands.typecheck}`
+
+### Phase 4: Review and Knowledge Capture
+
+**Goal**: Ensure the fix is safe and preserve the knowledge.
+
+Update STATE.md: `Current Phase: 4/4`
+
+1. **Check side effects**:
+   - Did the fix break anything else?
+   - Are there related tests?
+
+2. **Git commit**:
+   ```bash
+   git add {files}
+   git commit -m "fix({scope}): {description}"
+   ```
+
+3. **Update memory/anti-patterns.md**:
+   ```markdown
+   ## {short bug name}
+   - Symptom: {what was observed}
+   - Root cause: {where and why}
+   - Fix: {what was done}
+   - Regression test: {path to test}
+   ```
+
+4. **Update STATE.md**:
+   ```markdown
+   ## Current Position
+   - Phase: DEBUG
+   - Feature: {issue}
+   - Status: Bug fixed
+   ```
+
+> **Key principle**: the most valuable output of a debug session is not just the fixed code, but the captured knowledge.
+
+## Rules
+
+- **Check memory first** -- anti-patterns.md may already have the answer
+- **Reproduce first** -- do not fix until you understand the problem
+- **D→P→D in Phase 2** -- every hypothesis is confirmed by a deterministic step
+- **Regression test required** -- so the bug does not return
+- **Minimal fix** -- do not change anything unnecessary
+- **Quality gates** -- type check + tests before commit
+- **Write to anti-patterns.md** -- knowledge must not be lost
+
+## Result
+
+- Root cause identified and confirmed deterministically
+- Bug fixed with regression test
+- Quality gates passed
+- Git commit created
+- `memory/anti-patterns.md` updated

package/templates/commands/frame:doctor.md

@@ -0,0 +1,170 @@
+# /frame:doctor -- FRAME Health Check
+
+Diagnoses all FRAME systems and outputs a report.
+
+## Instructions
+
+Run a full project diagnostics. Check each component:
+
+### 1. Node.js version
+
+```bash
+node_version=$(node -e "process.exit(parseInt(process.versions.node) >= 18 ? 0 : 1)" 2>/dev/null && echo "OK" || echo "REQUIRES >=18")
+echo "Node.js: $(node --version) — $node_version"
+```
+
+### 2. CLAUDE.md
+
+```bash
+if [ -f "CLAUDE.md" ]; then
+  echo "CLAUDE.md: OK ($(grep -c "## " CLAUDE.md) sections)"
+else
+  echo "CLAUDE.md: MISSING"
+fi
+```
+
+### 3. .planning/ structure
+
+```bash
+for file in STATE.md ROADMAP.md CONTEXT.md MAP.md; do
+  if [ -f ".planning/$file" ]; then
+    echo "$file: OK"
+  else
+    echo "$file: MISSING"
+  fi
+done
+```
+
+### 4. .planning/memory/
+
+```bash
+for file in context.md patterns.md conventions.md decisions.md anti-patterns.md wins.md metrics.md dependencies.md; do
+  if [ -f ".planning/memory/$file" ]; then
+    echo "$file: OK"
+  else
+    echo "$file: MISSING"
+  fi
+done
+
+# Check patterns.md has required sections
+if [ -f ".planning/memory/patterns.md" ]; then
+  for section in "## Core" "## Active" "## Archived"; do
+    if grep -q "^${section}$" .planning/memory/patterns.md; then
+      echo "patterns.md section '${section}': OK"
+    else
+      echo "patterns.md section '${section}': MISSING"
+    fi
+  done
+fi
+```
+
+### 5. .frame/config.json
+
+```bash
+if [ -f ".frame/config.json" ]; then
+  if node -e "JSON.parse(require('fs').readFileSync('.frame/config.json','utf-8'))" 2>/dev/null; then
+    echo "config.json: OK (language: $(node -e "console.log(JSON.parse(require('fs').readFileSync('.frame/config.json','utf-8')).language||'not set')"))"
+  else
+    echo "config.json: INVALID JSON"
+  fi
+else
+  echo "config.json: MISSING"
+fi
+```
+
+### 6. Settings
+
+```bash
+if [ -f ".claude/settings.local.json" ]; then
+  echo "settings.local.json: OK"
+  if grep -q "hooks" .claude/settings.local.json; then
+    echo "  Hooks configured: OK"
+  else
+    echo "  Hooks configured: MISSING"
+  fi
+else
+  echo "settings.local.json: MISSING"
+fi
+```
+
+### 7. Commands
+
+```bash
+command_count=$(ls .claude/commands/frame:*.md 2>/dev/null | wc -l | tr -d ' ')
+expected_count=$(ls .claude/commands/frame:*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ "$command_count" -ge 1 ]; then
+  echo "Commands: $command_count — OK"
+else
+  echo "Commands: $command_count — INCOMPLETE (no commands found)"
+fi
+```
+
+### 8. Agents
+
+```bash
+agent_count=$(ls .claude/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ "$agent_count" -ge 5 ]; then
+  echo "Agents: $agent_count/5 — OK"
+else
+  echo "Agents: $agent_count/5 — INCOMPLETE"
+fi
+```
+
+### 9. Hooks
+
+```bash
+for hook in safety-net.sh git-safety.sh quality-gate.sh session-init.sh; do
+  if [ -f ".claude/hooks/$hook" ]; then
+    if [ -x ".claude/hooks/$hook" ]; then
+      echo "$hook: OK (executable)"
+    else
+      echo "$hook: WARNING — not executable (chmod +x needed)"
+    fi
+  else
+    echo "$hook: MISSING"
+  fi
+done
+```
+
+### 10. Git
+
+```bash
+git_status=$(git status --short 2>/dev/null | wc -l | tr -d ' ')
+echo "Uncommitted changes: $git_status"
+echo "Recent commits:"
+git log --oneline -5 2>/dev/null
+```
+
+## Output Format
+
+```
++======================================================================+
+|                    FRAME DOCTOR REPORT                               |
++======================================================================+
+|                                                                      |
+|  Environment:                                                        |
+|   Node.js            v20.x — OK                                     |
+|                                                                      |
+|  Core Files:                                                         |
+|   CLAUDE.md          OK (N sections)                                 |
+|   .planning/         OK (4/4 files)                                  |
+|   .planning/memory/  OK (8/8 files)                                  |
+|   .frame/config.json OK (language: en)                               |
+|   settings.local.json OK                                             |
+|                                                                      |
+|  FRAME Components:                                                   |
+|   Commands:          N — OK                                          |
+|   Agents:            5/5  — OK                                       |
+|   Hooks:             4/4  — OK                                       |
+|                                                                      |
+|  Git:                                                                |
+|   Uncommitted:       N files                                         |
+|                                                                      |
++======================================================================+
+```
+
+## Result
+
+- Full FRAME diagnostics completed
+- Problems identified
+- Recommendations for fixes