the-frame-ai 0.1.0

package/templates/commands/frame:estimate.md

@@ -0,0 +1,105 @@
+# /frame:estimate -- Task Estimation
+
+Quick pre-planning estimate: scope, risks, time. Helps decide whether to start now.
+
+## Instructions
+
+### Step 0: Fail-fast
+
+Check: task/feature description provided — if missing, STOP: "What do you want to estimate?"
+
+### Step 1: Read project context
+
+```bash
+find . -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" | grep -v node_modules | grep -v .git | wc -l
+```
+
+Read:
+- `.planning/MAP.md` — architecture, key directories
+- `.planning/memory/context.md` — current focus, blockers
+- `.planning/memory/patterns.md` — Core section only
+
+### Step 2: Scope analysis
+
+Estimate which files/modules will be touched:
+```bash
+grep -r "{keywords}" --include="*.ts" --include="*.js" -l | head -20
+```
+
+Count: files likely affected, modules involved, external dependencies needed.
+
+### Step 3: Risk assessment
+
+| Factor | Low | Medium | High |
+|--------|-----|--------|------|
+| Files touched | 1-3 | 4-8 | 9+ |
+| New dependencies | 0 | 1 | 2+ |
+| Touches auth/data/core | No | Partially | Yes |
+| Has existing tests | Yes | Partial | No |
+
+### Step 4: Historical calibration
+
+Check if metrics.md has past estimates for this project:
+
+```bash
+grep "estimate" .planning/memory/metrics.md 2>/dev/null | tail -20
+```
+
+If data exists, calculate actual vs estimated accuracy:
+- Find tasks of similar size (XS/S/M/L/XL) that were completed
+- Note if estimates were consistently over or under
+
+Include in output if data available:
+```
+║  Historical (your project):              ║
+║    M tasks avg: {N} hours actual         ║
+║    Estimate accuracy: {over/under/good}  ║
+```
+
+### Step 5: Output
+
+Based on scope and risk:
+- **XS** (< 30 min): 1-2 files, no new deps, clear pattern exists
+- **S** (30-60 min): 2-4 files, minor changes, pattern exists
+- **M** (1-3 hours): 4-8 files, some new logic, 1 new dep
+- **L** (3-8 hours): 8+ files, new architecture, multiple deps
+- **XL** (1+ day): cross-cutting change, new subsystem
+
+### Step 6: Output
+
+```
+╔══════════════════════════════════════════╗
+║  FRAME ESTIMATE                          ║
+╠══════════════════════════════════════════╣
+║  Task:     {task description}            ║
+╠══════════════════════════════════════════╣
+║  Scope:                                  ║
+║    Files:  ~{N} files affected           ║
+║    Modules: {list}                       ║
+╠══════════════════════════════════════════╣
+║  Risks:                                  ║
+║    {risk 1}                              ║
+║    {risk 2}                              ║
+╠══════════════════════════════════════════╣
+║  Estimate: {XS/S/M/L/XL} ({time range}) ║
+║  Confidence: {low/medium/high}           ║
+╠══════════════════════════════════════════╣
+║  Recommendation:                         ║
+║    {start now / break down / research}   ║
+╚══════════════════════════════════════════╝
+```
+
+**Recommendation rules**:
+- XS/S → "Start now with /frame:fast"
+- M → "Start with /frame:research then /frame:plan"
+- L/XL → "Break into smaller tasks first"
+- Any HIGH risk → "Run /frame:research first"
+
+## Rules
+
+- No code changes
+- If MAP.md missing: estimate based on task description only, note low confidence
+- After output: append estimate to `.planning/memory/metrics.md`:
+  ```
+  - {date}: estimate "{task}" → {XS/S/M/L/XL} ({time range}), confidence: {low/medium/high}
+  ```

package/templates/commands/frame:explain.md

@@ -0,0 +1,84 @@
+# /frame:explain -- Explain Code Decision History
+
+Why does this code look the way it does? Surfaces decisions, patterns, and history behind a file or function.
+
+## Instructions
+
+### Step 0: Fail-fast
+
+Require a file path or function/symbol name. If missing, STOP: "What do you want explained? Provide a file path or function name."
+
+### Step 1: Read the target
+
+```bash
+cat {file_path} 2>/dev/null | head -100
+```
+
+If a function name was given, find it:
+```bash
+grep -rn "function {name}\|const {name}\|def {name}\|func {name}" . \
+  --include="*.ts" --include="*.js" --include="*.py" --include="*.go" \
+  --include="*.rs" | grep -v node_modules | head -10
+```
+
+### Step 2: Search decisions memory
+
+```bash
+grep -i "{keywords}" .planning/memory/decisions.md 2>/dev/null | head -10
+grep -i "{keywords}" .planning/memory/anti-patterns.md 2>/dev/null | head -10
+grep -i "{keywords}" .planning/memory/patterns.md 2>/dev/null | head -10
+```
+
+### Step 3: Search git history
+
+```bash
+git log --oneline --follow -- {file_path} 2>/dev/null | head -10
+git log --oneline -S "{function_name}" 2>/dev/null | head -5
+git log --oneline --grep="{keywords}" 2>/dev/null | head -5
+```
+
+Read the most relevant commit messages in full:
+```bash
+git show {commit_hash} --stat --format="%B" 2>/dev/null | head -30
+```
+
+### Step 4: Check forensics reports
+
+```bash
+ls .planning/forensics/ 2>/dev/null
+grep -l "{keywords}" .planning/forensics/*.md 2>/dev/null | head -3
+```
+
+Read any matching forensics reports (first 40 lines each).
+
+### Step 5: Output explanation
+
+```
+## Why {file or function}?
+
+### What it does
+{1-2 sentences on the current behavior}
+
+### Why it looks this way
+{Key decisions that shaped this code — from memory, git, forensics}
+
+### Decisions
+{List of relevant DEC-XXX from decisions.md, or "No recorded decisions"}
+
+### Patterns applied
+{Patterns from patterns.md that apply here, or "None recorded"}
+
+### Watch out for
+{Anti-patterns from anti-patterns.md relevant to this area, or "None recorded"}
+
+### History
+{Key commits that changed this file/function, with dates}
+```
+
+If nothing was found in memory or git: say so explicitly — "No recorded history found. This code has no documented decisions."
+
+## Rules
+
+- No code changes
+- Output only — no file writes
+- If file doesn't exist: "File not found: {path}"

package/templates/commands/frame:fast.md

@@ -0,0 +1,89 @@
+# /frame:fast -- Quick Task
+
+Executes a quick task without the full workflow: mini Research -> mini Plan -> Build.
+
+## Instructions
+
+Execute the quick task: **$ARGUMENTS**
+
+### Step 0: Initialize (10 sec)
+
+Write to `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {task description}
+- Status: IN_PROGRESS
+```
+
+Quickly check:
+- `memory/anti-patterns.md` — any similar case already solved
+- `memory/patterns.md` — expected pattern for this area
+
+**Scope limit**: if the task will take more than 30 minutes — warn the user and suggest `/frame:build`, but continue if they want to proceed.
+
+### Step 1: Mini Research (30 sec)
+
+Quickly analyze:
+- What needs to be done
+- Where the relevant files are (use `.planning/MAP.md`)
+- Whether similar patterns exist in the project
+
+### Step 2: Mini Plan (30 sec)
+
+Determine:
+- Which files to change
+- What test to write (if needed)
+- Which verification command to use
+
+### Step 3: Build (2-5 min)
+
+Execute:
+1. If a test is needed -- write the test first (RED)
+2. Write the code (GREEN)
+3. Refactor if needed
+4. Run quality gates: `{quality.commands.typecheck} && {quality.commands.test} && {quality.commands.lint}`
+5. Git commit: `git add {files} && git commit -m "{type}({scope}): {description}"`
+
+### Step 4: Update STATE.md and wins
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {task description}
+- Status: Fast task completed
+- Last fast task: {date} — {task description}
+```
+
+Append to `.planning/memory/wins.md`:
+```markdown
+- {date}: {task description} — {files changed, 1 line summary}
+```
+
+If a new pattern or anti-pattern was discovered during the task — record it in the appropriate memory file.
+
+## Rules
+
+- **Fast** -- entire task should take ≤30 minutes
+- **Scope** -- if clearly >30 min, warn and suggest `/frame:build`
+- **Tests optional** -- only if logic changed
+- **Quality gates mandatory** -- typecheck + test + lint
+- **Specific files** -- never `git add -A`
+
+## When to Use
+
+- "Add a button"
+- "Change a color"
+- "Add an icon"
+- "Fix a typo"
+- "Add padding/margin"
+- "Rename a function"
+- "Add a field to a type"
+- "Add an env variable"
+
+## Result
+
+- Task completed in 2-5 minutes
+- Quality gates passed
+- Git commit created

package/templates/commands/frame:forensics.md

@@ -0,0 +1,139 @@
+# /frame:forensics -- Deep Debugging
+
+Systematic root cause analysis with logs, git history, and monitoring.
+
+> Use when `frame:debug` hasn't found the cause in 30 minutes, or the problem is systemic/recurring.
+
+## Instructions
+
+Debug the problem deeply: **$ARGUMENTS**
+
+### Step 0: Initialize
+
+Write to `STATE.md`:
+```markdown
+- Phase: FORENSICS
+- Issue: {description from $ARGUMENTS}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+Check memory before any investigation:
+- `memory/anti-patterns.md` → similar symptom may have been investigated before
+- `memory/decisions.md` → does the problem contradict an accepted decision
+
+### Phase 1: Evidence Collection
+
+1. **Git History**
+   ```bash
+   git log --oneline -20
+   git log --all --oneline --graph | head -30
+   git blame {affected_file}
+   git diff {suspect_commit}^ {suspect_commit}
+   ```
+
+2. **Monitoring Logs (if available)**
+   - What errors appeared recently?
+   - What is the stack trace?
+   - What triggers the error?
+
+3. **Codebase**
+   ```bash
+   grep -r "{error_keyword}" --include="*.ts" --include="*.tsx" | head -20
+   find . -name "*{affected_file}*"
+   ```
+
+### Phase 2: Root Cause Analysis (D→P→D)
+
+Apply "5 Whys" — confirm each answer with a deterministic step:
+
+1. What broke? **[D]** reproduce / find in logs
+2. Why? → **[P]** hypothesis → **[D]** confirm with grep/test
+3. Why did that happen? → **[P]** hypothesis → **[D]** confirm
+4. Why was the implementation like that? → **[P]** hypothesis → **[D]** confirm
+5. Why was it not prevented? → **[P]** hypothesis → **[D]** confirm
+
+> Root cause is a confirmed fact, not a guess.
+
+### Phase 3: Timeline Reconstruction
+
+```
+T-N days: commit X (possible cause)
+T-3 days: first occurrence of error
+T-2 days: commit Y (attempted fix)
+T-1 day: error worsened
+T-0: now (incident)
+```
+
+### Phase 4: Create Report
+
+Create `.planning/forensics/{issue-id}.md`:
+
+```markdown
+# Forensic Report: {Issue}
+
+## Incident Summary
+{What happened, when, impact, who is affected}
+
+## Root Cause
+{5 Whys analysis with confirmed facts}
+
+## Timeline
+|T|Event|
+|---|---|
+|...|...|
+
+## Evidence
+### Git History
+{relevant commits}
+
+### Code Analysis
+{problematic code}
+
+### Related Issues
+{monitoring links, PRs}
+
+## Fix
+{What needs to be fixed}
+
+## Prevention
+{How to avoid this in the future}
+```
+
+### Phase 5: Update Memory
+
+**anti-patterns.md** — if a new anti-pattern was found:
+```markdown
+## Anti-pattern: {name}
+- **Why it's bad**: {reason}
+- **Correct approach**: {how to do it}
+- **Related decision**: {DEC-XXX or empty}
+- **Occurrences**: 1
+```
+
+**decisions.md** — if an architectural decision is needed:
+```markdown
+## [DEC-{XXX}] {Title}
+- **Date**: {date}
+- **Status**: accepted
+- **Context**: {why the decision was needed}
+- **Decision**: {what was decided}
+- **Consequences**: {what follows from this}
+```
+
+**Update STATE.md**:
+```markdown
+- Phase: FORENSICS
+- Issue: {issue}
+- Status: COMPLETED
+```
+
+Then run `/frame:retrospective` to capture lessons learned.
+
+## Result
+
+- Root cause identified and confirmed deterministically
+- Report created in `.planning/forensics/`
+- Timeline reconstructed
+- Memory updated (anti-patterns.md / decisions.md)
+- STATE.md updated

package/templates/commands/frame:headless.md

@@ -0,0 +1,118 @@
+# /frame:headless -- Autonomous Execution (CI mode)
+
+Runs the full FRAME workflow without interaction: Research -> Plan -> Build -> Review -> Ship.
+
+## Instructions
+
+Execute the task fully autonomously: **$ARGUMENTS**
+
+### Constraint
+
+This command runs **without interaction** -- no confirmations, no input prompts.
+Use it for CI/CD pipelines or when fully automated execution is needed.
+
+### Step 0: Check state
+
+Read `.planning/STATE.md`. If there is unfinished work (status `IN_PROGRESS`) — record it in the report as `INTERRUPTED` and start fresh for `$ARGUMENTS`.
+
+Extract the feature name from `$ARGUMENTS` (first 2-4 words, snake_case) — this is `{feature}`, used in all subsequent steps.
+
+### Step 1: Research
+
+Execute the instructions of `/frame:research` for the topic `$ARGUMENTS`.
+
+Result: `docs/specs/{feature}/research.md` created.
+
+### Step 2: Plan
+
+Execute the instructions of `/frame:plan` for feature `{feature}`.
+
+Result: `docs/specs/{feature}/spec.md` and `docs/specs/{feature}/plan.md` created.
+
+### Step 3: Build
+
+Execute the instructions of `/frame:build`.
+
+If a task gets stuck (Stuck Detection — 3 attempts without progress):
+- Mark the task as `[BLOCKED]` in plan.md
+- Record in the report: `Build: PARTIAL`
+- Continue with the next task
+
+Result: code implemented, tests pass, commits created.
+
+### Step 4: Review
+
+Execute the instructions of `/frame:review`.
+
+If review returns `REVIEW_FAILED`:
+- Automatically apply fixes from `Action Items` in review.md
+- Re-run review (maximum 2 attempts)
+- If still `REVIEW_FAILED` after 2 attempts — record in the report and continue to Ship
+
+Result: `docs/specs/{feature}/review.md` created.
+
+### Step 5: Ship
+
+Execute the instructions of `/frame:ship`, skipping the interactive push question (do not push).
+
+Result: git commit created.
+
+### Step 6: Retrospective
+
+Execute the instructions of `/frame:retrospective`.
+
+Result: memory updated.
+
+### Step 7: Create report
+
+Create `docs/specs/{feature}/headless-report.md`:
+
+```markdown
+# Headless Execution Report: {Feature}
+
+## Summary
+- **Started**: {timestamp}
+- **Completed**: {timestamp}
+- **Duration**: {total time}
+- **Result**: SUCCESS | PARTIAL | FAILED
+
+## Phases
+| Phase | Status | Time | Notes |
+|-------|--------|------|-------|
+| Research | DONE | X min | |
+| Plan | DONE | X min | Tasks: N |
+| Build | DONE/PARTIAL | X min | Commits: N, Blocked: N |
+| Review | DONE | X min | Attempts: N |
+| Ship | DONE | X min | Commit: {hash} |
+| Reflect | DONE | X min | |
+
+## Changes
+- Files changed: N
+- Tests added: N
+- Commits: N
+
+## Quality Gates
+- Typecheck: {quality.commands.typecheck} — PASS/FAIL
+- Tests: {quality.commands.test} — PASS/FAIL
+- Lint: {quality.commands.lint} — PASS/FAIL
+- Build: {quality.commands.build} — PASS/FAIL
+
+## Blocked Tasks (if any)
+- {task}: {reason}
+```
+
+## Rules
+
+- **Never stop** -- execute all phases
+- **Never ask for input** -- do everything automatically
+- **Always log** -- create a report with final status SUCCESS/PARTIAL/FAILED
+- **Always run quality gates** -- use `{quality.commands.*}` from project config
+- **Always commit** -- capture changes, but do not push without explicit request
+- **Blocked does not mean stop** -- skip blocked tasks, record them, and move on
+- **Retrospective is mandatory** -- memory update is part of the cycle
+
+## Result
+
+- Task executed fully autonomously
+- All phases completed (or recorded as PARTIAL/FAILED)
+- Report created with final status

package/templates/commands/frame:health.md

@@ -0,0 +1,86 @@
+# /frame:health -- Daily Health Check
+
+Daily project health check.
+
+## Instructions
+
+Run a project health check and create a report.
+
+### Step 1: Read project context
+
+Read `.planning/STATE.md` — note current phase and blockers.
+Read `.planning/memory/context.md` — note last retrospective date and open anti-patterns.
+
+### Step 2: Technical checks
+
+1. **Security audit**
+```bash
+{quality.commands.audit} 2>/dev/null | tail -5
+```
+
+2. **Outdated dependencies**
+```bash
+{quality.commands.outdated} 2>/dev/null | head -10
+```
+
+3. **Type check**
+```bash
+{quality.commands.typecheck} 2>&1 | tail -3
+```
+
+4. **Tests**
+```bash
+{quality.commands.test} 2>&1 | tail -5
+```
+
+5. **Disk size**
+```bash
+du -sh . --exclude=node_modules --exclude=.git 2>/dev/null || du -sh $(find . -maxdepth 1 -not -name "node_modules" -not -name ".git" -not -name "." | tr '\n' ' ') 2>/dev/null
+```
+
+6. **Git status** (uncommitted changes)
+```bash
+git status --short
+git log --oneline -5
+```
+
+### Step 3: History (last 7 days)
+
+Read reports from `.planning/reports/daily/` for the last 7 days and determine each day's status: HEALTHY=`+`, ISSUES=`~`, CRITICAL=`!`, missing=`.`.
+
+### Step 4: Determine status and actions
+
+- **HEALTHY** — all checks passed, no blockers
+- **ISSUES** — outdated dependencies, type warnings, or uncommitted changes
+- **CRITICAL** — tests failed, audit found vulnerabilities, or open blockers
+
+For each failed check, add a concrete action item to the "Action Items" section.
+
+### Step 5: Create report
+
+Create `.planning/reports/daily/{date}.md`:
+
+```markdown
+# Daily Health Check -- {date}
+
+## Status: HEALTHY | ISSUES | CRITICAL
+
+## Project
+- Phase: {phase from STATE.md}
+- Blockers: {blockers or "none"}
+- Last retrospective: {date from context.md}
+
+## Technical Checks
+- [x] Audit: {result or "clean"}
+- [x] Outdated: {count or "none"}
+- [x] Types: PASS/FAIL
+- [x] Tests: PASS/FAIL
+- [x] Disk: {size}
+- [x] Git: {count of uncommitted files or "clean"}
+
+## Action Items
+- [ ] {concrete action for each failed check}
+
+## History (7 days)
+{date}: {+|~|!|.} {date}: {+|~|!|.} ...
+```