the-frame-ai 0.1.0

package/templates/commands/frame:init.md

@@ -0,0 +1,231 @@
+# /frame:init -- Project Initialization
+
+> **This is a slash command** — run it inside Claude Code after `npx the-frame init` has already installed the framework.
+> It scans your codebase and fills MAP.md, CLAUDE.md, and CONTEXT.md.
+> Not to be confused with `the-frame init` (the CLI installer).
+
+Scans the project and fills MAP.md, CLAUDE.md, and CONTEXT.md with a complete project map.
+
+## Instructions
+
+### Step 0: Auto-detect Stack
+
+Identify the project type by checking for these files:
+- `package.json` → Node.js/JS/TS (check framework: Next.js, Express, NestJS, Vue, Svelte, React)
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- `requirements.txt` / `pyproject.toml` / `setup.py` → Python
+- `pom.xml` / `build.gradle` → Java/Kotlin
+- `composer.json` → PHP
+- `*.csproj` / `*.sln` → .NET/C#
+
+Run: `ls -la` and `cat README.md 2>/dev/null | head -30`
+
+Record: **stack**, **language**, **framework**, **project type** (web/api/cli/library/mobile).
+
+### Step 1: Surface Scan
+
+Read the project config files (those that exist):
+- `package.json` / `go.mod` / `Cargo.toml` / `pyproject.toml` — dependencies, versions
+- `tsconfig.json` / `jsconfig.json` — compiler settings
+- `.env.example` / `.env` — environment variables
+- `Dockerfile` / `docker-compose.yml` — deployment
+- `README.md` — project description
+
+### Step 2: Structure Scan
+
+Adapt commands to the detected stack:
+
+**For JS/TS projects:**
+```
+find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) \
+  -not -path "*/node_modules/*" -not -path "*/.next/*" | head -60
+ls -la src/ 2>/dev/null || ls -la app/ 2>/dev/null || true
+```
+
+**For Go:**
+```
+find . -name "*.go" -not -path "*/vendor/*" | head -60
+```
+
+**For Python:**
+```
+find . -name "*.py" -not -path "*/__pycache__/*" -not -path "*/venv/*" | head -60
+```
+
+**For Rust:**
+```
+find . -name "*.rs" -not -path "*/target/*" | head -60
+```
+
+**For any stack:**
+```
+find . -type d -not -path "*/node_modules/*" -not -path "*/.git/*" \
+  -not -path "*/target/*" -not -path "*/__pycache__/*" | head -40
+```
+
+### Step 3: Patterns Scan
+
+Look for patterns relevant to the detected stack:
+
+**Auth/sessions:**
+```
+grep -r "auth\|session\|token\|login\|jwt\|oauth" . \
+  --include="*.ts" --include="*.go" --include="*.py" --include="*.rs" \
+  -l 2>/dev/null | head -10
+```
+
+**Entry points:**
+```
+find . -name "main.*" -o -name "index.*" -o -name "app.*" -o -name "server.*" \
+  | grep -v node_modules | grep -v ".next" | head -15
+```
+
+**HTTP/API routes:**
+```
+grep -r "router\|route\|handler\|endpoint\|@Get\|@Post\|app\.get\|app\.post" . \
+  --include="*.ts" --include="*.go" --include="*.py" -l 2>/dev/null | head -10
+```
+
+**Tests:**
+```
+find . -name "*_test.*" -o -name "*.test.*" -o -name "*.spec.*" \
+  | grep -v node_modules | head -15
+```
+
+### Step 4: Dependencies Scan
+
+Determine inter-module dependencies:
+
+```
+grep -r "^import\|^from\|^require\|^use " . \
+  --include="*.ts" --include="*.go" --include="*.py" --include="*.rs" \
+  -h 2>/dev/null | sort | uniq -c | sort -rn | head -30
+```
+
+Check for: database, cache, queues, external APIs.
+
+### Step 5: Dynamics Scan
+
+Determine data flow and async patterns:
+
+```
+grep -r "async\|await\|goroutine\|channel\|Promise\|Observable\|WebSocket\|EventSource" . \
+  --include="*.ts" --include="*.go" --include="*.py" --include="*.rs" \
+  -l 2>/dev/null | head -10
+```
+
+### Step 6: Fill MAP.md
+
+Write results to `.planning/MAP.md`:
+
+```markdown
+# Project Map -- {Project Name}
+
+## Quick Facts
+- **Name**: {name}
+- **Type**: {web-app / api / cli / library / mobile}
+- **Stack**: {language + framework + key dependencies}
+- **Database**: {type and ORM/driver, if any}
+- **Auth**: {auth type, if any}
+- **Deploy**: {Docker / Vercel / Railway / bare metal / etc.}
+- **Tests**: {testing framework}
+
+## Architecture Pattern
+{Description: MVC / Clean Architecture / Layered / Monolith / Microservices / etc.}
+
+## Entry Points
+{Main startup files, entrypoints, main functions}
+
+## Key Layers
+{Description of project layers — adapt to real structure, not a template}
+
+## Data Flow
+{How data moves: request → processing → response / storage}
+
+## Key Patterns
+| Pattern | Where Used |
+|---------|-----------|
+| {real patterns from code} |
+
+## File Inventory
+| Directory/File | Purpose |
+|----------------|---------|
+| {real project structure} |
+
+## Tech Debt / Notes
+{Anything notable spotted during scanning}
+```
+
+### Step 7: Update CLAUDE.md
+
+Fill in the placeholders in `CLAUDE.md` — this is the main file Claude reads on every run:
+
+- **Tech Stack** — specific stack from step 0
+- **Architecture** — brief description from step 6
+- **Key Patterns** — 3-5 patterns from the code
+
+### Step 8: Update CONTEXT.md
+
+Fill in the `## Technical Context` section in `.planning/CONTEXT.md`:
+- Project type and stack
+- Main entry points
+- Key dependencies
+
+### Step 9: Update STATE.md
+
+Update `.planning/STATE.md`:
+```markdown
+## Current Position
+- Phase: SETUP
+- Status: MAP.md filled, project ready to work
+```
+
+### Step 10: Fill memory from scan results
+
+Using data already gathered in steps 1-5, fill two memory files:
+
+**`.planning/memory/conventions.md`** — add what was detected:
+- File naming pattern (kebab-case, camelCase, etc.)
+- Import style (named vs default, path aliases)
+- Git commit format (if `.gitmessage` or recent commits reveal a pattern)
+
+**`.planning/memory/dependencies.md`** — add:
+- Core dependencies (from package.json / go.mod / etc.)
+- Dev tools (test runner, linter, bundler)
+- Any "avoid" patterns spotted (e.g., deprecated packages)
+
+Only fill what was actually found — no placeholders.
+
+### Step 11: Output completion checklist
+
+```
+╔══════════════════════════════════════════╗
+║  FRAME INIT — Complete                   ║
+╠══════════════════════════════════════════╣
+║  Filled:                                 ║
+║    ✓ MAP.md — project map                ║
+║    ✓ CLAUDE.md — stack + architecture    ║
+║    ✓ CONTEXT.md — technical context      ║
+║    ✓ STATE.md — phase set to SETUP       ║
+║    ✓ memory/conventions.md               ║
+║    ✓ memory/dependencies.md              ║
+╠══════════════════════════════════════════╣
+║  Review these files and correct anything ║
+║  that looks wrong before proceeding.     ║
+╠══════════════════════════════════════════╣
+║  Next step:                              ║
+║    /frame:research — start a feature     ║
+║    /frame:fast     — quick task < 30min  ║
+║    /frame:doctor   — verify installation ║
+╚══════════════════════════════════════════╝
+```
+
+## Result
+
+- `.planning/MAP.md` — complete project map
+- `CLAUDE.md` — stack and architecture sections filled
+- `.planning/CONTEXT.md` — technical context filled
+- `.planning/STATE.md` — status updated
+- `.planning/memory/conventions.md` — conventions from scan
+- `.planning/memory/dependencies.md` — dependencies from scan

package/templates/commands/frame:migrate.md

@@ -0,0 +1,107 @@
+# /frame:migrate -- Migration with Rollback Plan
+
+Executes a migration with a plan and rollback strategy.
+
+## Instructions
+
+Execute the migration: **$ARGUMENTS**
+
+### Step 1: Determine Migration Type
+
+Identify the type from the argument:
+- `db` — database migration (irreversible, requires a `down` script)
+- `api` — API/interface changes
+- `deps` — dependency updates
+- `code` — code refactor/move (default)
+
+### Step 2: Analysis
+
+Identify:
+- Source: what is being migrated (from)
+- Target: where it is being migrated (to)
+- Scope: which files are affected (`grep -r "{area}" --include="*.ts" | head -20`)
+- Risks: what could break
+
+### Step 3: Create Migration Plan
+
+Create `docs/specs/migrations/{feature}/plan.md`:
+
+```markdown
+# Migration Plan: {from} -> {to}
+
+## Type
+{db | api | deps | code}
+
+## Overview
+{What is being migrated and why}
+
+## Steps
+### Step 1: {description}
+- Files: {files}
+- Command: {command}
+- Verify: {verification}
+
+### Step 2: {description}
+- Files: {files}
+- Command: {command}
+- Verify: {verification}
+
+## Rollback Plan
+### Rollback Step 1
+- Description: {what to revert}
+- Command: {command}
+
+## Risks
+- {risk 1}: {mitigation}
+```
+
+### Step 4: Create Checkpoint
+
+```
+/frame:checkpoint create pre-migration-{feature}
+```
+
+### Step 5: Execute Migration
+
+Execute step by step, verifying after each step:
+
+```
+1. Apply changes
+2. /frame:health  (quality gates)
+3. If OK -> continue
+4. If FAIL -> /frame:rollback
+```
+
+**For `db` type**: ensure a `down` script exists before running `up`.
+
+### Step 6: Git Commit
+
+```bash
+git add {files}
+git commit -m "refactor(migration): migrate {from} to {to}"
+```
+
+### Step 7: Update STATE.md
+
+```markdown
+## Current Position
+- Phase: MIGRATE
+- Feature: {area}
+- Status: Migration complete — {from} -> {to}
+```
+
+## Rules
+
+- **Checkpoint before migration** — via `/frame:checkpoint`, not manually
+- **Rollback via `/frame:rollback`** — not manually
+- **Quality gates via `/frame:health`** — no hardcoded commands
+- **Step by step** — not everything at once
+- **For `db` migrations** — `down` script is mandatory
+
+## Result
+
+- Migration executed
+- Plan saved to `docs/specs/migrations/{feature}/plan.md`
+- Quality gates passed
+- STATE.md updated
+- Git commit created

package/templates/commands/frame:note.md

@@ -0,0 +1,32 @@
+# /frame:note -- Quick Memory Note
+
+Add a quick note to memory without a full retrospective.
+
+## Instructions
+
+Input: **$ARGUMENTS**
+
+### Step 1: Route by prefix
+
+- Starts with `pattern:` → append to `.planning/memory/patterns.md` under `## Active`
+- Starts with `decision:` → append to `.planning/memory/decisions.md`
+- Starts with `anti:` → append to `.planning/memory/anti-patterns.md`
+- No prefix → append to `.planning/memory/context.md`
+
+Strip the prefix before saving.
+
+### Step 2: Append
+
+Format: `- {date}: {text}`
+
+Append to the appropriate file. Do not rewrite the file — append only.
+
+### Step 3: Confirm
+
+Output one line: `Noted in {filename}: "{text}"`
+
+## Rules
+
+- No research, no plan, no commit
+- Append only — never overwrite existing content
+- Date format: YYYY-MM-DD

package/templates/commands/frame:pause.md

@@ -0,0 +1,145 @@
+# /frame:pause -- Save State
+
+Saves current state and pauses work.
+
+## Instructions
+
+Save the current state: **$ARGUMENTS**
+
+### 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; }
+```
+
+Immediately update status in `.planning/STATE.md`:
+```
+Status: IN_PROGRESS (pausing)
+```
+
+Capture the last commit hash BEFORE any changes:
+```bash
+git rev-parse HEAD 2>/dev/null || echo "no-commits"
+```
+Store in `lastCommit`.
+
+### Step 1: Read current STATE.md
+
+Read `.planning/STATE.md` to understand the current phase, feature, and tasks:
+```bash
+cat .planning/STATE.md
+```
+
+Extract: current phase, feature, list of open (incomplete) tasks.
+
+### Step 2: Save uncommitted changes
+
+Check for changes:
+```bash
+git status --short
+```
+
+If there are changes — offer two options:
+- **WIP commit** (recommended): `git commit -m "WIP: pause — $ARGUMENTS"`
+- **Stash** (if commit is undesirable): `git stash push -m "FRAME pause: $ARGUMENTS"`
+
+Record in `hasStash`/`hasWip` accordingly.
+
+### Step 3: Update STATE.md
+
+Update (do not overwrite) `.planning/STATE.md`, refreshing the status section:
+```markdown
+## Current Position
+- Phase: {current phase}
+- Feature: {current feature}
+- Task: {completed}/{total}
+- Status: PAUSED
+- Paused at: {timestamp}
+- Notes: {$ARGUMENTS}
+```
+
+### Step 4: Create pause-state.json
+
+Create `.planning/pause-state.json`:
+
+```json
+{
+  "timestamp": "{ISO timestamp}",
+  "phase": "{current phase}",
+  "feature": "{current feature}",
+  "task": "{completed}/{total}",
+  "lastCommit": "{hash}",
+  "notes": "{$ARGUMENTS}",
+  "hasStash": true/false,
+  "hasWip": true/false,
+  "stashMessage": "{stash or WIP commit message}",
+  "openTasks": ["{open task 1}", "{open task 2}"],
+  "resumeHint": "{specific next step — file, function, or task}"
+}
+```
+
+### Step 5: Git Tag + Checkpoint
+
+Create a checkpoint before pause:
+```bash
+TIMESTAMP=$(date +%Y%m%d%H%M)
+git tag "frame/pause-$TIMESTAMP" -m "FRAME pause: $ARGUMENTS"
+```
+
+If autoCheckpoint is enabled, also create a phase checkpoint:
+```bash
+PHASE=$(grep -oE 'Phase: .+' .planning/STATE.md 2>/dev/null | head -1 | sed 's/Phase: //' || echo "unknown")
+if echo "research plan build review" | grep -q "$PHASE"; then
+  git tag "frame/checkpoint/$PHASE-$TIMESTAMP-pause" -m "Auto checkpoint before pause ($PHASE phase)"
+fi
+```
+
+### Step 6: Save Context
+
+Create `.planning/pause-history/{date}.md`:
+
+```markdown
+# Pause: {date}
+
+## State
+- Phase: {phase}
+- Feature: {feature}
+- Task: {completed}/{total}
+
+## What was done
+{what was completed}
+
+## Open tasks
+- [ ] {open task 1}
+- [ ] {open task 2}
+
+## What's next
+{resumeHint — specific next step}
+
+## Notes
+{$ARGUMENTS}
+```
+
+## Output
+
+```
++======================================================================+
+|                    FRAME PAUSED                                      |
++======================================================================+
+|  State saved at: {timestamp}                                         |
+|  Phase: {phase}                                                      |
+|  Feature: {feature}                                                  |
+|  Task: {completed}/{total}                                           |
+|                                                                      |
+|  Resume with: /frame:resume                                          |
++======================================================================+
+```
+
+## Result
+
+- State read and updated (not overwritten)
+- Changes saved (WIP commit or stash)
+- Git tag created
+- Open tasks and resumeHint recorded
+- Pause history saved