archflow

<div align="center">

<a name="archflow"></a>

<h1> <img src="docs/logo.png" alt="" width="42" height="42" align="absmiddle" /> Archflow </h1>

Turn your coding agent into a structured development team.

Website · Watch it work · Quick Start · Hosts · Three Ways to Start · Studio · Commands · How It Works · Phases · Agents

<img src="docs/archflow-overview.svg" alt="Archflow Overview" width="700" />

▶ Watch the 59-second overview · or the 3-minute onboarding run on a real codebase

</div>

---

What is Archflow?

Getting AI to write code stopped being the hard part. Keeping it coherent is. Sessions end and take their context with them. The frontend drifts from the backend. Two weeks in, nobody can say what's actually finished.

Archflow is a phase-based AI development framework for your coding agent that fixes this structurally, with 17 specialized agents working from product strategy through to production deployment. It runs on Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor, Gemini CLI and OpenCode, from the same files in your repo; see Hosts.

Instead of one AI doing everything, each task goes to an agent with deep expertise in its domain. A product-strategist defines business goals. A ux-designer creates the design system. An api-contract-architect locks down API specs. Then ui-engineer and api-engineer build frontend and backend in parallel against that same contract, so they can't quietly disagree. Handoffs happen through files, not chat, so context outlives the session that created it.

Two things keep it practical rather than theoretical:

It meets your codebase where it is. A blank directory, an established codebase, or a prototype that outgrew itself: Archflow reads what already exists and picks up from there. It never assumes you're on day one.

Ceremony scales with the project. A solo weekend build runs in quick mode: one implicit release, gates that record but don't block. A team with a real release pipeline runs in full mode. Same schema either way, so switching costs nothing, and Archflow offers the upgrade when it notices you've outgrown the simpler mode.

Works with any project type (fullstack, frontend-only, backend-only, or mobile), adapting its phases, agents, and artifact structure to each.

---

Quick Start

1. Install

From your project root:

npx archflow install

It detects the coding agents on your machine and sets Archflow up for each one: Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor, Gemini CLI and OpenCode. Everything it writes lands in your repo, so teammates get it on clone. Pass --host codex,cursor to choose, or --dry-run to see the plan first.

On Claude Code the plugin marketplace works too, and is what npx archflow install runs for you there:

claude plugin marketplace add AZidan/archflow
claude plugin install archflow --scope project

Free and open source. No lock-in. Uninstall by deleting what it added; on Claude Code, claude plugin uninstall archflow.

2. Open your coding agent in the project

cd your-project
claude        # or codex, cursor, gemini, opencode, copilot

Then pick the entry point that matches where you actually are.

---

Hosts

Archflow is files, so the same .archflow/ state, agents and phases run on every host it supports. npx archflow install copies a host-native adapter into the project, merges the Archflow block into AGENTS.md and installs a git pre-push guard; on Claude Code it installs the marketplace plugin at project scope. Re-running it is the upgrade: the adapters come from the latest GitHub release, whatever version of the installer npx has cached, and a session-start check tells you when a newer release exists.

| Host | What you get | Sub-agents | Hooks | |---|---|---|---| | Claude Code | The plugin, via the marketplace. Studio lives here | yes | yes | | OpenAI Codex | .codex/ agents and $archflow-<cmd> skills | yes | yes | | GitHub Copilot CLI | .github/ agents, skills and hooks; VS Code agent mode reads the same tree | yes | yes | | Cursor | .cursor/ agents, commands, rules and hooks; also a Cursor Plugin | yes | yes | | Gemini CLI | An extension, installed per user | preview | yes | | OpenCode | .opencode/ agents, commands and a plugin for hooks | yes | primary agent only | | Anything with AGENTS.md + Agent Skills | Skills only; roles run serially; the git guard is the safety net | no | no |

What does not port: /archflow:studio drives the claude binary, and memory: user agent memory has no equivalent elsewhere. Each adapter's README under adapters/<host>/ lists that host's limits. Something off on your host? Open an issue. Contributors regenerate the adapters after changing plugin/ with node scripts/build-adapters.mjs; CI fails on drift.

---

Three Ways to Start

Whichever you pick, Archflow proposes and waits: every artifact is shown to you before it's written, and no phase advances without your approval. Your code is never modified during setup.

All three work from the terminal or from Archflow Studio, which runs them for you in a browser.

1. New project: start from strategy

/archflow:init

Creates the state files and drops you at Phase 1. A product-strategist works out who this is for and what success means, a feature-planner turns that into a backlog, and you move through design → API contract → implementation with an approval gate at every step.

Starts in quick mode, so you get structure without ceremony until you ask for it.

📖 Full guide: starting a new project

2. Existing codebase: onboard it

/archflow:onboard

Dispatches up to 9 agents in parallel to read your codebase, imports context from tools you already use (Jira, Notion, Linear, GitHub, Confluence, Slack), and reverse-engineers the artifacts you never wrote down: design system, API contract, user flows, roadmap. Everything is presented for approval before anything is written.

It also works out which phase your project has reached, so you don't redo work that's already done.

▶ Watch a real repo get onboarded (3m20s, unedited) · 📖 Full guide: onboarding an existing codebase

3. From prototype to product

Your prototype works. People are using it. What it doesn't have is a roadmap, an API contract, a test plan, or a defensible answer to what "1.0" means.

/archflow:onboard

Onboarding audits what you shipped and reconstructs the plan around it. Where it finds working code with no story behind it, it writes the story and marks it delivered, so your roadmap opens reflecting reality instead of pretending nothing exists yet.

From there, the road to a real product is the phases a prototype skips:

| What a prototype usually lacks | Where it comes from | |---|---| | Product direction, personas, success metrics | Phase 1 | | A design system instead of ad-hoc styling | Phase 2 | | An API contract both sides build against | Phase 2.5 | | Tests and acceptance criteria per story | Phase 3 | | Security, code quality, and performance review | Phase 4 | | CI/CD, versioning, app store prep, analytics | Phase 5 |

You stay in quick mode while it's still small. When Archflow spots growth signals (a second release, a second contributor, a size threshold) it offers full mode with explicit release planning and role-based gates. It never forces the upgrade.

What this does and doesn't do: it gives you the plan, contracts, and quality gates your prototype never had, and Phase 4 agents will review code quality, security, and performance. It will not silently rewrite your architecture. You decide what gets refactored; Archflow makes sure you know what needs it.

📖 Full guide: taking a prototype to production

---

Then: Develop Features

/archflow:feature          # Interactive wizard
/archflow:feature login    # Quick-add by name or description

Archflow creates the feature branch, breaks it into tasks, and guides implementation through the appropriate agents. Features are filtered by scope: a backend_only repo only sees backend-scoped work.

Capture an idea without committing to it, and detail it later when it's next up:

/archflow:feature          # → capture as a backlog stub
/archflow:groom S2-11      # → add acceptance criteria, subtasks, gates
/archflow:feature S2-11    # → pull it into the active release and start building

---

Or: Let It Run Unattended

/archflow:autopilot        # interview, then build the release's stories while you sleep

Autopilot is the unattended lane. It asks you everything it can't decide alone up front, in one batch (product behaviour, trade-offs, anything irreversible), then goes silent and builds story after story, running QA and acceptance on each. One report at the end.

The part that makes it safe is what happens when a new blocker appears at 3am. It never guesses and it never stalls the run: the story is parked with the open question and 2–4 candidate answers, the work-in-progress stays committed but unmerged, and the run moves to the next story. A parked story blocks the release until you answer.

Everything lands on one branch. Autopilot never merges to main, never opens a PR, never ships. You review a night's work in the morning and merge it yourself.

/archflow:autopilot --plan     # interview + show the queue, don't start
/archflow:autopilot resume     # answer the parked questions, pick up where it stopped

---

Or: Skip the Terminal

/archflow:studio        # opens a local workspace at localhost:3456

Studio is a local web workspace over the same .archflow/ files. The roadmap becomes a board, the release becomes a pipeline, and the agents work in front of you instead of behind a scroll of text.

It sets itself up. Point it at a folder and Studio runs onboarding for you: the same nine agents, the same approval gates, driven from a button instead of a prompt. A project still on the v1.0 schema gets a one-button migration to v2.0, backup included. After the plugin install, the terminal is optional.

Its chat is your session, forked. Open Studio from a running Claude Code session and its chat starts with that conversation's history on a branch, so you don't re-explain the project to a second assistant. Nothing you type in Studio lands back in your terminal. If no session context is found it falls back to its own claude process and says so.

Local, and only local. Binds to 127.0.0.1 with an origin allowlist covering the WebSocket upgrade. No cloud service, no telemetry, no account. Your code and your Claude credentials never leave the machine.

The server is detached on purpose, so it outlives the session that started it and you can leave it open beside your work.

/archflow:studio status     # is it running, and for which project?
/archflow:studio stop       # shut it down
/archflow:studio port 3457  # use a different port

Studio is what ships Studio: 4 releases and 71 stories so far, planned and driven