the-frame-ai 0.1.0

package/templates/commands/frame:resume.md

@@ -0,0 +1,137 @@
+# /frame:resume -- Resume Work
+
+Restores state from the last /frame:pause.
+
+## Instructions
+
+Restore state from pause.
+
+### Step 0: Fail-fast validation + mark IN_PROGRESS
+
+Verify STATE.md exists:
+```bash
+test -f .planning/STATE.md || { echo "ERROR: .planning/STATE.md not found. Run /frame:init first."; exit 1; }
+```
+
+Verify pause-state exists and is not empty:
+```bash
+test -f .planning/pause-state.json || { echo "ERROR: No pause state found. Nothing to resume."; exit 1; }
+```
+
+Read `.planning/pause-state.json` and check it has content:
+```bash
+cat .planning/pause-state.json
+```
+
+If the file contains only `{}` or is missing required fields (`phase`, `feature`, `resumeHint`), stop:
+```
+ERROR: pause-state.json is empty or invalid — no saved session to resume.
+Use /frame:status to see current state, or /frame:init to start fresh.
+```
+
+Immediately update status in `.planning/STATE.md`:
+```
+Status: IN_PROGRESS (resuming)
+```
+
+### Step 1: Read pause state
+
+Read `.planning/pause-state.json`:
+```bash
+cat .planning/pause-state.json
+```
+
+Extract: `timestamp`, `phase`, `feature`, `task`, `lastCommit`, `hasStash`, `hasWip`, `openTasks`, `resumeHint`.
+
+### Step 2: Restore uncommitted changes
+
+If `hasWip === true` — the WIP commit is already in git history, no action needed.
+
+If `hasStash === true`:
+```bash
+git stash pop
+```
+
+If `git stash pop` fails (conflicts), stop and report:
+```
+ERROR: git stash pop failed with conflicts. Resolve manually, then re-run /frame:resume.
+```
+
+Check checkpoint:
+```bash
+LAST_PAUSE=$(git tag -l "frame/pause-*" --sort=-creatordate | head -n 1)
+echo "Last pause checkpoint: $LAST_PAUSE"
+```
+
+### Step 3: Restore STATE.md
+
+Update `.planning/STATE.md` — restore context from pause:
+```markdown
+## Current Position
+- Phase: {phase from pause}
+- Feature: {feature from pause}
+- Task: {task from pause}
+- Status: RESUMED
+- Resumed at: {now}
+- Paused at: {timestamp from pause-state}
+```
+
+### Step 4: Show Context
+
+Display:
+```
++======================================================================+
+|                    FRAME RESUMED                                      |
++======================================================================+
+|  Paused at: {timestamp}                                               |
+|  Resumed at: {now}                                                    |
+|  Duration: {diff}                                                     |
+|                                                                       |
+|  Phase: {phase}                                                       |
+|  Feature: {feature}                                                   |
+|  Task: {completed}/{total}                                            |
+|                                                                       |
+|  Continue from: {resumeHint}                                          |
++======================================================================+
+```
+
+If `openTasks` is non-empty, list them:
+```
+Open tasks:
+  - {open task 1}
+  - {open task 2}
+```
+
+### Step 5: Clean up pause state
+
+Move to history (do not delete — preserves audit trail):
+```bash
+mkdir -p .planning/pause-history
+mv .planning/pause-state.json .planning/pause-history/resumed-$(date +%Y%m%d%H%M).json
+```
+
+### Step 6: Update STATE.md (final)
+
+Update `.planning/STATE.md` status to reflect active work:
+```
+Status: IN_PROGRESS
+```
+
+### Step 7: Continue Work
+
+Resume from `resumeHint`. Do not restart from the beginning of the phase.
+
+## Rules
+
+- **Fail fast** -- exit immediately if STATE.md or pause-state.json is missing
+- **Always restore stash before continuing** -- uncommitted changes must be recovered first
+- **Use resumeHint** -- continue from the exact next step, not from phase start
+- **Move pause-state to history** -- never silently delete it
+
+## Result
+
+- State restored from pause-state.json
+- Git stash applied (if hasStash)
+- STATE.md updated to IN_PROGRESS
+- pause-state.json moved to pause-history/
+- Work resumed from resumeHint

package/templates/commands/frame:retrospective.md

@@ -0,0 +1,196 @@
+# /frame:retrospective -- Retrospective + Memory Update
+
+Analyzes completed task, updates memory files, creates a retrospective report.
+
+## Instructions
+
+Run a retrospective for the last completed task.
+
+### Step 0: Validate prerequisites + Update STATE.md (IN_PROGRESS)
+
+**Fail-fast checks:**
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null || { echo "ERROR: Not a git repository. Run from project root."; exit 1; }
+git log --oneline -1 2>/dev/null || { echo "ERROR: No commits found. Nothing to retrospect."; exit 1; }
+```
+
+Check `.planning/STATE.md` — the previous phase should be SHIP or BUILD with Status: COMPLETE. If the phase is IN_PROGRESS, warn the user and ask for confirmation before continuing.
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: REFLECT
+- Feature: {feature}
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Analyze the last commit
+
+```bash
+git log --oneline -10
+git diff HEAD~1 --stat
+```
+
+### Step 2: Identify what worked
+
+- Did it fit within the estimate?
+- What patterns were used?
+- What problems were solved?
+
+### Step 3: Identify what did not work
+
+- What blockers were there?
+- What took longer than expected?
+- What mistakes were made?
+
+### Step 4: Update Memory
+
+Update the relevant memory files:
+
+#### context.md
+
+Update `.planning/memory/context.md` with current state:
+```markdown
+# Project Context
+
+## Current Focus
+- Working on: {feature}
+- Status: {completed | in progress}
+- Blocked by: {blockers or "none"}
+
+## Recent Decisions (last 2 weeks)
+- {any decision from this task}
+
+## Health
+- Last retrospective: {date}
+- Open anti-patterns: {count}
+- Stale patterns: {count}
+```
+
+#### patterns.md
+
+If a new pattern was discovered, add:
+```markdown
+## {Pattern Name} [confidence: low, confirmed: 1x, added: {date}, last: {date}]
+- **Pattern**: {description}
+- **Where**: {where it is used}
+- **Convention**: {convention}
+- **From**: {DEC-XXX if derived from a decision, or blank}
+- **Discovered**: {date}
+```
+
+If an existing pattern was used again, **update its metadata**:
+- Increment `confirmed` count
+- Update `last` date
+- Promote confidence: `low` (1x) -> `medium` (2-4x) -> `high` (5+)
+
+#### anti-patterns.md
+
+If an anti-pattern was discovered, add:
+```markdown
+## Anti-pattern: {anti-pattern}
+- **Why it is bad**: {reason}
+- **Correct approach**: {how it should be done}
+- **Related decision**: {DEC-XXX if avoided by a decision, or blank}
+- **Occurrences**: {count}
+```
+
+#### decisions.md
+
+If an architectural decision was made, add:
+```markdown
+## [DEC-{XXX}] {Decision Title}
+- **Date**: {date}
+- **Status**: accepted
+- **Context**: {why this decision was needed}
+- **Decision**: {what was decided}
+- **Consequences**: {what follows}
+
+Related:
+- → derives: patterns.md#{pattern-name}
+- → avoids: anti-patterns.md#{anti-pattern-name}
+```
+
+#### wins.md
+
+If the task went well, add:
+```markdown
+## {date}: {feature}
+- **What was done**: {description}
+- **Why it worked**: {reasons}
+- **Time**: {actual} min (estimate: {estimate} min)
+- **Preserved**: {pattern/approach}
+```
+
+#### metrics.md
+
+Update metrics. Recalculate task type aggregates:
+```markdown
+## Overall
+- Total tasks completed: {N}
+- Average time per task: {N} min
+- Success rate: {N}%
+
+## Task Type Analysis
+| Type | Count | Avg Time | Anti-pattern Rate |
+|------|-------|----------|-------------------|
+| feature | {N} | {N}h | {N}% |
+| bug | {N} | {N}h | {N}% |
+| refactor | {N} | {N}h | {N}% |
+| other | {N} | {N}h | {N}% |
+```
+
+### Step 4b: Cross-link memory files
+
+After writing to decisions.md, check if the new decision implies any of the following:
+
+- **New pattern**: if the decision establishes a repeatable approach, ensure a corresponding entry exists in `patterns.md` (or update an existing one).
+- **New anti-pattern**: if the decision avoids or replaces a previous approach, ensure the old approach is recorded in `anti-patterns.md` with the correct approach pointing to the new decision.
+- **Orphan check**: scan the new decision's `→ derives` and `→ avoids` links — if any link target does not exist, create it or remove the broken link.
+
+### Step 5: Create retrospective report
+
+Create `docs/specs/{feature}/retrospective.md`:
+
+```markdown
+# Retrospective: {Feature}
+
+## Date
+{date}
+
+## Summary
+- Tasks completed: {N}
+- Time estimate: {estimate}
+- Time actual: {actual}
+- Win rate: {N}%
+
+## Wins
+{what worked well}
+
+## Struggles
+{what was difficult}
+
+## Lessons Learned
+{what to remember}
+
+## Action Items
+{what to do differently next time}
+```
+
+### Step 6: Update STATE.md (COMPLETE)
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: REFLECT
+- Feature: {feature}
+- Status: COMPLETE
+- Finished: {timestamp}
+```
+
+## Result
+
+- Retrospective report created
+- Memory files updated
+- `.planning/STATE.md` updated

package/templates/commands/frame:review.md

@@ -0,0 +1,174 @@
+# /frame:review -- Code Review + Automated Checks
+
+Compares code against spec.md, checks security, performance, edge cases, runs automated checks.
+
+## Instructions
+
+Execute a code review of the current feature.
+
+### Step 0: Update STATE.md (start)
+
+Update `.planning/STATE.md` before any work:
+```markdown
+## Current Position
+- Phase: REVIEW
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Find and read context
+
+- `find docs/specs -name "spec.md" | head -5`
+- `find docs/specs -name "plan.md" | head -5`
+- `find docs/specs -name "research.md" | head -5`
+- Read spec.md, plan.md and the **Memory Impact** section from research.md
+
+| File | Section | Why |
+|------|---------|-----|
+| `spec.md` | full file | requirements to verify against |
+| `plan.md` | full file | architecture and task Risk levels |
+| `research.md → Memory Impact` | Memory Impact section | context for decisions — avoid flagging intentional tradeoffs |
+| `.planning/memory/anti-patterns.md` | full file | verify code does not repeat known anti-patterns |
+| `.planning/memory/dependencies.md` | full file | verify no unauthorized dependencies added |
+
+### Step 2: Automated Checks
+
+Run all automated checks:
+```bash
+{quality.commands.typecheck}    # Type checking
+{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.
+
+### Step 3: Code Review Checklist
+
+#### Before the checklist: check Risk tasks
+
+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 are implemented
+- [ ] No extra features (scope creep)
+- [ ] Architecture matches plan.md
+
+#### Tests
+- [ ] Tests cover all cases from spec
+- [ ] Edge cases covered
+- [ ] Error cases covered
+- [ ] Tests in `__tests__/` directory (or project test convention)
+
+#### Security (OWASP)
+- [ ] Input validation
+- [ ] XSS prevention
+- [ ] CSRF protection
+- [ ] No sensitive data in logs
+- [ ] Secure credential handling (httpOnly, secure, SameSite cookies if applicable)
+
+#### Performance
+- [ ] No N+1 queries
+- [ ] Proper caching
+- [ ] No memory leaks
+- [ ] Bundle size acceptable
+
+#### Code Quality
+- [ ] No `any` type
+- [ ] No `@ts-ignore`
+- [ ] Proper error handling
+- [ ] Error reporting configured (Sentry or equivalent)
+- [ ] No `console.log` in production code
+- [ ] Follows project conventions
+
+#### i18n (if applicable)
+- [ ] All UI text uses translations
+- [ ] Default language set per project config
+- [ ] Keys follow dot.notation
+
+**Issue classification** — for each problem found:
+- **Critical**: must fix before Ship (blocks deploy)
+- **Warning**: should fix (recommended, does not block)
+- **Info**: consider fixing (optional)
+
+### Step 4: Create review report
+
+Create `docs/specs/{feature}/review.md`:
+
+```markdown
+# Review: {Feature}
+
+## Date
+{date}
+
+## Automated Checks
+- [x] Typecheck: PASS
+- [x] Tests: PASS
+- [x] Lint: PASS
+- [x] Build: PASS
+
+## Code Review
+
+### Spec Compliance
+{results}
+
+### Security
+{results}
+
+### Performance
+{results}
+
+### Code Quality
+{results}
+
+## Issues Found
+{list of issues, if any}
+
+## Recommendation
+{approve / request changes}
+
+## Action Items
+{specific items to fix}
+
+## Memory Updates
+- anti-patterns.md: {what to add if a problem was found}
+- patterns.md: {what was confirmed as a good pattern}
+- decisions.md: {if a decision was made to change approach}
+```
+
+### Step 5: Update STATE.md (final)
+
+**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.
+```
+
+## Result
+
+- All automated checks passed
+- Code review completed
+- Review report created with Memory Updates section
+- `.planning/STATE.md` updated

package/templates/commands/frame:rollback.md

@@ -0,0 +1,207 @@
+# /frame:rollback -- Rollback to Checkpoint
+
+Roll back to the last or a specific checkpoint with confirmation.
+
+## Instructions
+
+Command: **$ARGUMENTS**
+
+### Routing
+
+Determine action from arguments:
+- (empty) -- rollback to the last checkpoint
+- `--to <tag>` -- rollback to a specific checkpoint
+- `--soft` -- soft rollback (files stay in working tree)
+
+---
+
+## Action: Default (last checkpoint)
+
+### Step 0: Update STATE.md (IN_PROGRESS) + Fail-Fast Checks
+
+Update `.planning/STATE.md`:
+```markdown
+- Phase: ROLLBACK
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+Check for uncommitted changes:
+```bash
+git status --porcelain
+```
+
+If there are uncommitted changes → **STOP**:
+```
+❌ Rollback blocked: uncommitted changes detected.
+   Commit or stash your changes first:
+   git stash   (to save temporarily)
+   git checkout -- .   (to discard)
+```
+
+### Step 1: Find Last Checkpoint
+
+```bash
+LAST_CHECKPOINT=$(git tag -l "frame/checkpoint/*" --sort=-creatordate | head -n 1)
+```
+
+If no checkpoints exist, show "No checkpoints found" and exit.
+
+### Step 2: Show Diff
+
+```bash
+echo "=== Changes since checkpoint ==="
+git log --oneline $LAST_CHECKPOINT..HEAD
+echo ""
+echo "=== Files changed ==="
+git diff --stat $LAST_CHECKPOINT..HEAD
+```
+
+### Step 3: Confirmation
+
+```
++======================================================================+
+|                    ROLLBACK CONFIRMATION                              |
++======================================================================+
+|  Checkpoint: {tag}                                                   |
+|  Created: {date}                                                     |
+|                                                                      |
+|  Changes to be discarded:                                            |
+|  {list of commits}                                                   |
+|                                                                      |
+|  WARNING: This will discard {count} commits!                         |
+|                                                                      |
+|  Type "yes" to confirm rollback                                      |
++======================================================================+
+```
+
+**If the user does not confirm** -> abort, do nothing.
+
+### Step 4: Execute Rollback
+
+```bash
+git reset --hard $LAST_CHECKPOINT
+```
+
+### Step 5: Show Result + Update STATE.md (DONE)
+
+Update `.planning/STATE.md`:
+```markdown
+- Phase: {previous_phase}
+- Status: ROLLED_BACK
+- Checkpoint: {tag}
+```
+
+```
++======================================================================+
+|                    ROLLBACK COMPLETE                                  |
++======================================================================+
+|  Rolled back to: {tag}                                               |
+|  Discarded commits: {count}                                          |
+|                                                                      |
+|  Working directory is now at checkpoint state                        |
+|  Next: /frame:checkpoint list   (to see remaining checkpoints)       |
++======================================================================+
+```
+
+---
+
+## Action: --to <tag>
+
+Rollback to a specific checkpoint.
+
+### Step 0: Update STATE.md (IN_PROGRESS) + Fail-Fast Checks
+
+Same as Default action Step 0.
+
+### Step 1: Validate Tag
+
+```bash
+git tag -l "$TAG"
+```
+
+If tag is not found, show available checkpoints:
+```bash
+git tag -l "frame/checkpoint/*" --sort=-creatordate
+```
+
+### Step 2: Show Diff
+
+```bash
+echo "=== Changes since $TAG ==="
+git log --oneline $TAG..HEAD
+```
+
+### Step 3: Confirmation + Rollback
+
+(Same as Default, but with the specified tag)
+
+Update STATE.md (DONE) same as Default Step 5.
+
+---
+
+## Action: --soft
+
+Soft rollback: files reset to checkpoint state, but changes remain in the working tree.
+
+### Step 0: Update STATE.md (IN_PROGRESS)
+
+Update `.planning/STATE.md`:
+```markdown
+- Phase: ROLLBACK
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Find Checkpoint
+
+(Same as Default)
+
+### Step 2: Show Diff (what will be preserved)
+
+```bash
+echo "=== Changes that will be preserved in working tree ==="
+git diff --stat $LAST_CHECKPOINT..HEAD
+```
+
+### Step 3: Execute Soft Rollback
+
+```bash
+git reset --soft $LAST_CHECKPOINT
+```
+
+### Step 4: Show Result + Update STATE.md (DONE)
+
+Update `.planning/STATE.md`:
+```markdown
+- Phase: {previous_phase}
+- Status: SOFT_ROLLED_BACK
+- Checkpoint: {tag}
+```
+
+```
++======================================================================+
+|                    SOFT ROLLBACK COMPLETE                             |
++======================================================================+
+|  Rolled back to: {tag}                                               |
+|                                                                      |
+|  Files reset to checkpoint state                                     |
+|  Changes preserved in working directory                              |
+|                                                                      |
+|  Review changes: git diff                                            |
+|  Discard changes: git checkout -- .                                  |
+|  Next: /frame:checkpoint list   (to see remaining checkpoints)       |
++======================================================================+
+```
+
+## Rules
+
+- **Always require confirmation** -- never run `git reset --hard` without user approval
+- **Show diff** -- what will be lost
+- **Soft rollback** -- alternative for cautious rollback
+- **Check git status** -- verify no uncommitted changes before rollback
+
+## Result
+
+- Rollback executed (hard or soft)
+- User informed about lost changes