the-frame-ai 0.1.0

package/templates/commands/frame:wave.md

@@ -0,0 +1,312 @@
+# /frame:wave -- Parallel Task Execution
+
+> Use for 4+ independent tasks (parallel subagents). For 1–3 tasks → `/frame:build`
+
+Identifies dependencies, groups into waves, launches subagents in parallel.
+
+**Role**: Orchestrator (not Builder). You coordinate and validate — subagents write the code.
+
+## Instructions
+
+### Step 0: Fail-fast validation + STATE.md (IN_PROGRESS)
+
+**Before doing anything**, check:
+- `.planning/MAP.md` exists — if missing, STOP: "Run /frame:init first — MAP.md not found."
+- `plan.md` exists: `find docs/specs -name "plan.md" | head -1` — if missing, STOP: "No plan.md found. Run /frame:plan first."
+
+Then immediately update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: BUILD (wave)
+- Feature: {feature from plan.md}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+**Orchestrator heartbeat rules:**
+- After each wave completes: "Wave {N}/{total} done — {passed}/{total_tasks} tasks committed"
+- Before launching a wave: "Launching Wave {N}: {task_names}"
+- No more than 3 tool calls in a row without output
+
+### Step 1: Find plan.md
+
+- `find docs/specs -name "plan.md" | head -5`
+- Read plan.md
+
+### Step 2: Determine dependencies
+
+For each task, determine:
+- Which files it will change (Files: `path/to/file`)
+- Which other tasks it depends on (Dependencies: Task N)
+- Which wave it belongs to (auto-assigned by dependencies)
+
+**Wave algorithm**: no dependencies → Wave 1; depends on Wave N → Wave N+1; depends on multiple waves → max(waves) + 1.
+
+If plan.md already has `Wave:` fields — use them. Otherwise compute from dependencies.
+
+### Step 3: Group into waves
+
+```
+Wave 1: Tasks with no dependencies (parallel)
+Wave 2: Tasks that depend on Wave 1
+Wave 3: Tasks that depend on Wave 2
+...
+```
+
+### Step 4: Check file conflicts and Risk
+
+**File Locking Strategy:**
+
+1. Each subagent declares files in plan.md
+2. Orchestrator checks for file overlaps between tasks in the same wave
+3. If overlap exists — move tasks to separate waves or merge (sequential)
+4. If no overlap — launch in parallel
+
+```
+Subagent 1: Files: [lib/api/client.ts, types/api.ts]
+Subagent 2: Files: [components/chat/message.tsx]
+-> No overlap -> parallel OK
+
+Subagent 1: Files: [components/chat/message.tsx]
+Subagent 2: Files: [components/chat/message.tsx]
+-> Overlap -> same wave (sequential) WARNING
+```
+
+**Risk strategy for waves:**
+
+Before launching a wave, check task Risk fields:
+
+- If the wave contains a `Risk: high` task →
+  create a git checkpoint before the wave:
+  `git tag frame/pre-wave-{N}-{timestamp}`
+
+- If the wave contains more than one `Risk: high` task →
+  move them into a separate wave, do not run in parallel
+
+### Step 5: Launch Wave N
+
+Before launching, update STATE.md:
+```markdown
+- Phase: BUILD (wave)
+- Status: IN_PROGRESS
+- Wave: {N}/{total}
+- Wave Status: Running (0/{count} subagents completed)
+- Started: {timestamp}
+```
+
+For each task in the wave, launch a subagent via the Agent tool:
+- Fresh context (200K)
+- Self-contained prompt from `docs/specs/_template/subagent-prompt.md`
+- Fill in all placeholders
+
+**Maximum 5 subagents** per wave.
+
+If a subagent produces no output for more than 2 minutes →
+consider it hung, log in STATE.md: `Wave Status: AGENT_HUNG ({task_name})`
+
+### Step 6: Wave Validation (D-step)
+
+After all subagents in the wave complete:
+
+```bash
+{quality.commands.typecheck}
+{quality.commands.test}
+{quality.commands.lint}
+git log --oneline -5
+```
+
+**Logic:**
+- If **OK** -> proceed to next wave
+- If **FAIL** -> Retry strategy (see below)
+- **Max retries: 2** per wave
+
+### Retry strategy
+
+On FAIL of wave N:
+1. Identify which tasks failed (via git log — no commit present)
+2. Relaunch ONLY the failed subagents (not the entire wave)
+3. Tasks with a `[DONE]` commit — do not touch
+
+### Step 7: Repeat for each wave
+
+Repeat Steps 5-6 for each wave until all waves are complete.
+
+### Step 8: Final validation
+
+```bash
+{quality.commands.typecheck}
+{quality.commands.test}
+{quality.commands.lint}
+{quality.commands.build}
+git log --oneline -10
+```
+
+Check completeness:
+```bash
+TOTAL=$(grep -c "^### Task" plan.md)
+DONE=$(grep -c "\[DONE\]" plan.md)
+
+if [ "$TOTAL" != "$DONE" ]; then
+  echo "⚠️ Unclosed tasks: $((TOTAL - DONE)) of $TOTAL"
+  grep "^### Task" plan.md | grep -v "\[DONE\]"
+fi
+```
+
+### Step 9: Update STATE.md and Memory
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {feature}
+- Task: {completed}/{total}
+- Status: Wave execution complete -- all {N} waves passed
+```
+
+**Memory Updates (if patterns found):**
+
+Analyze git log of waves. If recurring solutions are visible → suggest adding to patterns.md:
+
+"During the wave, the following patterns were used N times: {pattern}. Add to patterns.md? (y/n)"
+
+## Wave Failure Strategy
+
+If wave N failed after 2 retries:
+
+```
+1. git tag frame/wave-failure-{N}
+2. Update STATE.md: Status: WAVE_FAILED, Wave: N
+3. Show the user:
+   ✅ What succeeded (committed waves 1..N-1)
+   ❌ What did not complete (wave N and its dependents)
+4. Do NOT auto-rollback previous waves
+```
+
+User decides: manual retry, fix and relaunch, or rollback via `/frame:rollback`.
+
+## Task format in plan.md
+
+```markdown
+### Task 1: API Client
+- Files: `lib/api/client.ts`
+- Dependencies: NONE
+- Wave: 1
+- Risk: low
+
+### Task 2: Types
+- Files: `types/api.ts`
+- Dependencies: NONE
+- Wave: 1
+- Risk: low
+
+### Task 3: UI Components
+- Files: `components/chat/message.tsx`
+- Dependencies: Task 1 (API Client), Task 2 (Types)
+- Wave: 2
+- Risk: high
+
+### Task 4: Tests for API
+- Files: `lib/api/__tests__/client.test.ts`
+- Dependencies: Task 1
+- Wave: 2
+- Risk: low
+
+### Task 5: Tests for UI
+- Files: `components/chat/__tests__/message.test.tsx`
+- Dependencies: Task 3
+- Wave: 3
+- Risk: low
+```
+
+## Subagent Prompt Template
+
+See `docs/specs/_template/subagent-prompt.md` for the full template with placeholders.
+
+Brief version for quick use:
+
+```markdown
+# Task: {task_name}
+
+## Memory (read before writing code)
+- .planning/memory/anti-patterns.md — what to avoid
+- .planning/memory/conventions.md — how to write code
+- .planning/memory/dependencies.md — stack + Avoid list
+- docs/specs/{FEATURE}/research.md → Memory Impact section
+
+## Heartbeat rules
+- After each D-step: "✓ Task {name}: {step} confirmed"
+- Before a long command: "⏳ Running: {command}"
+- No more than 3 tools in a row without output
+
+## Context
+- Project: {project_name}
+- MAP: See .planning/MAP.md
+- Spec: See docs/specs/{FEATURE}/spec.md
+- Task: {task_description}
+
+## Your Role: Builder
+1. Write TEST first (RED)
+2. Verify: `{quality.commands.test} {test_file}`
+3. Write CODE (GREEN)
+4. Verify: `{quality.commands.test} {test_file}`
+5. Refactor if needed
+6. Verify types: `{quality.commands.typecheck}`
+7. Verify lint: `{quality.commands.lint}`
+8. Git commit: `{type}({scope}): {description}`
+
+## Key Files
+- {file1} -- {purpose}
+- {file2} -- {purpose}
+
+## Patterns
+- Follow project conventions from CLAUDE.md
+- Errors: use project error reporting (no console.log for errors)
+- Types: no `any` (use `unknown` + type guard)
+
+## DO NOT
+- Do not modify files outside {scope_dir}
+- Do not skip tests
+- Do not use `any` type
+- Do not add dependencies without approval
+- Do not commit without passing quality gates
+```
+
+## Rules
+
+- **Maximum 5 subagents** per wave
+- **File locking** -- check conflicts before launching a wave
+- **Risk strategy** -- isolate high-risk tasks into a separate wave + git tag
+- **STATE.md before launch** -- update IN_PROGRESS before each wave
+- **Subagent heartbeat** -- >2 min without output = hung
+- **Wave validation** -- D-step (tsc + vitest + eslint) between waves
+- **Retry only failed** -- max 2 retries, only tasks without [DONE] commit
+- **Wave Failure Strategy** -- git tag + STATE.md + report to user, do not auto-rollback
+- **Completeness check** -- grep plan.md before final report
+- **Fresh context** -- each subagent gets an isolated 200K context
+- **Waves are sequential** -- waves do not run in parallel, only tasks within a wave do
+
+## Algorithm (summary)
+
+1. Read plan.md
+2. Determine dependencies
+3. Group into waves (independent batches)
+4. Check file conflicts + Risk
+5. Update STATE.md (IN_PROGRESS)
+6. Launch subagents in parallel (max 5)
+7. Wait for all subagents (heartbeat monitoring)
+8. Run wave validation (tsc + vitest + eslint)
+9. If OK -> next wave
+10. If FAIL -> retry only failed tasks (max 2)
+11. If FAIL after 2 retries -> Wave Failure Strategy
+12. Repeat until all waves are complete
+13. Final validation + completeness check
+14. Update STATE.md + suggest Memory Updates
+
+## Result
+
+- Tasks executed in parallel
+- Waves separated by dependencies
+- High-risk tasks isolated + git checkpoint
+- Quality gates passed between waves
+- `.planning/STATE.md` updated
+- Patterns suggested for memory

package/templates/commands/frame:where.md

@@ -0,0 +1,5 @@
+# /frame:where -- Alias for /frame:daily
+
+> This is an alias. Use `/frame:daily` instead — it does everything this command does, plus gives you a concrete next action.
+
+Run `/frame:daily` to get your current position and next step.

package/templates/commands/frame:why.md

@@ -0,0 +1,57 @@
+# /frame:why -- Search Decision History
+
+Find why a decision was made. Searches memory and git history.
+
+## Instructions
+
+Search for: **$ARGUMENTS**
+
+### Step 1: Search memory files
+
+```bash
+grep -i "$ARGUMENTS" .planning/memory/decisions.md 2>/dev/null
+grep -i "$ARGUMENTS" .planning/memory/anti-patterns.md 2>/dev/null
+grep -i "$ARGUMENTS" .planning/memory/patterns.md 2>/dev/null
+```
+
+### Step 2: Search git history
+
+```bash
+git log --oneline --grep="$ARGUMENTS" | head -10
+git log --oneline -S "$ARGUMENTS" | head -10
+```
+
+### Step 3: Search forensics reports
+
+```bash
+grep -rl "$ARGUMENTS" .planning/forensics/ 2>/dev/null | head -5
+```
+
+### Step 4: Output results
+
+Format findings:
+
+```
+Search: "{keyword}"
+
+DECISIONS:
+  [DEC-XXX] {title} — {date}
+  Context: {why it was needed}
+  Decision: {what was decided}
+
+ANTI-PATTERNS:
+  {pattern name} — {why it's bad}
+
+GIT HISTORY:
+  {hash} {commit message}
+
+FORENSICS:
+  {report file} — {issue title}
+```
+
+If nothing found: "No records found for '{keyword}'. Check spelling or try a broader term."
+
+## Rules
+
+- Read-only — never modify files
+- If $ARGUMENTS is empty: "Provide a keyword. Example: /frame:why auth"

package/templates/commands/frame:worktree.md

@@ -0,0 +1,219 @@
+# /frame:worktree -- Git Worktrees
+
+Manage isolated git worktrees for parallel work.
+
+## Instructions
+
+Command: **$ARGUMENTS**
+
+### Step 0: Fail-fast validation
+
+Before routing, run these checks:
+
+```bash
+git rev-parse --git-dir 2>/dev/null || echo "NOT_GIT"
+```
+
+If output is `NOT_GIT` — STOP with error: "Error: not a git repository. Run this command from inside a git project."
+
+For `create`: if `$NAME` is empty — STOP with error: "Error: name is required. Usage: /frame:worktree create <name>"
+
+### Routing
+
+Determine action from the first argument:
+- `create <name>` -- create a worktree
+- `list` -- show all worktrees
+- `switch <name>` -- switch to a worktree
+- `cleanup <name>` -- remove a worktree
+
+---
+
+## Action: create
+
+Create a git worktree with an isolated workspace.
+
+Update STATE.md at the start:
+```markdown
+## Current Position
+- Phase: WORKTREE
+- Action: create
+- Name: feature/{name}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Validate Name
+
+Name must follow git branch naming conventions:
+```bash
+echo "$NAME" | grep -E '^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$'
+```
+
+Check if worktree already exists:
+```bash
+git worktree list | grep "feature/$NAME" && echo "EXISTS"
+```
+
+If EXISTS — STOP with error: "Error: worktree feature/{name} already exists."
+
+### Step 2: Create Worktree
+
+```bash
+git worktree add ../$(basename $(pwd))-$NAME -b feature/$NAME
+```
+
+Say: "Worktree created, copying context..."
+
+### Step 3: Copy Context
+
+Copy planning context into the new worktree:
+```bash
+mkdir -p ../$(basename $(pwd))-$NAME/.planning
+cp .planning/STATE.md ../$(basename $(pwd))-$NAME/.planning/
+cp .planning/CONTEXT.md ../$(basename $(pwd))-$NAME/.planning/ 2>/dev/null || true
+cp .planning/MAP.md ../$(basename $(pwd))-$NAME/.planning/ 2>/dev/null || true
+```
+
+### Step 4: Show Result
+
+Update STATE.md:
+```markdown
+## Current Position
+- Phase: WORKTREE
+- Action: create
+- Name: feature/{name}
+- Status: COMPLETE
+- Started: {timestamp}
+```
+
+```
++======================================================================+
+|                    WORKTREE CREATED                                   |
++======================================================================+
+|  Name: feature/{name}                                                |
+|  Path: ../{project}-{name}                                           |
+|  Branch: feature/{name}                                              |
+|                                                                      |
+|  cd ../{project}-{name} to work in isolation                         |
++======================================================================+
+```
+
+---
+
+## Action: list
+
+Show all active worktrees.
+
+```bash
+git worktree list
+```
+
+### Output
+
+```
++======================================================================+
+|                    GIT WORKTREES                                      |
++======================================================================+
+|  {path} [{branch}]                                                   |
+|  {path} [{branch}]                                                   |
++======================================================================+
+```
+
+---
+
+## Action: switch
+
+Switch to another worktree.
+
+Show the path and instructions:
+```bash
+WORKTREE_PATH="../$(basename $(pwd))-$NAME"
+if git worktree list | grep -q "feature/$NAME"; then
+  echo "WORKTREE_PATH=$WORKTREE_PATH"
+else
+  echo "ERROR: worktree feature/$NAME not found"
+  git worktree list
+fi
+```
+
+Tell the user: "Open a new terminal and run: `cd $WORKTREE_PATH`"
+
+Show current status of the worktree:
+```bash
+git -C "../$(basename $(pwd))-$NAME" status 2>/dev/null
+git -C "../$(basename $(pwd))-$NAME" branch --show-current 2>/dev/null
+```
+
+---
+
+## Action: cleanup
+
+Remove a worktree and branch.
+
+Update STATE.md at the start:
+```markdown
+## Current Position
+- Phase: WORKTREE
+- Action: cleanup
+- Name: feature/{name}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Check Status
+
+```bash
+cd ../{project}-{name}
+git status --short
+```
+
+If there are uncommitted changes, warn the user and request confirmation.
+
+### Step 2: Remove Worktree
+
+```bash
+cd {project-root}
+git worktree remove ../{project}-{name}
+```
+
+### Step 3: Remove Branch (optional)
+
+```bash
+git branch -d feature/{name}
+```
+
+### Step 4: Show Result
+
+Update STATE.md:
+```markdown
+## Current Position
+- Phase: WORKTREE
+- Action: cleanup
+- Name: feature/{name}
+- Status: COMPLETE
+- Started: {timestamp}
+```
+
+```
++======================================================================+
+|                    WORKTREE REMOVED                                   |
++======================================================================+
+|  Name: feature/{name}                                                |
+|  Path: removed                                                       |
+|  Branch: {deleted or kept}                                           |
++======================================================================+
+```
+
+## Rules
+
+- **WorktreeBase**: `../` -- sibling directories
+- **Branch naming**: `feature/{name}`
+- **Context copy**: STATE.md, CONTEXT.md, MAP.md
+- **Cleanup**: check for uncommitted changes before removal
+- **Never force** -- warn about potential work loss
+
+## Result
+
+- Git worktree created/removed
+- Branch created/removed
+- Context copied

package/templates/hooks/git-safety.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# git-safety.sh - Blocks dangerous git commands
+
+read -r input
+
+COMMAND=$(node -e "try{const i=JSON.parse(process.argv[1]);process.stdout.write(i.tool_input?.command??'')}catch{}" -- "$input" 2>/dev/null)
+
+deny() {
+  node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:process.argv[1]}}))" -- "$1"
+  exit 0
+}
+
+ask() {
+  node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'ask',permissionDecisionReason:process.argv[1]}}))" -- "$1"
+  exit 0
+}
+
+if echo "$COMMAND" | grep -qiE 'git\s+push.*(--force|-f)' && ! echo "$COMMAND" | grep -q 'force-with-lease'; then
+  deny "FRAME Git Safety: Force push blocked. Use regular push. If you must force push, do it manually."
+fi
+
+if echo "$COMMAND" | grep -qiE 'git\s+reset\s+--hard'; then
+  if [ "${FRAME_INTERNAL}" = "1" ]; then
+    exit 0
+  fi
+  deny "FRAME Git Safety: git reset --hard blocked. Use git restore or git stash instead."
+fi
+
+if echo "$COMMAND" | grep -qiE 'git\s+add\s+(-A|\.)'; then
+  ask "FRAME Git Safety: FRAME recommends using specific files instead of git add -A. Are you sure you want to add all files?"
+fi
+
+exit 0

package/templates/hooks/quality-gate.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# quality-gate.sh - Runs typecheck and lint after file changes
+
+FILE_PATH=$(node -e "try{const i=JSON.parse(process.env.CLAUDE_TOOL_INPUT||'{}');process.stdout.write(i.file_path||i.path||'')}catch{}" 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Read quality commands from config if available
+TYPECHECK_CMD=""
+LINT_CMD=""
+if [ -f ".frame/config.json" ] && command -v node &>/dev/null; then
+  CONFIG_VALID=$(node -e "try{JSON.parse(require('fs').readFileSync('.frame/config.json','utf8'));process.stdout.write('ok')}catch(e){process.stdout.write('invalid: '+e.message)}" 2>/dev/null)
+  if [ "$CONFIG_VALID" != "ok" ]; then
+    echo "FRAME Quality Gate: .frame/config.json is malformed — $CONFIG_VALID"
+    echo "Fix it or run /frame:doctor to diagnose."
+    exit 0
+  fi
+  TYPECHECK_CMD=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.frame/config.json','utf8'));process.stdout.write(c.quality?.commands?.typecheck||'')}catch{}" 2>/dev/null)
+  LINT_CMD=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.frame/config.json','utf8'));process.stdout.write(c.quality?.commands?.lint||'')}catch{}" 2>/dev/null)
+fi
+
+# Fallback: TypeScript-only detection
+if [ -z "$TYPECHECK_CMD" ] && echo "$FILE_PATH" | grep -qiE '\.(ts|tsx)$'; then
+  TYPECHECK_CMD="npx tsc --noEmit"
+  LINT_CMD="npx eslint --fix \"$FILE_PATH\""
+fi
+
+run_cmd() {
+  local cmd="$1"
+  # Only allow commands starting with known safe prefixes
+  if ! echo "$cmd" | grep -qE '^(npx |npm run |yarn |pnpm |node |tsc |eslint |biome |deno )'; then
+    echo "FRAME Quality Gate: command not in allowlist, skipping: $cmd"
+    return 0
+  fi
+  sh -c "$cmd" 2>/dev/null
+}
+
+if [ -n "$TYPECHECK_CMD" ]; then
+  if ! run_cmd "$TYPECHECK_CMD"; then
+    echo "FRAME Quality Gate: typecheck failed for $FILE_PATH"
+  fi
+fi
+
+if [ -n "$LINT_CMD" ]; then
+  if ! run_cmd "$LINT_CMD"; then
+    echo "FRAME Quality Gate: lint issues in $FILE_PATH"
+  fi
+fi
+
+exit 0

package/templates/hooks/safety-net.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# safety-net.sh - Blocks dangerous bash commands
+
+read -r input
+
+COMMAND=$(node -e "try{const i=JSON.parse(process.argv[1]);process.stdout.write(i.tool_input?.command??'')}catch{}" -- "$input" 2>/dev/null)
+
+if echo "$COMMAND" | grep -qiE 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f|rm\s+--recursive.*--force|rm\s+--force.*--recursive|\bDROP\s+(TABLE|DATABASE)\b'; then
+  node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:'FRAME Safety Net: Destructive command blocked (rm -rf or DROP TABLE/DATABASE). Use specific, safer alternatives.'}}))"
+  exit 0
+fi
+
+exit 0