Open source · MIT · npm

THE FRAME

THE FRAME is an open-source, MIT-licensed npm framework that gives a solo developer a repeatable six-phase workflow for building software with Claude Code: research, plan, build, review, ship, reflect. It keeps project memory between sessions, runs tests and quality gates for you, and can fly the whole pipeline unattended. I use it to build every product I ship.

npm ↗GitHub ↗

install

# in any git repository
npx the-frame-ai init

# then, inside Claude Code
/frame:init     # scan codebase, fill MAP.md
/frame:daily    # your entry point every day

The cycle

How does THE FRAME work?

Each session is one pass through six phases. You make the decisions in Research; everything after that is a pipeline.

01
Research
/frame:research
Clarifying questions, codebase and web scouting, dependency passports, a devil's-advocate stress test. Ends in research.md with requirements and acceptance criteria.
02
Plan
/frame:plan
Atomic, code-grounded tasks grouped into waves, each labelled Parallel: yes/no and traced back to a requirement.
03
Build
/frame:build
TDD implementation. Independent wave tasks run concurrently; a second feature is routed into its own git worktree automatically.
04
Review
/frame:review
Automated gates plus a 6-panel review: spec compliance, security, performance, business logic, tests, conventions. FAIL findings are verified adversarially.
05
Ship
/frame:ship
Commit, optional push and PR, project memory updated. Checkpoints and rollback if anything goes sideways.
06
Reflect
/frame:retrospective
Learnings and patterns land in memory files. High-confidence ones get promoted into permanent project rules.

Autopilot

Decide once. Then it flies.

/frame:auto <feature> chains plan → build → review → fix → ship and asks nothing. Review findings are fixed in-flight to the right architectural solution, not a workaround.

It halts only for a product decision (a business rule, a policy, scope), a wave failure, a deviation from the plan, or five review rounds without approval. It never pushes and never opens a PR on its own.

Run it in several worktrees at once, then one /frame:integrate and one /frame:ship.

Why I work this way: Why I build alone with an AI pair.

example · google oauth

/frame:research "Google OAuth"
→ 2–3 clarifying questions, then codebase + web scouting
→ research.md: R1…Rn requirements, AC1…ACn acceptance criteria

/frame:auto "Google OAuth"
→ plan: Wave 1 (parallel) credentials, callback route
        Wave 2 (sequential) sessions
        Wave 3 (parallel) UI button, integration tests
→ build: TDD, gates green after every task
→ review: 6-panel, FAIL findings verified adversarially
→ fix: findings closed file-by-file
→ ship: local commit, memory updated

# halts only on a product decision

Under the hood

What is under the hood?

Project memory

STATE.md, MAP.md, ROADMAP.md and a memory/ folder. Every session starts with a context dump, so nothing is lost between days.

TDD by default

The builder agent writes the test first, runs typecheck, lint and tests as quality gates, and commits only when they are green.

10 specialised agents

Researcher, Planner, Builder, Reviewer, Auditor, Devil's Advocate, Security, Performance Auditor, Tests Reviewer, Conventions Reviewer.

5 safety hooks

Block rm -rf, DROP TABLE, force push and reset --hard. Block commits while the quality gate is red. Save state before context compaction.

12-category audit

Security, performance, logic, API, data, observability, deps, tests, infra, maintainability, a11y, privacy. Critical findings are challenged by a devil's advocate before they reach you.

Parallel features

Each feature in its own worktree with a task board. /frame:integrate merges them back with per-merge gates and a cross-feature review.

Parallel fixes

/frame:fix closes review findings file-by-file, one fixer per group, a single gates run at the end.

UI verification

/frame:verify-ui opens the app through Playwright MCP, screenshots it and compares against the task. Runs automatically when a task touches UI files.

Stack detection

init reads go.mod, Cargo.toml, Package.swift, pyproject.toml or package.json and fills the quality commands for TypeScript, Python, Go, Rust, Swift or Xcode projects.

Commands

Seven cover 90% of the work.

`/frame:daily`	Start here after any break: what was done, what is next
`/frame:research <topic>`	Before planning a new feature
`/frame:plan <feature>`	Turn research into tasks with waves
`/frame:build`	Implement with TDD, sequential or parallel automatically
`/frame:review`	6-panel review plus automated checks
`/frame:ship`	Commit, optional push and PR, update memory
`/frame:auto <feature>`	Plan → build → review → fix → ship, unattended

All 33 commands

`/frame:fast <task>`	Quick task under 30 minutes
`/frame:debug <issue>`	Git archaeology, 3 ranked hypotheses; --deep for parallel investigators
`/frame:fix`	Close review findings in parallel
`/frame:audit [category]`	Full or targeted audit with adversarial verification
`/frame:parallel`	Start, board, stop features in worktrees
`/frame:integrate`	Merge parallel features with gates
`/frame:checkpoint`	Create, list, rollback git checkpoints
`/frame:verify-ui`	Browser check via Playwright MCP
`/frame:refactor`	Refactor with a test safety net
`/frame:migrate`	DB / API / deps migration with rollback plan
`/frame:why`	Search decision history, explain why code looks the way it does
`/frame:unstuck`	Three concrete options to unblock
`/frame:health`	Tests, lint, types, scan freshness; sprint velocity
`/frame:test-plan`	Manual acceptance checklist before ship
`/frame:evolve`	Promote learnings into permanent rules
`/frame:pause / resume`	Save and restore mid-task state

Full reference on npm ↗

After install

Lives in your repo.

Commands, agents and hooks go into .claude/; state, roadmap, memory and reports into .planning/. Updates never overwrite your project files.

Requires Node.js 18+, Git and Claude Code. Quality commands are detected from your stack: TypeScript, JavaScript, Python, Go, Rust, Swift, Xcode.

project structure

.claude/
  commands/     # 33 FRAME commands
  agents/       # 10 AI agents
  hooks/        # 5 safety hooks
.frame/
  config.json   # quality commands, settings
.planning/
  STATE.md      # current position
  MAP.md        # project map
  ROADMAP.md
  BOARD.md      # parallel task board
  memory/       # context, conventions, learnings
  specs/
  reports/audit/

Get started

Build like a team. Stay one person.

npx the-frame-ai initnpm ↗Source on GitHub ↗

MIT licensed. Questions and ideas: andrey@chmerev.com