Metadata-Version: 2.4
Name: phaseops
Version: 0.1.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)

> 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](https://github.com/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.

```mermaid
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](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 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](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

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

## 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 + writing your own |
| [Working Process](docs/guides/working-process.md) | Running real work: initiatives, slices, checkpoints |
| [Troubleshooting](docs/guides/troubleshooting.md) | Doctor checks + known failure modes |
| [Doc Templates](docs/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/](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/`) — 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

```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.*
