phaseops 0.1.0

Modular, ecosystem-agnostic agentic SDLC framework.

PhaseOps

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

Part of the agentxworks ecosystem.

---

What is PhaseOps?

AI coding assistants are powerful but unstructured: long chats, lost context, no audit trail, no consistent process. PhaseOps adds the missing structure without taking control away from you:

• Phase-based workflows — work moves through named stages (ideate → plan → implement → verify → close), each 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 stopped.
• Adapters — stack-specific rules, skills, and tools (WordPress, Node.js, React, Next.js, Astro, Python, LangChain bundled) that activate only in projects that opt in.
• A read-only MCP server — your AI tool (e.g. Claude Code) gets 27 core tools (plus adapter tools) for reading workflows, rules, state, and planning docs. The server never edits files, 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; the agent works to understand it (new product? feature? refactor?) instead of guessing and coding.
2. Research & findings — for anything touching existing code, the agent reads the codebase and reports its findings back to you.
3. Decisions — you and the agent settle the open questions together, and the decisions are 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 proactively asks "next is initiate phase X — shall we start?" at each step.
6. Loop back — if verify fails, a decision proves wrong, or the context drifts, the flow routes backward to fix it. That is by design, not a breakdown. When a phase closes, the next phase — or the next idea — begins.

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 transition between stages is a human checkpoint: the agent proposes, and it waits for your approval before it proceeds.

flowchart TB
    Idea(["Idea / request"]) --> Ideate
    Ideate["Ideate<br/>understand the ask"] --> Findings["Research and findings<br/>read the code"]
    Findings --> Decisions["Decisions locked"]
    Decisions --> Roadmap["Roadmap<br/>you approve"]
    Roadmap --> Initiate
    subgraph Loop["Phase loop — repeats per roadmap item"]
      direction TB
      Initiate["Initiate"] --> Implement["Implement"]
      Implement --> Verify{"Verify?"}
      Verify -- pass --> Close["Close"]
      Verify -- fail --> Implement
    end
    Close --> More{"More phases?"}
    More -- yes --> Initiate
    More -- no --> Idea

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 / extended), so trivial changes move straight ahead while a new product gets the whole process.

For the full rationale — 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 externalizes the process into files and checkpoints, so a brand-new session resumes exactly 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 — drift is caught, not absorbed.
• The loop back is built in. Failed verification or a bad assumption routes backward automatically; rectification is part of the flow, not an exception.
• No prompt-engineering required. You don't craft a perfect mega-prompt. You ideate, approve the decisions, approve the roadmap — the process carries the rest.
• An audit trail by default. Planning docs, per-slice commits, and append-only logs let you see why every change happened.

Status

Implemented 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 audited close-out. That dogfooding is the primary proving ground: this repository is built, slice by slice, under the same workflows and checkpoints it ships.

Current surface: 35 MCP tools (27 core + 8 WordPress), 11 CLI commands, 7 bundled adapters, stdio + HTTP transports, and generated plugin trees for Claude Code, Cursor, and Codex (nine /phaseops:* commands where the client supports them; MCP server wiring per client). Not yet on PyPI — installs from a repo clone.

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/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: docs/architecture/12-fail-soft-design.md.
• Adapter isolation — stack-specific rules (WordPress, Python, …) activate only in 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

# 1. Install (Python 3.11+)
git clone https://github.com/agentxworks/phaseops.git
cd phaseops
python3 -m venv .venv && .venv/bin/pip install -e ".[dev,mcp]"

# 2. Put the `phaseops` command on your PATH
ln -s "$(pwd)/.venv/bin/phaseops" ~/.local/bin/phaseops
phaseops version   # 0.1.0

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

# 4. 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.

Documentation

Guides — how to use it (start here):

Guide	Covers
Philosophy	Why PhaseOps works this way, and when (and when not) to use it
Getting Started	Install → init → connect → verify
CLI Reference	All 10 commands, flags, exit codes
Configuration	Everything under .phaseops/
MCP Tools	Every tool the AI gets, in plain English
Adapters	Bundled adapters + writing your own
Working Process	Running real work: initiatives, slices, checkpoints
Troubleshooting	Doctor checks + known failure modes
Doc Templates	Copy-and-fill README + doc-page skeletons for your own project

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/) — 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 + isolation checks behind `validate`
tests/                      # 300+ assertions: unit + 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.