the-frame-ai 0.1.0

package/templates/commands/frame:ship.md

@@ -0,0 +1,148 @@
+# /frame:ship -- Git + PR
+
+Prepares a git commit, optionally pushes and creates a PR.
+
+## Instructions
+
+### Step 0: Fail-fast + 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 the project root."; exit 1; }
+```
+
+Update `.planning/STATE.md` before starting:
+```markdown
+## Current Position
+- Phase: SHIP
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+Read `.planning/STATE.md` and verify:
+- `Phase: REVIEW` ✓
+- `Status:` is `approve` OR `Shipped` OR contains `ready to ship` ✓ (not `request changes`)
+
+If conditions not met → **STOP**:
+```
+❌ Ship blocked. Review not completed or not approved.
+   Current status: {status}
+   Run /frame:review first.
+```
+
+Check `Deps Audit` in STATE.md:
+- If `Deps Status: CRITICAL` → **STOP**: fix critical vulnerabilities before shipping
+- If audit date is older than 7 days → warn: `⚠️ Deps audit is stale. Consider running /frame:check-deps`
+
+### Step 1: Quality gate
+
+```bash
+{quality.commands.typecheck} && {quality.commands.test}
+```
+
+If fails → **STOP**, do not commit broken code.
+
+### Step 2: Check git status
+
+```bash
+git status
+git diff --stat
+```
+
+**D-step**: Identify which files have changed.
+
+### Step 3: Select files for commit
+
+**NEVER use `git add -A` or `git add .`**
+
+Add only the relevant files:
+```bash
+git add path/to/file1.ts path/to/file2.tsx
+```
+
+### Step 4: Create commit
+
+Commit format: `{type}({scope}): {description}`
+
+Types:
+- `feat` -- new feature
+- `fix` -- bug fix
+- `refactor` -- refactoring
+- `test` -- tests
+- `docs` -- documentation
+- `chore` -- maintenance
+
+Examples:
+```bash
+git commit -m "feat(chat): add streaming support"
+git commit -m "fix(auth): handle expired token"
+git commit -m "refactor(api): extract proxy logic"
+```
+
+**D-step**: Commit is successful.
+
+### Step 5: Optional -- Push
+
+Ask the user:
+```
+Push to {branch}? (y/n)
+```
+
+If yes:
+```bash
+git push origin {branch}
+```
+
+### Step 6: Optional -- PR
+
+If a PR needs to be created:
+```bash
+gh pr create --title "{title}" --body "{description}"
+```
+
+### Step 6.5: Update memory files
+
+Update `.planning/context.md`:
+- `Current Focus` → remove the completed feature
+- `Recent Decisions` → add an entry about what was shipped
+
+If an architectural decision was made during ship (branch choice, PR strategy, rollback), add to `.planning/memory/decisions.md`:
+```markdown
+## [DEC-{XXX}] {Decision name}
+- **Date**: {date}
+- **Status**: accepted
+- **Context**: {why the decision was needed}
+- **Decision**: {what was decided}
+- **Consequences**: {what follows from this}
+```
+
+### Step 7: Update STATE.md
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: SHIP
+- Feature: {feature}
+- Commit: {hash}
+- Branch: {branch}
+- Tasks: {completed}/{total}
+- Review: approve / {N} warnings
+- Shipped: {timestamp}
+- Status: Shipped
+```
+
+## Rules
+
+- **Always specific files** -- never `git add -A`
+- **Descriptive commit messages** -- `{type}({scope}): {description}`
+- **One commit per task** -- atomic commits
+- **Check git status before commit** -- ensure no sensitive files are included
+- **Push only with confirmation** -- always ask before pushing
+
+## Result
+
+- Git commit created
+- Optionally: git push (with confirmation), PR created
+- `.planning/context.md` updated
+- `.planning/memory/decisions.md` updated (if architectural decision made)
+- `.planning/STATE.md` updated

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

@@ -0,0 +1,111 @@
+# /frame:sprint-check -- Sprint Planning Check
+
+Checks ROADMAP progress and velocity.
+
+## Instructions
+
+Check project progress.
+
+### Step 0: Fail-fast validation + Update STATE.md (IN_PROGRESS)
+
+**Before doing anything**, check:
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null || { echo "ERROR: Not a git repository. Run from project root."; exit 1; }
+```
+
+Check `.planning/ROADMAP.md` exists — if missing, STOP: "Run /frame:init first — ROADMAP.md not found."
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: SPRINT-CHECK
+- Status: IN_PROGRESS
+- Started: {timestamp}
+```
+
+### Step 1: Read ROADMAP
+
+```bash
+cat .planning/ROADMAP.md
+```
+
+### Step 2: Git Stats for last 2 weeks
+
+**Heartbeat**: report "Reading git history..." before running.
+
+```bash
+git log --since="2 weeks ago" --oneline | wc -l  # commits
+git log --since="2 weeks ago" --oneline | head -10  # recent
+```
+
+### Step 3: Read STATE.md and plan.md
+
+```bash
+cat .planning/STATE.md
+```
+
+Find the current plan.md and count completed tasks:
+```bash
+find docs/specs -name "plan.md" | head -1
+```
+Read plan.md and count:
+- `[DONE]` tasks — completed this sprint
+- `[ ]` tasks — remaining
+- `[BLOCKED]` tasks — blocked
+
+### Step 4: Identify blockers
+
+Check for:
+- Open tasks
+- Blocked tasks
+- Overdue items
+
+### Step 5: Create report and update velocity
+
+```bash
+mkdir -p .planning/reports/sprint
+```
+
+Create `.planning/reports/sprint/{date}.md`:
+
+```markdown
+# Sprint Check -- {date}
+
+## Progress
+- Commits last 2 weeks: N
+- Completed tasks (DONE): N
+- Remaining tasks: N
+- Blocked tasks: N
+
+## Velocity
+- Average: N tasks/week (based on [DONE] tasks in plan.md)
+
+## Blockers
+- {blocker 1}
+- {blocker 2}
+
+## Recommendations
+1. {recommendation}
+```
+
+Append velocity data to `.planning/memory/metrics.md` under `## Velocity`:
+```
+- {date}: {N} tasks/week, {N} commits/week
+```
+
+If a `## Velocity` section doesn't exist, create it.
+
+### Step 6: Update STATE.md (COMPLETE)
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: SPRINT-CHECK
+- Status: COMPLETE
+- Finished: {timestamp}
+```
+
+## Result
+
+- `.planning/reports/sprint/{date}.md` — sprint report created
+- `.planning/STATE.md` updated (COMPLETE)

package/templates/commands/frame:status.md

@@ -0,0 +1,103 @@
+# /frame:status -- Project Status
+
+> Full technical dump: STATE.md, ROADMAP, git, memory, blockers.
+> For daily orientation use `/frame:daily` instead.
+
+Shows current status: STATE.md, ROADMAP.md, CONTEXT.md, git status.
+
+## Instructions
+
+### Step 0: Fail-fast validation
+
+**Before any action** check:
+- `.planning/STATE.md` exists — if not, STOP: "Run /frame:init first — STATE.md not found."
+
+### Step 1: Read STATE.md
+
+Read `.planning/STATE.md` and capture:
+- Current phase
+- Current feature
+- Task progress
+- Latest commit
+- Blockers
+
+**D-step**: STATE.md read, data captured.
+
+### Step 2: Read ROADMAP.md
+
+Read `.planning/ROADMAP.md` (if exists) and capture:
+- Current milestone
+- Task progress
+- Upcoming plans
+
+Also grep for blocked tasks:
+```bash
+grep -i "BLOCKED" .planning/ROADMAP.md 2>/dev/null
+grep -i "BLOCKED" docs/specs/*/plan.md 2>/dev/null | head -10
+```
+
+**D-step**: ROADMAP.md read or noted as absent.
+
+### Step 3: Read CONTEXT.md
+
+Read `.planning/CONTEXT.md` (if exists) and capture:
+- Active feature
+- Key files
+- Tech context
+
+**D-step**: CONTEXT.md read or noted as absent.
+
+### Step 4: Git Status
+
+```bash
+git status
+git log --oneline -5
+```
+
+**Heartbeat**: "Git status retrieved, reading memory..."
+
+**D-step**: Git commands executed, output captured.
+
+### Step 5: Show Context (if available)
+
+Read `.planning/memory/context.md` and capture a brief summary of current focus and health.
+
+### Step 6: Show Memory (if available)
+
+Read `.planning/memory/patterns.md` and capture a brief summary with confidence levels.
+
+### Step 7: Output Format
+
+```
+============================================================
+                    FRAME STATUS
+============================================================
+
+  Phase:     {current phase}
+  Feature:   {current feature}
+  Tasks:     {completed}/{total}
+  Commit:    {hash}
+  Milestone: {milestone from ROADMAP or "—"}
+
+============================================================
+  BLOCKERS:
+  {list of BLOCKED tasks from plan.md and ROADMAP.md, or "none"}
+
+============================================================
+  MEMORY:
+  {brief summary from context.md or "—"}
+
+============================================================
+  GIT:
+  {git status --short}
+  {last 5 commits}
+
+============================================================
+```
+
+## Result
+
+- Current project status displayed
+- All key files read
+- Git status shown
+- Next step: `/frame:health` for technical checks or `/frame:research <topic>` for a new feature

package/templates/commands/frame:unstuck.md

@@ -0,0 +1,102 @@
+# /frame:unstuck -- Get Unblocked
+
+When you're stuck on a task, feature, or decision and don't know how to proceed.
+
+## Instructions
+
+### Step 1: Understand the block
+
+Ask if not provided: "What are you stuck on? Describe the problem in one sentence."
+
+Read:
+- `.planning/STATE.md` — current phase, feature, task
+- `.planning/memory/context.md` — active blockers
+- `.planning/memory/anti-patterns.md` — known traps
+
+```bash
+git log --oneline -5
+git diff --stat HEAD~3..HEAD 2>/dev/null | tail -5
+```
+
+### Step 2: Classify the block
+
+Determine which type:
+- **Technical** — don't know how to implement something
+- **Decision** — two+ valid approaches, can't choose
+- **Scope creep** — task grew beyond original estimate
+- **External** — waiting on something outside your control
+- **Motivation** — overwhelmed, lost context, don't know where to start
+
+### Step 3: Check memory for prior solutions
+
+```bash
+grep -i "{keywords from block}" .planning/memory/decisions.md 2>/dev/null | head -5
+grep -i "{keywords from block}" .planning/memory/anti-patterns.md 2>/dev/null | head -5
+grep -i "{keywords from block}" .planning/memory/patterns.md 2>/dev/null | head -5
+```
+
+### Step 4: Output 3 options
+
+Always give exactly 3 options, ordered from least to most disruptive:
+
+```
+╔══════════════════════════════════════════╗
+║  FRAME UNSTUCK                           ║
+╠══════════════════════════════════════════╣
+║  Block: {one-line description}           ║
+║  Type:  {Technical/Decision/Scope/...}   ║
+╠══════════════════════════════════════════╣
+║  Option 1 — Smallest step               ║
+║    {concrete action, < 30 min}           ║
+║    → {command to run}                    ║
+╠══════════════════════════════════════════╣
+║  Option 2 — Reframe                     ║
+║    {different angle or scope reduction}  ║
+║    → {command to run}                    ║
+╠══════════════════════════════════════════╣
+║  Option 3 — Reset                       ║
+║    {rollback / simplify / skip for now}  ║
+║    → {command to run}                    ║
+╚══════════════════════════════════════════╝
+```
+
+Option templates by block type:
+
+**Technical:**
+1. Find a working example in the codebase → `/frame:why`
+2. Spike a minimal proof-of-concept → `/frame:fast`
+3. Simplify the requirement → `/frame:plan`
+
+**Decision:**
+1. Pick the option with fewer dependencies and proceed
+2. Run devil's advocate on both options → use `@devils-advocate` agent
+3. Time-box 30 min on option A, then decide → `/frame:fast`
+
+**Scope creep:**
+1. Cut to the original requirement, defer extras → `/frame:add-task`
+2. Re-estimate and update plan → `/frame:estimate`
+3. Checkpoint and start fresh sub-task → `/frame:checkpoint` then `/frame:fast`
+
+**External:**
+1. Document the blocker and work on something else → `/frame:note anti: waiting on {X}`
+2. Mock/stub the external dependency → `/frame:fast`
+3. Escalate or find a workaround
+
+**Motivation:**
+1. Run `/frame:daily` to rebuild context
+2. Pick the smallest open task → `/frame:fast`
+3. Take a break, set a 25-min timer, come back to `/frame:build`
+
+### Step 5: Save blocker to context
+
+Append to `.planning/memory/context.md` under `## Active Blockers`:
+```
+- {date}: {block description} — {chosen option}
+```
+
+## Rules
+
+- Always give exactly 3 options
+- Options must be concrete — no vague advice
+- Option 1 must be actionable in < 30 min
+- No code changes