Metadata-Version: 2.4
Name: phaseops
Version: 0.2.0
Summary: Modular, ecosystem-agnostic agentic SDLC framework.
Project-URL: Homepage, https://github.com/agentxworks/phaseops
Project-URL: Documentation, https://github.com/agentxworks/phaseops/tree/main/docs
Project-URL: Repository, https://github.com/agentxworks/phaseops
Project-URL: Issues, https://github.com/agentxworks/phaseops/issues
Author-email: Xavier Emerson <agentx4u@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,mcp,phaseops,sdlc,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.20
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: http
Requires-Dist: fastapi>=0.110; extra == 'http'
Requires-Dist: uvicorn>=0.30; extra == 'http'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Requires-Dist: structlog>=24.0; extra == 'mcp'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-exporter-otlp>=1.25; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'telemetry'
Description-Content-Type: text/markdown

# PhaseOps

[![CI](https://github.com/agentxworks/phaseops/actions/workflows/ci.yml/badge.svg)](https://github.com/agentxworks/phaseops/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/phaseops.svg)](https://pypi.org/project/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](https://github.com/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.

| If this is you | Start here |
|----------------|------------|
| You use Claude Code or Cursor daily, but your project is drifting and you have no real process | [Finding a path](docs/guides/start/struggling.md) |
| You built an MVP on Lovable, Replit, or Bolt and hit the ceiling, and the terminal is new to you | [Moving to a real codebase](docs/guides/start/from-no-code.md) |
| You are new to coding agents and want to start in an organised way | [Starting right](docs/guides/start/new-to-agents.md) |

Already know what you want? Go straight to
[Getting Started](docs/guides/getting-started.md).

---

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

```mermaid
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](docs/guides/philosophy.md).

## 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](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):

```bash
# 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](docs/guides/getting-started.md)**.

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

```bash
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):

| Guide | Covers |
|-------|--------|
| [Philosophy](docs/guides/philosophy.md) | Why PhaseOps works this way, and when (and when not) to use it |
| [Getting Started](docs/guides/getting-started.md) | Install, init, connect, verify |
| [CLI Reference](docs/guides/cli-reference.md) | All 10 commands, flags, exit codes |
| [Configuration](docs/guides/configuration.md) | Everything under `.phaseops/` |
| [MCP Tools](docs/guides/mcp-tools.md) | Every tool the AI gets, in plain English |
| [Adapters](docs/guides/adapters.md) | Bundled adapters plus writing your own |
| [Working Process](docs/guides/working-process.md) | Running real work: initiatives, slices, checkpoints |
| [Troubleshooting](docs/guides/troubleshooting.md) | Doctor checks and known failure modes |
| [Doc Templates](docs/templates/) | Copy-and-fill README and doc-page skeletons for your own project |

**Architecture, why it's built this way:** the numbered documents in
[docs/architecture/](docs/architecture/), starting with the
[architecture plan](docs/architecture/00-phaseops-architecture-plan.md).
Investigation reports and raw ideas live under [.planning/](.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

```bash
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](docs/guides/working-process.md). PhaseOps is
developed with PhaseOps.

---

## Built By

[Xavier Emerson P J](https://github.com/agentx4u), Senior Full-Stack Engineer
and Solutions Architect.

---

*Part of the [agentxworks](https://github.com/agentxworks) ecosystem: workflows,
skills, and agent patterns for production-grade agentic systems.*
