the-frame-ai 0.1.0

package/templates/hooks/session-init.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# session-init.sh - Loads context at session start
+
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+STATE_FILE="$PROJECT_ROOT/.planning/STATE.md"
+
+# Onboarding: STATE.md missing or not yet filled (only template headers)
+if [ ! -f "$STATE_FILE" ] || ! grep -q "^- Phase:" "$STATE_FILE" 2>/dev/null; then
+  echo "╔══════════════════════════════════════════╗"
+  echo "║         FRAME — Getting Started          ║"
+  echo "╚══════════════════════════════════════════╝"
+  echo ""
+  echo "  FRAME is installed but not yet initialized."
+  echo ""
+  echo "  Next step: run /frame:init"
+  echo "  This will scan your project and fill in"
+  echo "  MAP.md, CLAUDE.md, and STATE.md."
+  echo ""
+  exit 0
+fi
+
+LAST_ACTIVITY=0
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  LAST_ACTIVITY=$(stat -f %m "$STATE_FILE" 2>/dev/null || echo 0)
+else
+  LAST_ACTIVITY=$(stat -c %Y "$STATE_FILE" 2>/dev/null || echo 0)
+fi
+NOW=$(date +%s)
+ELAPSED=$(( NOW - LAST_ACTIVITY ))
+
+PHASE=$(grep "^- Phase:" "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*Phase: //')
+FEATURE=$(grep "^- Feature:" "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*Feature: //')
+TASK=$(grep "^- Task:" "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*Task: //')
+
+# < 2 hours: one-liner
+if [ "$ELAPSED" -lt 7200 ]; then
+  echo "FRAME | Phase: ${PHASE:-?} | Feature: ${FEATURE:-?} | Task: ${TASK:-?}"
+  exit 0
+fi
+
+# 2-24 hours: brief digest
+if [ "$ELAPSED" -lt 86400 ]; then
+  echo "╔══════════════════════════════════════════╗"
+  echo "║           FRAME — Welcome back           ║"
+  echo "╚══════════════════════════════════════════╝"
+  echo ""
+  echo "  Phase: ${PHASE:-?} | Feature: ${FEATURE:-?}"
+  echo "  Task:  ${TASK:-?}"
+  echo ""
+  echo "  Recent commits:"
+  git log --oneline -3 2>/dev/null | sed 's/^/    /'
+  echo ""
+  exit 0
+fi
+
+# > 24 hours: full context
+echo "╔══════════════════════════════════════════╗"
+echo "║        FRAME SESSION INITIALIZED         ║"
+echo "╚══════════════════════════════════════════╝"
+echo ""
+
+if [ -f "$STATE_FILE" ]; then
+  echo "Current State:"
+  head -15 "$STATE_FILE" | sed 's/^/  /'
+  echo ""
+fi
+
+MAP_FILE="$PROJECT_ROOT/.planning/MAP.md"
+if [ -f "$MAP_FILE" ]; then
+  echo "Project:"
+  grep "^## Quick Facts" -A 6 "$MAP_FILE" 2>/dev/null | head -7 | sed 's/^/  /'
+  echo ""
+fi
+
+echo "  Recent commits:"
+git log --oneline -5 2>/dev/null | sed 's/^/    /'
+echo ""
+echo "Commands: /frame:status, /frame:context, /frame:daily, /frame:fast"
+echo ""
+
+exit 0

package/templates/planning/pause-state.json

@@ -0,0 +1 @@
+{}

package/templates/project/CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+## Tech Stack
+
+(to be filled after /frame:init scan)
+
+## Architecture
+
+(to be filled after /frame:init scan)
+
+## Key Patterns
+
+(to be filled after /frame:init scan)
+
+## Code Conventions
+
+- **File naming**: (define your convention)
+- **Imports**: (define your import order)
+- **TypeScript**: Strict mode
+- **Git**: `{type}({scope}): {description}` — types: feat, fix, refactor, test, docs, chore
+- **Tests**: co-located or `__tests__/` directory
+
+## Rules (MUST follow)
+
+1. Always run quality checks before commit
+2. Use error reporting (not console.log)
+3. No `any` type — use `unknown` + type guard
+4. New features require tests
+
+## FRAME Framework
+
+This project uses FRAME (Framework for AI-Assisted Solo Development).
+
+**Commands**:
+- `/frame:init` — initialize project
+- `/frame:status` — current state
+- `/frame:fast <task>` — quick task
+- `/frame:research <topic>` — domain research
+- `/frame:plan <feature>` — plan feature
+- `/frame:build` — implement with TDD
+- `/frame:review` — code review
+- `/frame:ship` — git + PR
+- `/frame:debug <issue>` — systematic debugging
+- `/frame:retrospective` — retrospective + memory update
+- `/frame:cleanup-memory` — trim and archive memory files
+
+**Key files**:
+- `.planning/STATE.md` — current position
+- `.planning/MAP.md` — project map
+- `.planning/ROADMAP.md` — roadmap
+- `.frame/config.json` — FRAME configuration
+- `.planning/memory/` — project memory
+
+**Quality Gates** (D→P→D):
+- `{quality.commands.typecheck}` — Type check
+- `{quality.commands.test}` — Test check
+- `{quality.commands.lint}` — Lint check
+- `{quality.commands.build}` — Build check (before Ship)
+
+## Anti-Patterns (NEVER do)
+
+- ❌ Skip verification steps (D→P→D is mandatory)
+- ❌ `any` type (use `unknown` + type guard)

package/templates/project/CONTEXT.md

@@ -0,0 +1,16 @@
+# CONTEXT.md — Working Context
+
+## Active Feature
+- Name: (none yet)
+- Phase: SETUP
+
+## Key Files
+- .planning/STATE.md — current state
+- .planning/MAP.md — project map
+- .frame/config.json — FRAME configuration
+
+## Tech Context
+(to be filled by /frame:init)
+
+## Recent Changes
+- FRAME installed via the-frame CLI

package/templates/project/MAP.md

@@ -0,0 +1,35 @@
+# MAP.md -- {{PROJECT_NAME}}
+
+## Quick Facts
+- **Name**: {{PROJECT_NAME}}
+- **Type**: (filled by /frame:init)
+- **Stack**: (filled by /frame:init)
+- **Database**: (filled by /frame:init)
+- **Auth**: (filled by /frame:init)
+- **Deploy**: (filled by /frame:init)
+- **Tests**: (filled by /frame:init)
+
+## Architecture Pattern
+(filled by /frame:init)
+
+## Entry Points
+(filled by /frame:init)
+
+## Key Layers
+(filled by /frame:init)
+
+## Data Flow
+(filled by /frame:init)
+
+## Key Patterns
+| Pattern | Where Used |
+|---------|-----------|
+| (filled by /frame:init) |
+
+## File Inventory
+| Directory/File | Purpose |
+|----------------|---------|
+| (filled by /frame:init) |
+
+## Tech Debt / Notes
+(filled by /frame:init)

package/templates/project/ROADMAP.md

@@ -0,0 +1,12 @@
+# ROADMAP.md — {{PROJECT_NAME}}
+
+## v1.0 — Current
+- [ ] Core features
+- [ ] Testing
+- [ ] Documentation
+
+## v1.1 — Planned
+- (add planned features here)
+
+## v2.0 — Future
+- (add future vision here)

package/templates/project/STATE.md

@@ -0,0 +1,13 @@
+# STATE.md — Current Position
+
+## Current Position
+- Phase: SETUP
+- Feature: Framework initialization
+- Status: FRAME installed, awaiting /frame:init scan
+
+## Completed
+- [x] FRAME installed via the-frame CLI
+
+## Notes
+- Run /frame:init to scan your codebase and populate MAP.md
+- Run /frame:doctor to verify all systems

package/templates/project/config.json

@@ -0,0 +1,74 @@
+{
+  "version": "1.0",
+  "project": "{{PROJECT_NAME}}",
+
+  "_solo_comment": "=== SOLO SETTINGS — review and adjust these ===",
+
+  "quality": {
+    "commands": {
+      "typecheck": "npx tsc --noEmit",
+      "test": "npx vitest run",
+      "lint": "npx eslint .",
+      "build": "npm run build",
+      "audit": "npm audit",
+      "outdated": "npm outdated"
+    },
+    "typescript": "strict",
+    "eslint": true,
+    "tests": "required",
+    "build": "required"
+  },
+
+  "soloMode": {
+    "autoContextPruning": true,
+    "timeBoxing": { "defaultMinutes": 30 }
+  },
+
+  "devilsAdvocate": {
+    "enabled": true,
+    "categories": ["input", "error", "edge", "security", "performance"]
+  },
+
+  "_advanced_comment": "=== ADVANCED — safe to leave as-is ===",
+
+  "workflow": {
+    "tdd": true,
+    "autoCommit": false,
+    "checkpoints": true,
+    "autoCheckpoint": true,
+    "checkpointBefore": ["research", "plan", "build", "review"],
+    "maxCheckpoints": 10,
+    "cleanupAfterShip": true,
+    "pauseResume": true,
+    "worktrees": true
+  },
+
+  "phases": {
+    "research": { "type": "plan", "freshContext": true },
+    "plan": { "freshContext": true },
+    "build": { "type": "tdd" },
+    "review": { "freshContext": true },
+    "ship": {}
+  },
+
+  "memory": {
+    "autoUpdate": true,
+    "trigger": "per-task",
+    "maxPatterns": 50,
+    "maxAntiPatterns": 20,
+    "maxDecisions": 30,
+    "confidenceArchiveDays": 60,
+    "retrospectiveRequired": true
+  },
+
+  "checkDeps": {
+    "runBeforeShip": true,
+    "auditAgeDaysWarning": 7
+  },
+
+  "archive": {
+    "enabled": true,
+    "thresholdDays": 90,
+    "archivePath": "docs/specs/archive"
+  }
+}

package/templates/project/memory/anti-patterns.md

@@ -0,0 +1,14 @@
+{
+  "name": "Anti-Patterns",
+  "description": "Patterns to avoid in this project"
+}
+
+# Anti-Patterns
+
+<!-- Format for new entries:
+## Anti-pattern: {name}
+- **Why it is bad**: {reason}
+- **Correct approach**: {how it should be done}
+- **Related decision**: {DEC-XXX if avoided by a decision}
+- **Occurrences**: {count}
+-->

package/templates/project/memory/context.md

@@ -0,0 +1,23 @@
+{
+  "name": "Context",
+  "description": "Current project state — what's happening now, recent decisions, health"
+}
+
+# Project Context
+
+## Current Focus
+- Working on: {feature}
+- Status: {status}
+- Blocked by: {blockers or "none"}
+
+## Recent Decisions (last 2 weeks)
+- {decision with link to decisions.md if available}
+
+## Health
+- Last retrospective: {date}
+- Open anti-patterns: {count} {needs attention if > 2}
+- Stale patterns: {count}
+
+## Active Blockers
+- {blocker 1}
+- {blocker 2}

package/templates/project/memory/conventions.md

@@ -0,0 +1,19 @@
+# Conventions
+
+Code conventions and standards discovered during /frame:init scan.
+
+## File Naming
+
+(auto-filled by /frame:init)
+
+## Import Order
+
+(auto-filled by /frame:init)
+
+## Patterns
+
+(auto-filled by /frame:init)
+
+## Git Commit Format
+
+`{type}({scope}): {description}` — types: feat, fix, refactor, test, docs, chore

package/templates/project/memory/decisions.md

@@ -0,0 +1,20 @@
+{
+  "name": "Architecture Decisions",
+  "description": "Architecture Decision Records (ADRs)"
+}
+
+# Architecture Decisions
+
+<!-- Format for new entries:
+## [DEC-{XXX}] {Decision Title}
+- **Date**: {date}
+- **Status**: {accepted|deprecated|superseded by DEC-YYY}
+- **Context**: {why this decision was needed}
+- **Decision**: {what was decided}
+- **Consequences**: {what follows from this decision}
+
+Related:
+- → derives: patterns.md#{pattern-name}
+- → avoids: anti-patterns.md#{anti-pattern-name}
+- ← derived from: (if this supersedes another decision)
+-->

package/templates/project/memory/dependencies.md

@@ -0,0 +1,23 @@
+{
+  "name": "Dependencies",
+  "description": "External dependencies, tech stack, and things to avoid adding"
+}
+
+# Dependencies
+
+## Core
+- {runtime language + version}
+- {key framework}
+- {database driver}
+- {cache library}
+
+## Integrations
+- {service} -- {purpose}
+
+## Dev Tools
+- {testing framework}
+- {linter}
+- {build tool}
+
+## Avoid
+- {technology} -- {reason / what we use instead}

package/templates/project/memory/metrics.md

@@ -0,0 +1,22 @@
+{
+  "name": "Metrics",
+  "description": "Project baseline metrics and task type analysis"
+}
+
+# Metrics
+
+<!-- Updated automatically by /frame:retrospective -->
+
+## Overall
+- Total tasks completed: 0
+- Average time per task: 0 min
+- Success rate: 0%
+
+## Task Type Analysis
+
+| Type | Count | Avg Time | Anti-pattern Rate |
+|------|-------|----------|-------------------|
+| feature | 0 | 0h | 0% |
+| bug | 0 | 0h | 0% |
+| refactor | 0 | 0h | 0% |
+| other | 0 | 0h | 0% |

package/templates/project/memory/patterns.md

@@ -0,0 +1,30 @@
+{
+  "name": "Patterns",
+  "description": "Project-specific patterns discovered during development"
+}
+
+# Patterns
+
+<!-- Format for new entries:
+## {Pattern Name} [confidence: {high|medium|low}, confirmed: {N}x, added: {date}, last: {date}]
+- **Pattern**: {description}
+- **Where**: {where it is used}
+- **Convention**: {convention}
+- **From**: {DEC-XXX or blank if organic}
+- **Discovered**: {date}
+-->
+
+## Core
+
+<!-- Established patterns: confidence: high (5+ confirmed)
+     or confidence: medium with confirmed >= 3 and last within the last 90 days.
+     Planner reads only this section. -->
+
+## Active
+
+<!-- Working patterns: all patterns not in Core.
+     Marked [stale] if last > 90 days. -->
+
+## Archived
+
+<!-- Patterns with confidence: low, inactive for > 60 days. -->

package/templates/project/memory/wins.md

@@ -0,0 +1,11 @@
+# Wins
+
+Recorded successes and completed tasks.
+
+## Format
+
+`- {date}: {task} — {outcome}`
+
+## Log
+
+(populated by /frame:fast and /frame:build)

package/templates/project/settings.local.json

@@ -0,0 +1,50 @@
+{
+  "permissions": {
+    "allow": [
+      "npx tsc *",
+      "npx vitest *",
+      "npx eslint *",
+      "WebSearch",
+      "WebFetch"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/safety-net.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/git-safety.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/quality-gate.sh",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-init.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/project/specs/_template/PRD.md

@@ -0,0 +1,24 @@
+# PRD.md — Product Requirements Document
+
+## Overview
+- Feature: (name)
+- Problem: (what problem does this solve?)
+- Users: (who benefits?)
+
+## Requirements
+
+### Must Have
+- (requirement 1)
+- (requirement 2)
+
+### Nice to Have
+- (requirement 3)
+
+## Success Criteria
+- (how do we know it's done?)
+
+## Constraints
+- (technical or business constraints)
+
+## Out of Scope
+- (what we explicitly won't do)

package/templates/project/specs/_template/plan.md

@@ -0,0 +1,25 @@
+# plan.md — {{feature}}
+
+## Overview
+- Feature: {{feature}}
+- Tasks: 0/0
+- Status: PLANNING
+
+## Tasks
+
+### Task 1: (task name)
+- Files: `path/to/file`
+- Dependencies: NONE
+- Wave: 1
+- Complexity: low | medium | high
+- Risk: low | medium | high
+- Estimate: XS | S | M | L | XL
+- Test: (test file or "not needed")
+- Verification: {quality.commands.test} {quality.commands.typecheck}
+- Status: [ ] TODO
+
+<!-- Add more tasks as needed -->
+
+## Wave Map
+- Wave 1: Task 1
+- Wave 2: (tasks depending on Wave 1)

package/templates/project/specs/_template/spec.md

@@ -0,0 +1,27 @@
+# spec.md — {{feature}}
+
+## Overview
+- Feature: (name)
+- Status: DRAFT
+
+## Problem
+(what problem does this solve?)
+
+## Solution
+(how will we solve it?)
+
+## API / Interface
+(define endpoints, components, or interfaces)
+
+## Data Model
+(define data structures if applicable)
+
+## Edge Cases
+- (edge case 1)
+- (edge case 2)
+
+## Testing Strategy
+- (how will we test this?)
+
+## References
+- (links to research, docs, examples)

package/templates/project/specs/_template/subagent-prompt.md

@@ -0,0 +1,43 @@
+# Subagent Prompt Template
+
+## Memory (read before writing code)
+- `.planning/memory/anti-patterns.md` — what to avoid
+- `.planning/memory/conventions.md` — how to write code
+- `.planning/memory/dependencies.md` — stack + Avoid list
+- `docs/specs/{FEATURE}/research.md` → Memory Impact section
+
+## Heartbeat rules
+- After each D-step write: "✓ Task {name}: {step} confirmed"
+- Before a long command: "⏳ Running: {command}"
+- Do not execute more than 3 tools in a row without output
+
+## Context
+- Project: {{PROJECT_NAME}}
+- MAP: See .planning/MAP.md
+- Spec: See docs/specs/{FEATURE}/spec.md
+- Task: {task_description}
+
+## Your Role: Builder
+1. Write TEST first (RED)
+2. Verify: {quality.commands.test} {test_file}
+3. Write CODE (GREEN)
+4. Verify: {quality.commands.test} {test_file}
+5. Refactor if needed
+6. Verify types: {quality.commands.typecheck}
+7. Verify lint: {quality.commands.lint} {files}
+8. Git commit: `{type}({scope}): {description}`
+
+## Key Files
+- {file1} — {purpose}
+- {file2} — {purpose}
+
+## Patterns
+- Follow project conventions in CLAUDE.md
+- Use project-specific patterns from .planning/memory/
+
+## DO NOT
+- Do not modify files outside {scope_dir}
+- Do not skip tests
+- Do not use `any` type
+- Do not add dependencies without approval
+- Do not commit without passing quality gates