Phasestep

v0.7.6 · agentic delivery

Phase-driven
agentic workflow.

A phase-driven workflow for AI-assisted development. You keep product intent in the repo, your agent builds one step at a time. You accept a short behavior contract, verify it, audit the phase — then ship.

Ready for

Plan

Build

Audit

Ship

01 · Core loop · Agent executes · Owner gates

Delivery as a pipeline.

Not a checklist — a continuous flow. Agent nodes run the work. Highlighted nodes are Owner gates. Reject / fail routes back through refine.

Start /setup Product · flow · stack · architecture · design · build plan

Plan /plan-phase Break phase into verifiable steps

Build /build-phase One step + short behavior contract

Owner gate Intent Accept the contract · or reject → refine

Owner gate /verify-phase Prove it works · fail → refine → re-verify

Next step Loop Repeat until the phase is done

Phase close /audit-phase Read-only quality pass across the phase

Optional Evidence Web: Playwright · Native: device UAT · Backend: build/tests

Done /complete-phase Mark the phase complete

Optional /pr-step Owner-gated commit → PR → merge via GitHub

End Ship Verified work leaves the loop — merged, released, or live

Agent node Owner gate

02 · Behavior delta · What you review after each build

A short contract — not a code dump.

After each /build-phase, the agent writes a Behavior delta: the product behavior that changed, as SHALL statements you can observe. You Accept or Reject that contract (the intent gate) before deep code review or /verify-phase. Reject sends the agent to refine — not to the next step.

ADDED New SHALLs — behavior the product must now do

CHANGED Updated SHALLs — same feature, different outcome than before

REMOVED Behavior that must no longer happen (regression check)

WHEN Trigger or condition you can perform or observe

THEN Expected outcome — what verify will assert

AND Optional extra outcomes (errors, persistence, edge cases)

Example — Behavior delta after building “sign up email validation”

ADDED The system SHALL reject malformed email addresses before creating an account. Scenario: invalid email blocked WHEN the user submits sign-up with "not-an-email" THEN the form shows invalid_email AND no user record is created

CHANGED The system SHALL keep sessions for 30 days when “Remember me” is checked (was: 24 hours for all sessions) Scenario: remember-me duration WHEN the user signs in with Remember me enabled THEN the session remains valid for 30 days

REMOVED The system no longer accepts disposable email domains. Scenario: disposable blocked WHEN the user submits an address on mailinator.com THEN sign-up is rejected with disposable_email

03 · FAQ · Straight answers

Is this another planning chat mode?

No. Phasestep is a delivery pipeline with written specs, an intent gate after each build, Owner verification, and phase audits. Plans and progress live in the repo.

Which agents does it support?

Cursor, Claude Code, and Codex. npx phasestep init installs the matching command files (or all three). The workflow is the same across agents.

What does npx phasestep init actually install?

Slash commands, a constitution seed, and starter project docs (product, build plan, progress). It does not rewrite your app. Your product code stays yours until the agent builds a step you asked for.

Can I use it on an existing project?

Yes. /setup mid-project mode documents what exists and plans remaining work. It does not reinvent the app.

What if I already have other slash commands?

init does not delete them. Choose Sole in /setup to archive competing delivery loops (Owner Accept), or Alongside to keep both.

What is a Behavior delta?

A short post-build contract: ADDED / CHANGED / REMOVED SHALL statements, each with WHEN/THEN scenarios. You Accept or Reject it before deep code review or verify.

Who decides product behavior?

You — the Owner. The agent drafts and stops at numbered gates. Intent and verify never auto-pass.

Does the agent auto-commit or merge?

No. Commit, push, PR, and merge only happen when you Accept gates in optional /pr-step. Without that, work stays local.

Do I have to use GitHub automation?

No. Connect and /pr-step are optional. Skip and keep shipping locally.

Does it only work for web apps?

No. Stack-agnostic — web, mobile, and backend. Evidence differs by surface: Playwright for web UI, device UAT for native, build/tests for backend.

Do I need Playwright?

Only if you want optional browser evidence for web UI. Owner verification is always the gate. You can decline Playwright and continue with manual UAT.

How do I upgrade after a new release?

Run npx phasestep upgrade. It refreshes commands and catalogs while keeping your product docs, phase plans, and progress.

Is it free to use?

Yes. Phasestep is open source under the MIT License — use, modify, and ship it in commercial projects. You still pay for whatever AI agent / model you already use.