PhaseOps

A modular, ecosystem-agnostic framework for agentic software development. Phase-based workflows, human checkpoints, and resumable execution for AI-assisted work on any tech stack.

Part of the agentxworks ecosystem.

Start here

Pick whichever sounds most like you. Each guide gets you set up and hands off to the same walkthrough at the end.

Already know what you want? Go straight to Getting Started.

What is PhaseOps?

AI coding assistants are powerful, but they run loose: long chats, lost context, no audit trail, no consistent process. PhaseOps adds the structure that's missing, without taking the wheel away from you.

• Phase-based workflows. Work moves through named stages (ideate, plan, implement, verify, close), and each one is defined as a contract in markdown.
• Human checkpoints. Every important transition stops and waits for your approval. The AI proposes, you decide.
• Resumable state. Progress lives in files (.phaseops/state/active.json), so a brand-new session picks up exactly where the last one left off.
• Adapters. Stack-specific rules, skills, and tools (WordPress, Node.js, React, Next.js, Astro, Python, and LangChain come bundled) that switch on only in the projects that opt into them.
• A read-only MCP server. Your AI tool (Claude Code, for example) gets 27 core tools, plus any adapter tools, for reading workflows, rules, state, and planning docs. The server never edits files and never runs commands. Its only writes are two append-only logs.

How it works

PhaseOps runs your idea through the same path a good team would. It doesn't jump straight into code.

1. Ideate. You bring an idea, and the agent works to understand it (is this a new product, a feature, a refactor?) instead of guessing and coding.
2. Research and findings. For anything that touches existing code, the agent reads the codebase and reports back what it found.
3. Decisions. You and the agent settle the open questions together, and those decisions get written down and locked.
4. Roadmap. From the locked decisions, a roadmap is generated. You approve it. No clever prompt required.
5. Phases. Each roadmap item runs the loop initiate, implement, verify, close, and the agent asks "next is initiate phase X, shall we start?" at each step.
6. Loop back. If verify fails, a decision turns out to be wrong, or the context drifts, the flow routes backward to fix it. That's by design, not a breakdown. When a phase closes, the next phase begins, or the next idea does.

Think of it as client, project manager, discuss, decide, roadmap, build, review, with the coding agent playing the disciplined team that never skips a step. Every move between stages is a human checkpoint: the agent proposes, then waits for your go-ahead before it proceeds.

The two tracks below run one after the other. You plan once on the left, then the right-hand loop repeats for every phase on the roadmap.

flowchart LR
    subgraph PLAN["Idea / Brainstorm (plan once)"]
      direction TB
      A1["Ideate<br/>(Planning Agent)"] --> A2["Understand the ask<br/>feature, request, or refactor"]
      A2 --> A3["Analyze and research<br/>inspect and review the code"]
      A3 --> A4["Findings"]
      A4 --> A5["Decisions<br/>settled one by one, then locked"]
      A5 --> A6["Roadmap<br/>(Planning Agent)<br/>phases, tier per phase, which tier to run"]
    end

    subgraph BUILD["Phase loop (repeats per phase)"]
      direction TB
      B1["Initiate phase<br/>(Planning Agent)"] --> B2["Phase planning<br/>(Planning Agent)"]
      B2 --> B3["Verify the plan<br/>(Verification Agent)"]
      B3 --> B4["Implement<br/>(Implementation Agent)"]
      B4 --> B5["Implementation review<br/>(Review Agent)"]
      B5 --> B6["Housekeeping"]
      B6 --> B7["Audit<br/>(Audit Agent)"]
      B7 --> B8{"Pass?"}
      B8 -- fail --> B4
      B8 -- pass --> B9["Close phase"]
      B9 -. next phase .-> B1
    end

    A6 ==> B1

Right-sized by tier. Not every change deserves the full ceremony. A one-line fix shouldn't need findings and a roadmap. PhaseOps runs work at a tier (light, full, or extended), so trivial changes move straight ahead while a new product gets the whole process.

For the full rationale, including the team analogy, the loop-back, and when not to use the process, see the Philosophy guide.

Why it helps

• It survives a long or resumed session. A coding agent won't hold this structure on its own. Over a long context it drifts, forgets earlier decisions, and skips verification. PhaseOps moves the process out into files and checkpoints, so a fresh session resumes right where the last one stopped.
• You stay in control. Every phase transition waits for your approval. The AI never runs ahead; it proposes the next step and asks.
• Decisions don't silently change. Once locked, they're written down and referenced by later phases, so drift gets caught instead of absorbed.
• The loop back is built in. Failed verification or a bad assumption routes backward on its own. Fixing course is part of the flow, not an exception.
• No prompt-engineering required. You don't have to craft a perfect mega-prompt. You ideate, approve the decisions, approve the roadmap, and the process carries the rest.
• You get an audit trail by default. Planning docs, per-slice commits, and append-only logs let you see why every change happened.

Status

Published and in production use. The full roadmap (schemas, core workflows, MCP server, adapter system, HTTP transport) is complete, and PhaseOps develops itself with its own process. Every feature ships as an initiative with planning docs, per-slice commits, and an audited close-out. That dogfooding is the main proving ground: this repository is built, slice by slice, under the same workflows and checkpoints it ships.

Current surface: 35 MCP tools (27 core plus 8 WordPress), 11 CLI commands, 7 bundled adapters, stdio and HTTP transports, and generated plugin trees for Claude Code, Cursor, and Codex (nine /phaseops:* commands where the client supports them, with MCP server wiring per client). Available on PyPI: pipx install phaseops.

Design principles

• Read-only by contract. The MCP server reads workflows, rules, and state. It never edits files or runs commands. Its only writes are two append-only logs.
• Fail-soft where it's safe. Observability (audit and feedback logs, optional integrations) degrades silently rather than blocking your work, while load-bearing state fails loud rather than risk corruption. Full rationale and trade-offs are in docs/architecture/12-fail-soft-design.md.
• Adapter isolation. Stack-specific rules (WordPress, Python, and so on) activate only in the projects that opt in. A Python session never sees WordPress rules.
• Schema-first. Every artifact type has a JSON Schema before any file is written.

Quickstart

The fastest way to get the CLI (Python 3.11 or newer):

# 1. Install PhaseOps (the [mcp] extra adds the server)
pipx install "phaseops[mcp]"
phaseops version

# 2. Set up a project. This also writes .mcp.json so Claude Code
#    auto-starts the server (it prints the entry instead if the file exists).
cd ~/code/my-project
phaseops init

# 3. Check health
phaseops doctor

# From here on: where am I, and what's the next step?
phaseops next

Open Claude Code in the project, approve the new phaseops MCP server, and you're running. Full walkthrough: docs/guides/getting-started.md.

Prefer to work from source? Clone the repo and install it editable:

git clone https://github.com/agentxworks/phaseops.git
cd phaseops
python3 -m venv .venv && .venv/bin/pip install -e ".[dev,mcp]"
ln -s "$(pwd)/.venv/bin/phaseops" ~/.local/bin/phaseops

Documentation

Guides, how to use it (start here):

Architecture, why it's built this way: the numbered documents in docs/architecture/, starting with the architecture plan. Investigation reports and raw ideas live under .planning/ (findings/, ideas/), which is PhaseOps' own dogfooding process prose.

Repository layout

src/phaseops/
├── _bundled/               # Resources shipped inside the wheel
│   ├── core/               # Workflows, planning templates, agents, rules,
│   │                       #   JSON Schemas, ADRs
│   └── adapters/           # wordpress, nodejs, react, nextjs, astro, python, langchain
├── mcp/                    # MCP server: registry, tools, session context
├── cli/                    # init, scaffold, closeout, next, validate, doctor,
│                           #   serve, sync, feedback
└── validators/             # Structural and isolation checks behind `validate`
tests/                      # ~490 tests: unit plus wire-level integration
docs/guides/                # User guides (how)
docs/architecture/          # Design documents (why)
.planning/findings/         # Investigation reports (dogfooding process prose)
.planning/ideas/            # Raw ideas and briefs
.planning/SESSION_HANDOFF.md # Live project status, read first to resume work

Development

PYTHONPATH=src .venv/bin/python -m pytest tests/ -q     # full test suite
.venv/bin/phaseops validate --strict                    # structural + isolation gates
.venv/bin/phaseops doctor                               # install/project diagnostics

All gates must pass before a commit lands. The working process itself is documented in docs/guides/working-process.md. PhaseOps is developed with PhaseOps.

Built By

Xavier Emerson P J, Senior Full-Stack Engineer and Solutions Architect.

Part of the agentxworks ecosystem: workflows, skills, and agent patterns for production-grade agentic systems.