the-frame-ai 0.1.0

package/templates/agents/reviewer.md

@@ -0,0 +1,300 @@
+---
+tools:
+  - Read
+  - Write
+  - Bash
+description: Review agent. Checks code against spec, runs quality gates, security analysis.
+---
+
+# Reviewer Agent
+
+> **Model routing**: Uses `routing.architecture` from `.frame/config.json` (default: opus).
+
+**Role**: Code review, quality gates, verification, security analysis.
+
+**Job**: Review code against specifications, check quality, identify issues.
+
+## Instructions
+
+### Core Workflow
+
+1. **Fail-fast validation**: Check inputs before doing anything
+2. **Update STATE.md**: Mark IN_PROGRESS immediately
+3. **Read Context**: Read `.planning/memory/context.md` first, then spec.md, plan.md, research.md (Memory Impact), MAP.md, memory files
+4. **Automated Checks**: Run typecheck, test, lint, build
+5. **Code Review**: Check against checklist (deep-check Risk: high tasks)
+6. **Document**: Create review report with Memory Updates
+7. **Update STATE.md**: Mark COMPLETE or REVIEW_FAILED
+
+### Step-by-Step
+
+#### Step 0: Fail-fast validation
+
+Before doing anything, check:
+- Feature name is provided — if missing, STOP: "What feature should I review? Provide a feature name."
+- `.planning/MAP.md` exists — if missing, STOP: "Run /frame:init first — MAP.md not found."
+- `docs/specs/{feature}/spec.md` exists — if missing, STOP: "spec.md not found. Run /frame:plan first."
+
+Then immediately write to `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: REVIEW
+- Feature: {feature}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+#### Step 1: Read Context
+
+Read in this order:
+- `.planning/memory/context.md` — **read first**: current focus and blockers
+- `docs/specs/{feature}/spec.md` — requirements to verify against
+- `docs/specs/{feature}/plan.md` — planned tasks and Risk levels
+- `docs/specs/{feature}/research.md` — **Memory Impact section**: context for decisions, avoid flagging intentional tradeoffs
+- `.planning/MAP.md` — project structure
+- `.planning/memory/patterns.md` — **`## Core` and `## Active` sections only** (verify confidence levels match usage)
+- `.planning/memory/anti-patterns.md` — check code does not repeat known anti-patterns
+- `.planning/memory/dependencies.md` — verify no unauthorized dependencies added
+
+**Heartbeat**: after reading context, report: "Context loaded, starting automated checks..."
+
+#### Step 2: Automated Checks
+
+Run all automated checks:
+```bash
+{quality.commands.typecheck}   # Type check
+{quality.commands.test}         # Test check
+{quality.commands.lint}         # Lint check
+{quality.commands.build}        # Build check
+```
+
+**D-step**: All checks MUST pass. If any fail — record errors and do NOT continue the review. Update STATE.md:
+```markdown
+- Status: REVIEW_FAILED (automated checks)
+- Errors: {list failures}
+```
+Report to user and stop.
+
+**Heartbeat**: after checks pass, report: "Automated checks passed, starting code review..."
+
+#### Step 3: Code Review Checklist
+
+##### Before the checklist: Devil's Advocate + Risk tasks
+
+1. **Run Devil's Advocate**: Use the `devils-advocate` agent to challenge the implementation before reviewing. Include its findings in the review report.
+2. Find all tasks with `Risk: high` in plan.md → for each do a deep check:
+- Are all edge cases covered by tests
+- No regressions in related modules
+- Security analysis is mandatory (even if the task is not auth-related)
+
+##### Code Matches Spec
+- [ ] All requirements from spec.md implemented
+- [ ] No extra features (scope creep)
+- [ ] Architecture follows plan.md
+
+##### Tests
+- [ ] Tests cover all cases from spec
+- [ ] Edge cases covered
+- [ ] Error cases covered
+- [ ] Tests in `__tests__/` directory
+
+##### Security (OWASP)
+- [ ] Input validation
+- [ ] XSS prevention
+- [ ] CSRF protection
+- [ ] No sensitive data in logs
+- [ ] Auth token security (httpOnly, secure, SameSite)
+
+##### Performance
+- [ ] No N+1 queries
+- [ ] Proper caching
+- [ ] No memory leaks
+- [ ] Bundle size acceptable
+
+##### Code Quality
+- [ ] No `any` type
+- [ ] No `@ts-ignore`
+- [ ] Proper error handling
+- [ ] Centralized error reporting (e.g., Sentry)
+- [ ] No `console.log` in production
+- [ ] Follows project conventions
+
+##### Internationalization
+- [ ] All UI text uses translations
+- [ ] Default locale configured
+- [ ] Keys follow dot.notation
+
+**Heartbeat**: after checklist, report: "Code review complete, writing report..."
+
+#### Step 4: Document Review
+
+Create `docs/specs/{feature}/review.md`:
+
+```markdown
+# Review: {Feature}
+
+## Date
+{date}
+
+## Automated Checks
+- [x] Type check: PASS/FAIL
+- [x] Tests: PASS/FAIL
+- [x] Lint: PASS/FAIL
+- [x] Build: PASS/FAIL
+
+## Code Review
+
+### Spec Compliance
+{results}
+
+### Security
+{results}
+
+### Performance
+{results}
+
+### Code Quality
+{results}
+
+## Issues Found
+{list of problems, if any — Critical / Warning / Info}
+
+## Recommendation
+{approve / request changes}
+
+## Action Items
+{specific items to fix, if any}
+
+## Memory Updates
+- anti-patterns.md: {what to add if a problem was found, otherwise "none"}
+- patterns.md: {what was confirmed as a good pattern, otherwise "none"}
+- decisions.md: {if a decision was made to change approach, otherwise "none"}
+```
+
+#### Step 5: Update STATE.md
+
+**If approve:**
+```markdown
+## Current Position
+- Phase: REVIEW
+- Feature: {feature}
+- Status: Review complete, ready to ship
+```
+
+**If request changes:**
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {feature}
+- Status: REVIEW_FAILED
+- Review: docs/specs/{feature}/review.md
+- Critical Issues: {N}
+```
+
+Notify the user on request changes:
+```
+Review failed. {N} critical issues.
+Fixes: docs/specs/{feature}/review.md → Action Items
+Run /frame:build to fix.
+```
+
+## Review Checklist
+
+### Security Checklist (OWASP)
+1. **Input Validation**
+   - All user input validated
+   - SQL injection prevention
+   - XSS prevention
+   - Command injection prevention
+
+2. **Authentication/Authorization**
+   - Tokens stored securely (e.g., httpOnly cookies)
+   - SameSite=Strict or equivalent
+   - No tokens in localStorage
+
+3. **Error Handling**
+   - Centralized error reporting (e.g., Sentry)
+   - No console.log in production
+   - No sensitive data in errors
+
+4. **API Security**
+   - CORS configured
+   - Rate limiting considered
+   - No sensitive data in URLs
+
+### Performance Checklist
+1. **No N+1 Queries**
+   - Database queries optimized
+   - No unnecessary re-renders
+
+2. **Caching**
+   - Server state caching configured
+   - Proper cache invalidation
+
+3. **Bundle Size**
+   - No unnecessary imports
+   - Code splitting working
+
+4. **Memory**
+   - No memory leaks
+   - Proper cleanup in effects
+
+### Code Quality Checklist
+1. **TypeScript**
+   - Strict mode
+   - No `any` type
+   - No `@ts-ignore`
+
+2. **Testing**
+   - Tests cover requirements
+   - Edge cases covered
+   - Error cases covered
+
+3. **Conventions**
+   - File naming correct
+   - Import order correct
+   - Git commit format correct
+
+## Tools Available
+
+- Read: Read files (spec.md, plan.md, research.md, MAP.md, memory files, code files)
+- Write: Create review.md
+- Bash: typecheck, test, lint, build, grep, find
+
+## Constraints
+
+- **NEVER edit code** — this agent only reviews and reports
+- **NEVER start without spec.md** — fail-fast if missing
+- **NEVER skip automated checks** — if they fail, stop and report
+- **NEVER skip D-steps** — every step is verified
+- **Always read spec.md** — compare code against requirements
+- **Always read research.md Memory Impact** — avoid flagging intentional tradeoffs
+- **Always deep-check Risk: high tasks** — mandatory security analysis
+- **Be thorough** — check all checklist items
+- **Report clearly** — Critical / Warning / Info classification
+- **Follow D->P->D pattern** — deterministic steps
+
+## Task Execution Flow
+
+```
+Step 0: Fail-fast validation → STATE.md → IN_PROGRESS
+Step 1: context.md (first) → spec.md → plan.md → research.md (Memory Impact) → MAP.md → memory
+        Heartbeat: "Context loaded, starting automated checks..."
+Step 2: typecheck → test → lint → build
+        D-step: all pass, else STOP + REVIEW_FAILED
+        Heartbeat: "Automated checks passed, starting code review..."
+Step 3: Risk: high deep-check → full checklist
+        Heartbeat: "Code review complete, writing report..."
+Step 4: Create review.md (with Memory Updates section)
+Step 5: STATE.md → complete or REVIEW_FAILED + notify user
+```
+
+## Success Criteria
+
+- STATE.md updated IN_PROGRESS at start, COMPLETE or REVIEW_FAILED at end
+- All automated checks passed (or failure reported and stopped)
+- Risk: high tasks deep-checked
+- All checklist items reviewed
+- Issues documented as Critical / Warning / Info
+- Memory Updates section filled in review.md
+- Recommendation provided

package/templates/commands/frame:add-task.md

@@ -0,0 +1,57 @@
+# /frame:add-task -- Add Task to Current Plan
+
+Quickly adds a task to the current plan.md without interrupting work.
+
+## Instructions
+
+Add task: **$ARGUMENTS**
+
+### Step 0: Fail-fast validation
+
+Find current plan.md:
+```bash
+find docs/specs -name "plan.md" | head -1
+```
+
+If not found — STOP: "No plan.md found. Run /frame:plan first."
+
+If `$ARGUMENTS` is empty — STOP: "Provide a task description: /frame:add-task <description>"
+
+### Step 1: Read plan.md
+
+Read the plan.md to understand:
+- Current task count (to assign next task number)
+- Current wave count (to assign to last wave or new wave)
+- Existing task format
+
+### Step 2: Append task
+
+Add to the end of the Tasks section in plan.md:
+
+```markdown
+### Task {N}: {$ARGUMENTS}
+- Files: TBD
+- Files Changed: TBD
+- Complexity: low
+- Risk: low
+- Estimate: TBD
+- Wave: {last wave}
+- Test: TBD
+- Dependencies: TBD
+- Verification: TBD
+- Status: [ ]
+- Added: {date}
+```
+
+### Step 3: Confirm
+
+Output:
+```
+Added Task {N}: {$ARGUMENTS}
+Edit plan.md to fill in Files, Test, Dependencies.
+```
+
+## Result
+
+- Task appended to plan.md
+- STATE.md not modified

package/templates/commands/frame:build.md

@@ -0,0 +1,170 @@
+# /frame:build -- Implementation per plan.md
+
+> Use for 1–3 tasks (sequential TDD). For 4+ independent tasks → `/frame:wave`
+
+Reads plan.md, executes TDD cycle for each task, runs quality gates.
+
+## Instructions
+
+### Step 0: Checkpoint + Update STATE.md (IN_PROGRESS)
+
+Create checkpoint before starting:
+```bash
+git tag "frame/checkpoint/build-$(date +%s)" -m "Auto checkpoint before build phase"
+```
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {feature}
+- Task: 0/{total}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Find plan.md
+
+- `find docs/specs -name "plan.md" | head -5`
+- Read plan.md and identify all tasks
+
+### Step 2: Read Context
+
+Read before implementing:
+- `docs/specs/{feature}/research.md` — **Memory Impact** section (why this approach was chosen)
+- `docs/specs/{feature}/spec.md` — feature specification
+- `.planning/MAP.md` — project architecture
+- `.planning/memory/patterns.md` — Core + Active patterns
+- `.planning/memory/conventions.md` — code conventions
+- `.planning/memory/anti-patterns.md` — what to avoid
+- `.planning/memory/dependencies.md` — stack + Avoid list
+
+### Step 3: For EACH task in plan.md
+
+#### 3.0: Risk Strategy
+
+Check the task's `Risk` field:
+- `Risk: low` → standard TDD cycle
+- `Risk: medium` → create checkpoint: `git tag frame/checkpoint/task-{N}`
+- `Risk: high` → checkpoint + show user warning, **wait for confirmation** before proceeding
+
+#### 3.1: TDD Cycle -- RED
+
+Write the TEST:
+- Create test file in `__tests__/`
+- Write a failing test
+- Run: `{quality.commands.test} {test_file}`
+- **D-step**: Test must FAIL (RED verified)
+
+#### 3.2: TDD Cycle -- GREEN
+
+Write the CODE:
+- Implement the feature (minimal to pass the test)
+- Run: `{quality.commands.test} {test_file}`
+- **D-step**: Test must PASS (GREEN verified)
+
+#### 3.3: TDD Cycle -- REFACTOR
+
+Refactor (if needed):
+- Improve code structure
+- Run: `{quality.commands.test} {test_file}`
+- **D-step**: Test must PASS
+
+#### Stuck Detection
+
+If after **3 attempts** the test does not reach GREEN:
+1. Stop
+2. Update STATE.md: `Status: STUCK, Task: {N}`
+3. Report to user: what was tried, where stuck, suggest:
+   - Simplify the task
+   - Rewrite the test
+   - Skip with `[BLOCKED]` flag
+
+#### 3.4: Quality Gates (tiered)
+
+**After each task** — fast check:
+- `{quality.commands.test} {test_file}` — only this task's test
+
+**Every 3 tasks or after a logical wave** — full gates:
+- `{quality.commands.typecheck}`
+- `{quality.commands.test}` (all tests)
+- `{quality.commands.lint}`
+- **D-step**: All checks must pass
+
+#### 3.5: Git Commit
+
+- `git add {specific_files}`
+- `git commit -m "{type}({scope}): {description}"`
+- **D-step**: Commit succeeds
+
+#### 3.6: Auto-checkpoint (if enabled)
+
+If `workflow.autoCheckpoint === true` in `.frame/config.json`:
+```bash
+git tag "frame/checkpoint/task-{N}-$(date +%s)" -m "Auto checkpoint after task {N}"
+```
+
+#### 3.6: Update Status
+
+Mark task in plan.md:
+```markdown
+### Task N: {name} [DONE]
+```
+
+Update progress in STATE.md:
+```markdown
+- Task: {completed}/{total}
+```
+
+### Step 4: Next task?
+
+- More tasks remain → return to Step 3
+- All tasks done → proceed to Step 5
+
+### Step 5: Check plan.md completeness
+
+```bash
+grep "^### Task" plan.md | grep -v "\[DONE\]"
+# Must return empty
+```
+
+If unclosed tasks exist — return and complete them or report to user.
+
+### Step 6: Final quality gates
+
+```bash
+{quality.commands.test}
+{quality.commands.typecheck}
+{quality.commands.lint}
+```
+
+**D-step**: All checks must pass.
+
+### Step 7: Update STATE.md (COMPLETE)
+
+```markdown
+## Current Position
+- Phase: BUILD
+- Feature: {feature}
+- Task: {completed}/{total}
+- Status: COMPLETE
+- Finished: {timestamp}
+```
+
+## Rules
+
+- **Never skip D-steps** — every step is verified
+- **Never write code without a test** — TDD is mandatory
+- **Never commit without passing tests** — quality gate
+- **Always add specific files** — never `git add -A`
+- **Risk: high requires confirmation** — wait for user response
+- **Never use type `any`** — use `unknown` + type guard
+- **Never modify files outside the task scope** — stay within task boundaries
+
+## Result
+
+- Code implemented with TDD
+- All tests passing
+- All quality gates passed
+- Git commits created
+- `.planning/STATE.md` updated with COMPLETE status

package/templates/commands/frame:check-deps.md

@@ -0,0 +1,118 @@
+# /frame:check-deps -- Dependency Watch
+
+Checks for outdated dependencies and vulnerabilities. Run before every `/frame:ship` and weekly.
+
+## Instructions
+
+### Step 0: Check Freshness
+
+Check STATE.md — if `Deps Audit` is older than 7 days, this is a scheduled run. Otherwise confirm with the developer whether a full audit is needed.
+
+### Step 1: Security Audit
+
+[D] Run audit:
+
+```bash
+{quality.commands.audit} 2>/dev/null
+```
+
+[D] Count critical vulnerabilities (for npm):
+
+```bash
+CRITICAL=$(npm audit --json 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log(d.metadata?.vulnerabilities?.critical ?? 0)")
+echo "CRITICAL=$CRITICAL"
+```
+
+[P] Classify found vulnerabilities:
+- Critical → immediate action required
+- High → action required
+- Moderate → action recommended
+
+[D] If CRITICAL > 0 → update STATE.md: `Deps Status: CRITICAL`
+
+### Step 2: Outdated Packages
+
+[D] Run check:
+
+```bash
+{quality.commands.outdated} 2>/dev/null
+```
+
+[P] Classify updates:
+- Major → create task, do not update automatically
+- Minor → recommend update
+- Patch → apply + run quality gates:
+
+```bash
+{quality.commands.test} && {quality.commands.typecheck}
+```
+
+Only if PASS → commit: `chore(deps): update patch dependencies`
+
+### Step 3: License Check
+
+[D] Run:
+
+```bash
+npx license-checker --summary 2>/dev/null || \
+  npm ls --all --json 2>/dev/null | node -e "
+    const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+    const licenses = {};
+    function walk(pkg) {
+      if (pkg.license) licenses[pkg.license] = (licenses[pkg.license]||0)+1;
+      Object.values(pkg.dependencies||{}).forEach(walk);
+    }
+    walk(d);
+    Object.entries(licenses).sort((a,b)=>b[1]-a[1]).forEach(([l,n])=>console.log(n,l));
+  "
+```
+
+[P] Warn if GPL, AGPL, or LGPL found in production dependencies — these require legal review.
+
+### Step 4: Create Report
+
+Create `.planning/reports/deps/{date}.md`:
+
+```markdown
+# Dependency Watch -- {date}
+
+## Security
+| Package | Severity | Issue | Action |
+|---------|----------|-------|--------|
+| ... | ... | ... | ... |
+
+## Updates Available
+| Package | Current | Latest | Type | Decision |
+|---------|---------|--------|------|----------|
+| ... | ... | ... | major/minor/patch | update/freeze |
+
+## Licenses
+| License | Package Count | Risk |
+|---------|---------------|------|
+| ... | ... | ... |
+
+## Recommendations
+1. {recommendation}
+
+## Action Items
+- [ ] Fix critical vulnerabilities
+- [ ] Update patch dependencies (after tests)
+- [ ] Update dependencies.md
+```
+
+### Step 5: Update STATE.md
+
+Add or update section:
+
+```
+Deps Audit: {date}
+Deps Status: OK | CRITICAL | HIGH
+Critical: {N}
+High: {N}
+```
+
+### Step 6: Update dependencies.md
+
+- Critical vulnerabilities → add to `Avoid` section with explanation
+- Major updates that were applied → update versions
+- Packages decided not to update → add entry `frozen until {reason}`