the-frame-ai 0.1.0

package/templates/commands/frame:performance.md

@@ -0,0 +1,228 @@
+# /frame:performance -- Performance Budget
+
+Performance monitoring and bundle analysis.
+
+## Subcommands
+
+---
+
+### `/frame:performance bundle` -- Bundle Analysis
+
+### Step 0: Validate prerequisites
+
+Check `.frame/config.json` exists:
+```bash
+test -f .frame/config.json || echo "MISSING"
+```
+
+If missing → **STOP**:
+```
+❌ .frame/config.json not found. Run /frame:init first.
+```
+
+Update STATE.md:
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: Bundle analysis IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Build
+
+```bash
+{quality.commands.build} 2>&1 | tail -20
+```
+
+### Step 2: Bundle size
+
+Detect tool from `package.json`:
+
+```bash
+# Next.js
+ls -la .next/static/chunks/ 2>/dev/null | sort -k5 -rn | head -10
+
+# Vite
+ls -la dist/assets/ 2>/dev/null | sort -k5 -rn | head -10
+
+# Universal
+find dist .next build -name "*.js" 2>/dev/null | xargs ls -la | sort -k5 -rn | head -10
+```
+
+### Step 3: Compare against limits
+
+Read `.frame/config.json` → `performance` section:
+- `maxBundleSize` (default: 200KB)
+- `maxFirstLoadJS` (default: 85KB)
+
+If `{quality.commands.bundle}` is set in config — use it instead of step 2.
+
+Calculate percentage of limit and determine level:
+- < 90% of limit → PASS
+- 90–120% of limit → WARNING
+- > 120% of limit → FAIL
+
+### Step 4: Update STATE.md
+
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: Bundle analysis complete — {PASS|WARNING|FAIL}
+```
+
+---
+
+### `/frame:performance audit` -- Full Performance Audit
+
+### Step 0: Validate prerequisites
+
+Check `.frame/config.json` exists:
+```bash
+test -f .frame/config.json || echo "MISSING"
+```
+
+If missing → **STOP**:
+```
+❌ .frame/config.json not found. Run /frame:init first.
+```
+
+### Step 1: Update STATE.md
+
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: Performance audit IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 2: Bundle analysis
+
+Run all steps from `/frame:performance bundle`.
+
+**Heartbeat**: Output after each sub-step completes — build, size scan, comparison.
+
+### Step 3: Runtime metrics
+
+Check for available tools:
+
+```bash
+# Lighthouse CLI (if installed)
+npx lighthouse {url} --output=json --quiet 2>/dev/null | grep -E '"score"|"numericValue"' | head -20
+```
+
+**Heartbeat**: If Lighthouse takes > 30s — output: `Lighthouse running... ({url})`
+
+If Lighthouse is unavailable — note in report: "Check manually in Chrome DevTools → Lighthouse".
+
+Target values:
+- CLS < 0.1
+- INP < 200ms
+- LCP < 2.5s
+- Lighthouse Performance > 90
+
+### Step 4: Code review for performance anti-patterns
+
+- No N+1 queries in critical paths
+- No memory leaks (unclosed subscriptions, timers)
+- Correct caching (HTTP headers, memoization)
+- No blocking operations on the main thread
+
+### Step 5: Create report
+
+Create `.planning/reports/performance/performance-{date}.md`:
+
+```markdown
+# Performance Report -- {date}
+
+## Status: PASS | WARNING | FAIL
+
+## Bundle
+- Size: {size} / {maxBundleSize}
+- First Load JS: {size} / {maxFirstLoadJS}
+- Level: PASS | WARNING | FAIL
+
+## Runtime Metrics
+- CLS: {score} / 0.1 — {PASS|FAIL|not checked}
+- INP: {ms} / 200ms — {PASS|FAIL|not checked}
+- LCP: {ms} / 2500ms — {PASS|FAIL|not checked}
+- Lighthouse: {score} / 90 — {PASS|FAIL|not checked}
+
+## Anti-patterns
+- {issues found or "none detected"}
+
+## Enforce Level: {strict|warning|advisory}
+
+## Recommendations
+- {specific optimization suggestions}
+```
+
+### Step 6: Update memory files
+
+If anti-patterns were found in Step 4:
+- Add to `.planning/memory/anti-patterns.md`: each issue with context
+
+If new optimization patterns were confirmed:
+- Add to `.planning/memory/patterns.md`: the pattern and why it worked
+
+### Step 7: Update STATE.md
+
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: Performance audit complete — {PASS|WARNING|FAIL}
+- Report: .planning/reports/performance/performance-{date}.md
+```
+
+---
+
+### `/frame:performance check` -- Quick Check
+
+Quick bundle size check without full audit.
+
+### Step 0: Validate prerequisites
+
+Check `.frame/config.json` exists:
+```bash
+test -f .frame/config.json || echo "MISSING"
+```
+
+If missing → **STOP**:
+```
+❌ .frame/config.json not found. Run /frame:init first.
+```
+
+Update STATE.md:
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: Quick performance check IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Check
+
+```bash
+{quality.commands.build} 2>&1 | grep -E "(Bundle|First Load|chunk|dist|kB|KB)"
+```
+
+Compare output against limits from `.frame/config.json` → `performance` and output: PASS / WARNING / FAIL.
+
+### Step 2: Update STATE.md
+
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: Quick performance check complete — {PASS|WARNING|FAIL}
+```
+
+---
+
+## Enforce Levels
+
+| Level | Behavior |
+|-------|----------|
+| strict | > limit = BLOCKED, cannot Ship |
+| warning | > limit = WARNING, can Ship |
+| advisory | > limit = INFO, does not block |
+
+Default: `warning`

package/templates/commands/frame:plan.md

@@ -0,0 +1,198 @@
+# /frame:plan -- Feature Planning
+
+Takes research.md, validates it, reads memory, breaks into atomic tasks with complexity, risk, dependencies and waves.
+
+## Instructions
+
+Plan the feature: **$ARGUMENTS**
+
+### Step 0: Checkpoint
+
+Create git tag before the phase:
+```bash
+git tag "frame/checkpoint/plan-$(date +%Y%m%dT%H%M%S)" -m "Auto checkpoint before plan phase"
+```
+
+Update `.planning/STATE.md` — phase started:
+```markdown
+- Phase: PLAN
+- Feature: {feature}
+- Status: IN_PROGRESS
+```
+
+### Step 1: Find and read research.md
+
+```bash
+find docs/specs -name "research.md" | head -5
+```
+
+Read `docs/specs/{feature}/research.md`.
+
+### Step 1.1: Validate research.md (fail-fast)
+
+Check for required sections:
+- `## Requirements`
+- `## Architecture`
+- `## API Design`
+
+**If any section is missing — STOP.** Do not begin decomposition. Report:
+
+> "research.md is incomplete, missing: {sections}. Run /frame:research again or add sections manually."
+
+### Step 1.2: Read Memory Impact from research.md
+
+Find the **Memory Impact** section in research.md and extract:
+- Which patterns will be affected/created
+- Which dependencies will appear
+- Which focus will shift
+- Which conventions are affected
+
+This is the Researcher's decision context — why this approach was chosen, which alternatives were rejected.
+
+### Step 2: Read MAP.md
+
+Read `.planning/MAP.md` to understand:
+- Current project architecture
+- File structure
+- Key patterns and constraints
+
+### Step 3: Read memory files
+
+Read in the following order with restrictions:
+
+| File | What to read | Why |
+|------|-------------|-----|
+| `.planning/memory/context.md` | Entire file (**first**) | Current focus and blockers |
+| `.planning/memory/patterns.md` | **Core section only** | Established patterns (confidence: high or medium with 3+ confirmations) |
+| `.planning/memory/conventions.md` | Entire file | Code conventions for tasks |
+| `.planning/memory/dependencies.md` | Entire file + **Avoid list** | Don't propose rejected tools |
+
+**Important**: Core patterns only — experimental ones (confidence: low/medium without confirmations) are not reliable enough for planning.
+
+### Step 4: Decompose into atomic tasks
+
+**Heartbeat**: after every 5 tasks report: "Decomposition: {N} tasks created, continuing..."
+
+Break the specification into tasks. Each task must be **atomic**: Files Changed ≤ 3, Complexity ≤ medium.
+
+If a task is too large (Files Changed > 3 or Complexity: high) — split it.
+
+**Risk definition:**
+
+| Risk | Criteria |
+|------|----------|
+| `low` | 1-2 files, no cross-module dependencies |
+| `medium` | 3-5 files or touches public APIs |
+| `high` | 5+ files, touches core logic or routing |
+
+### Step 5: Define dependencies
+
+For each task: if task B uses the result of task A (file, type, function) — B depends on A.
+
+### Step 6: Group into waves
+
+```
+Wave 1: Tasks with no dependencies (parallel)
+Wave 2: Tasks depending on Wave 1
+Wave 3: Tasks depending on Wave 2
+```
+
+Rules:
+- Maximum 5 tasks per wave
+- Two tasks in the same wave cannot modify the same file
+- Each task knows its wave
+
+### Step 7: Check file conflicts
+
+Final check: no two tasks in the same wave modify the same file. On conflict — merge tasks or move to different waves.
+
+### Step 8: Create spec.md and plan.md
+
+Create `docs/specs/{feature}/spec.md` (transform research.md into a concrete specification).
+
+Create `docs/specs/{feature}/plan.md`:
+
+```markdown
+# Plan: {Feature}
+
+## Overview
+{Brief description of the plan}
+
+## Waves
+
+### Wave 1: {name}
+Tasks with no dependencies (parallel):
+- Task 1
+- Task 2
+
+### Wave 2: {name}
+Tasks depending on Wave 1:
+- Task 3
+
+## Tasks
+
+### Task 1: {name}
+- Files: `path/to/file.ts`
+- Files Changed: 2
+- Complexity: low
+- Risk: low
+- Estimate: {time estimate, e.g. 30min / 1h / 2h}
+- Wave: 1
+- Test: `path/to/file.test.ts`
+- Dependencies: NONE
+- Verification: `{quality.commands.test} path/to/file.test.ts`
+- Status: [ ]
+
+### Task 2: {name}
+- Files: `path/to/other.ts`, `path/to/another.ts`
+- Files Changed: 2
+- Complexity: medium
+- Risk: medium
+- Estimate: {time estimate, e.g. 30min / 1h / 2h}
+- Wave: 2
+- Test: `path/to/other.test.ts`
+- Dependencies: Task 1
+- Verification: `{quality.commands.test} path/to/other.test.ts`
+- Status: [ ]
+
+## Exit Criteria
+- [ ] `{quality.commands.typecheck}` passes with 0 errors
+- [ ] `{quality.commands.test}` — all tests pass
+- [ ] All tasks marked [DONE] in plan.md
+- [ ] STATE.md: Phase: BUILD, Status: complete
+```
+
+### Step 9: Update STATE.md
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: PLAN
+- Feature: {feature}
+- Task: 0/{total}
+- Status: COMPLETE — plan created, {total} tasks in {waves} waves
+```
+
+### Step 10: Report result
+
+Show the user:
+- Number of tasks and waves
+- Tasks with Risk: high (if any)
+- Next step: `/frame:build` (sequential) or `/frame:wave` (parallel)
+
+## Rules
+
+- **Fail-fast on research.md** — don't plan on incomplete data
+- **Core patterns only** — don't trust experimental ones
+- **Avoid list** — don't propose rejected tools
+- **Atomic tasks** — Files Changed ≤ 3, Complexity ≤ medium
+- **Risk on every task** — Builder must see risks upfront
+- **Test on every task** — every task is verified
+- **No file conflicts** within one wave
+- **Never edit code** — only create spec.md and plan.md
+
+## Result
+
+- `docs/specs/{feature}/spec.md` — specification
+- `docs/specs/{feature}/plan.md` — plan with tasks
+- `.planning/STATE.md` updated

package/templates/commands/frame:refactor.md

@@ -0,0 +1,161 @@
+# /frame:refactor -- Refactoring with Test Coverage
+
+Analyzes an area, plans the refactor, executes with TDD, checks quality gates.
+
+## Instructions
+
+Refactor: **$ARGUMENTS**
+
+### Step 0: Checkpoint + Update STATE.md (IN_PROGRESS)
+
+Create checkpoint before starting:
+```bash
+git tag "frame/checkpoint/refactor-$(date +%s)" -m "Auto checkpoint before refactor"
+```
+
+Update `.planning/STATE.md` before any work:
+```markdown
+## Current Position
+- Phase: REFACTOR
+- Feature: {area}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Read Context
+
+Read before refactoring:
+- `.planning/memory/patterns.md` — Core + Active patterns (what to follow)
+- `.planning/memory/anti-patterns.md` — what to avoid
+- `docs/specs/{feature}/research.md` — **Memory Impact** section (if exists)
+
+### Step 2: Baseline Metrics
+
+Before any changes, record:
+- Number of files in the area
+- Current test coverage (if available)
+- LOC of key files
+- List of public exports (to detect breaking changes)
+
+```bash
+grep -r "export " {area} | wc -l
+```
+
+### Step 3: Analyze the area
+
+1. **Find related files**:
+   - `grep -r "{area}" | head -20`
+   - Map the dependency graph
+
+2. **Assess current state**:
+   - How many files?
+   - Are there tests?
+   - What is the coverage?
+
+3. **Identify problems**:
+   - Code smells
+   - Duplication
+   - Tight coupling
+   - Missing tests
+
+### Step 4: Plan the refactor
+
+Create a plan as a table:
+
+| File | What changes | Test | Risk |
+|------|-------------|------|------|
+| ... | ... | ... | low/medium/high |
+
+Order: least risky changes first.
+
+### Step 5: TDD Refactor
+
+For each change:
+
+1. **Write a test** (if none exists):
+   - Define expected behavior
+   - **D-step**: Test should FAIL (RED)
+
+2. **Refactor the code**:
+   - Minimal changes
+   - Do not change behavior
+   - **D-step**: Test should PASS (GREEN)
+
+3. **Repeat** until refactor is complete
+
+#### Stuck Detection
+
+If after **3 attempts** the test does not reach GREEN:
+1. Stop
+2. Update STATE.md: `Status: STUCK, Task: {change}`
+3. Report to user: what was tried, where stuck, suggest:
+   - Simplify the change
+   - Rewrite the test
+   - Skip with `[BLOCKED]` flag
+
+### Step 6: Check for Breaking Changes
+
+Compare public API before and after:
+```bash
+grep -r "export " {area} | sort > after-exports.txt
+# compare with baseline from Step 2
+```
+
+If signatures changed — that is a breaking change and requires an explicit decision.
+
+### Step 7: Quality Gates
+
+Determine commands from the project config:
+- If `package.json` exists → use `npm test`, `npm run lint`, `npm run typecheck`
+- If TypeScript → `npx tsc --noEmit`
+- If vitest → `npx vitest run`
+- If jest → `npx jest`
+- If eslint → `npx eslint .`
+
+Run all applicable checks. **D-step**: All checks must pass.
+
+If checks fail — **do not commit**. Roll back changes:
+```bash
+git stash
+# or for specific files:
+git checkout -- {file}
+```
+
+### Step 8: Git Commit
+
+```bash
+git add {specific files from the plan}
+git commit -m "refactor({scope}): {description}"
+```
+
+### Step 9: Update Memory + STATE.md
+
+Update `.planning/memory/patterns.md` if a new good pattern was confirmed.
+Update `.planning/memory/anti-patterns.md` if a problem was found and fixed.
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: REFACTOR
+- Feature: {area}
+- Status: COMPLETE
+- Finished: {timestamp}
+```
+
+## Rules
+
+- **Behavior preservation** -- do not change behavior
+- **Test coverage** -- increase coverage
+- **Incremental** -- small steps
+- **Quality gates** -- read from project config, do not hardcode
+- **Rollback** -- if gates fail, roll back, do not commit broken code
+- **Never skip D-steps** -- every step is verified
+
+## Result
+
+- Baseline recorded, improvement is measurable
+- Code refactored without breaking changes
+- Test coverage increased
+- Quality gates passed
+- Memory files updated
+- Git commit created

package/templates/commands/frame:research.md

@@ -0,0 +1,131 @@
+# /frame:research -- Domain Research
+
+Analyzes the request, searches for alternatives, explores the codebase, creates research.md with Memory Impact.
+
+## Instructions
+
+Research the following topic: **$ARGUMENTS**
+
+> Use the `researcher` agent for this task. It runs with a fresh context window (200K) to avoid contamination from previous phases.
+
+### Step 0: Fail-fast validation
+
+**Before doing anything**, check:
+- `$ARGUMENTS` is not empty — if empty, STOP and ask: "What topic should I research? Usage: /frame:research <topic>"
+- `.planning/MAP.md` exists — if missing, STOP: "Run /frame:init first — MAP.md not found."
+
+Then immediately write to `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: RESEARCH
+- Feature: {topic from $ARGUMENTS}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Analyze the Request
+
+Determine:
+- What exactly needs to be researched
+- What alternatives may exist
+- Constraints: tech, time, budget
+
+### Step 2: Codebase Exploration
+
+Read in this order:
+
+1. `.planning/MAP.md` — project architecture (stack, patterns, key directories). **Must be first.**
+2. `.planning/memory/context.md` — current focus and blockers
+3. Grep the codebase: `grep -r "{keywords}" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" | head -20`
+4. Memory files (with staleness check):
+   - `.planning/memory/patterns.md` — **ignore entries flagged [stale]**
+   - `.planning/memory/decisions.md` — **decisions older than 6 months are context, not constraints**
+   - `.planning/memory/dependencies.md` — current stack and Avoid list
+
+**Heartbeat**: after reading memory files, report: "Context loaded, starting web research..."
+
+### Step 3: Web Research
+
+WebSearch is **required** if at least one condition is met:
+- Topic involves external APIs/libraries (versions, limits, pricing)
+- No entry for the topic in `dependencies.md`
+- No relevant pattern in `patterns.md`
+
+WebSearch is **not needed** only if:
+- Topic is about internal architecture (own code, own patterns)
+- Pattern already exists in memory with `confidence: high`
+
+Check: alternative libraries, latest versions, limits, best practices.
+
+**Heartbeat**: after web research, report: "Research complete, writing research.md..."
+
+### Step 4: Create research.md
+
+Create `docs/specs/{topic}/research.md`:
+
+```markdown
+# Research: {Topic}
+
+## Overview
+{Brief description of what is being researched}
+
+## Current State
+{What already exists in the project}
+
+## Alternatives
+
+### Option 1: {name}
+- **Pros**: {advantages}
+- **Cons**: {disadvantages}
+- **Effort**: {estimate}
+- **Risk**: {risks}
+
+### Option 2: {name}
+- **Pros**: {advantages}
+- **Cons**: {disadvantages}
+- **Effort**: {estimate}
+- **Risk**: {risks}
+
+## Recommendation
+{Recommendation with justification}
+
+## Requirements
+- {functional requirement 1}
+- {functional requirement 2}
+
+## Architecture
+{High-level description of the chosen approach}
+
+## API Design
+{Key interfaces, endpoints, or data structures}
+
+## References
+- {links to documentation}
+
+## Memory Impact
+<!-- Retrospective reads this section to decide what to persist. Fill it now while context is fresh. -->
+- patterns.md: {proposed pattern if found, otherwise "none"}
+- decisions.md: {proposed decision if made, otherwise "none"}
+- dependencies.md: {new dependencies if any, otherwise "none"}
+```
+
+**Rule**: minimum 2 alternatives. Research without alternatives is incomplete.
+
+**Do not create spec.md** — that is the responsibility of `/frame:plan`.
+
+### Step 5: Update STATE.md (phase complete)
+
+```markdown
+## Current Position
+- Phase: RESEARCH
+- Feature: {topic}
+- Status: COMPLETE
+- Started: {timestamp from step 0}
+- Completed: {timestamp}
+```
+
+## Result
+
+- `docs/specs/{topic}/research.md` — research findings with Memory Impact
+- `.planning/STATE.md` updated (COMPLETE)
+- Next phase: `/frame:plan` (takes research.md as input, creates spec.md and plan.md)