{"id":"6ad715bc-b4e5-421a-bc4d-bba19ce79f50","slug":"azidan-archflow","kind":"skill","name":"archflow","summary":"Phase-based AI development framework for AI Coding Agents. 17 specialized agents across 6 phases, handing off through files in your repo — and it reads the codebase you already have.","owner":"AZidan","repoUrl":"https://github.com/AZidan/archflow","license":"MIT","licenseTier":"permissive","trust":"community","stars":29,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-03-12T04:17:23.000Z","addedAt":"2026-10-14T11:39:55.896Z","logoUrl":"https://avatars.githubusercontent.com/u/2356958?u=c23501729b55e1e81ebd589fb1ddb9f55aa1dc3f&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","files-documents"],"tags":["agent-orchestration","agentic-development","ai-agents","ai-coding-assistant","ai-development-framework","claude-code","claude-code-plugin","developer-tools"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T21:39:50.307Z","sample":false,"url":"https://conduits.dev/tools/azidan-archflow","language":"Python","transports":["stdio"],"install":{"npm":"archflow"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n<a name=\"archflow\"></a>\n<h1>\n  <img src=\"docs/logo.png\" alt=\"\" width=\"42\" height=\"42\" align=\"absmiddle\" />\n  Archflow\n</h1>\n\n**Turn your coding agent into a structured development team.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-0f766e)](https://opensource.org/licenses/MIT) [![Agents](https://img.shields.io/badge/Agents-17-0d9488)](https://github.com/AZidan/archflow) [![Phases](https://img.shields.io/badge/Phases-6-0d9488)](https://github.com/AZidan/archflow) [![Studio](https://img.shields.io/badge/Studio-Beta-14b8a6)](#or-skip-the-terminal)\n\n[Website](https://archflowai.dev/) · [Watch it work](https://www.youtube.com/@archflowai-dev) · [Quick Start](#quick-start) · [Hosts](#hosts) · [Three Ways to Start](#three-ways-to-start) · [Studio](#or-skip-the-terminal) · [Commands](#commands) · [How It Works](#how-it-works) · [Phases](#the-phases) · [Agents](#agents)\n\n<img src=\"docs/archflow-overview.svg\" alt=\"Archflow Overview\" width=\"700\" />\n\n**[▶ Watch the 59-second overview](https://www.youtube.com/watch?v=sc2qEDnDeP0)** · or the [3-minute onboarding run](https://archflowai.dev/#start) on a real codebase\n\n</div>\n\n---\n\n## What is Archflow?\n\nGetting 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.\n\nArchflow 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 (enterprise/API) and OpenCode, from the same files in your repo; see [Hosts](#hosts).\n\nInstead 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.\n\nTwo things keep it practical rather than theoretical:\n\n**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.\n\n**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.\n\nWorks with any project type (fullstack, frontend-only, backend-only, or mobile), adapting its phases, agents, and artifact structure to each.\n\n---\n\n## Quick Start\n\n### 1. Install\n\nFrom your project root:\n\n```bash\nnpx archflow install\n```\n\nIt detects the coding agents on your machine and sets Archflow up for each one: Claude Code, OpenAI\nCodex, GitHub Copilot CLI, Cursor, Gemini CLI (enterprise/API) and OpenCode. Everything it writes lands in your repo, so\nteammates get it on clone. Pass `--host codex,cursor` to choose, or `--dry-run` to see the plan first.\n\nOn Claude Code the plugin marketplace works too, and is what `npx archflow install` runs for you there:\n\n```bash\nclaude plugin marketplace add AZidan/archflow\nclaude plugin install archflow --scope project\n```\n\nFree and open source. No lock-in. Uninstall by deleting what it added; on Claude Code,\n`claude plugin uninstall archflow`.\n\n### 2. Open your coding agent in the project\n\n```bash\ncd your-project\nclaude        # or codex, cursor, gemini, opencode, copilot\n```\n\nThen pick the entry point that matches where you actually are.\n\n---\n\n## Hosts\n\nArchflow is files, so the same `.archflow/` state, agents and phases run on every host it supports.\n`npx archflow install` copies a host-native adapter into the project, merges the Archflow block into\n`AGENTS.md` and installs a git pre-push guard; on Claude Code it installs the marketplace plugin at\nproject scope. Re-running it is the upgrade: the adapters come from the latest GitHub release, whatever\nversion of the installer npx has cached, and a session-start check tells you when a newer release exists.\n\n| Host | What you get | Sub-agents | Hooks |\n|---|---|---|---|\n| Claude Code | The plugin, via the marketplace. Studio's chat runs the agent in its panel | yes | yes |\n| OpenAI Codex | `.codex/` agents and `$archflow-<cmd>` skills | yes | yes |\n| GitHub Copilot CLI | `.github/` agents, skills and hooks; VS Code agent mode reads the same tree | yes | yes |\n| Cursor | `.cursor/` agents, commands, rules and hooks; also a Cursor Plugin | yes | yes |\n| Gemini CLI (enterprise/API) | An extension, installed per user | preview | yes |\n| OpenCode | `.opencode/` agents, commands and a plugin for hooks | yes | primary agent only |\n| Anything with `AGENTS.md` + Agent Skills | Skills only; roles run serially; the git guard is the safety net | no | no |\n\nGoogle now points individual users (free, AI Pro, AI Ultra) to its Antigravity CLI; Gemini CLI serves\nGemini Code Assist Standard/Enterprise and paid Gemini API users. Archflow support for Antigravity CLI is planned.\n\nStudio runs on every host. Off Claude Code it runs in forward mode: its chat composes the command\nand you paste it into your own terminal session, and `npx archflow@latest install` puts its bundle in\nthat host's install (`@latest`: an installer npx cached before 2.5.0 brings the adapters without it). What does not port: Studio's companion mode, which forks a Claude Code session, and\n`memory: user` agent memory, which has no equivalent elsewhere. Each adapter's README under `adapters/<host>/` lists that host's limits.\nSomething off on your host? [Open an issue](https://github.com/AZidan/archflow/issues).\nContributors regenerate the adapters after changing `plugin/` with `node scripts/build-adapters.mjs`;\nCI fails on drift.\n\n---\n\n## Three Ways to Start\n\nWhichever 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.\n\nAll three work from the terminal or from [Archflow Studio](#or-skip-the-terminal), which runs them for you in a browser.\n\n### 1. New project: start from strategy\n\n```\n/archflow:init\n```\n\nCreates 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.\n\nStarts in `quick` mode, so you get structure without ceremony until you ask for it.\n\n📖 [Full guide: starting a new project](https://archflowai.dev/guides/new-project/)\n\n### 2. Existing codebase: onboard it\n\n```\n/archflow:onboard\n```\n\nDispatches 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.\n\nIt also works out which phase your project has reached, so you don't redo work that's already done.\n\n▶ **[Watch a real repo get onboarded](https://archflowai.dev/#start)** (3m20s, unedited) · 📖 [Full guide: onboarding an existing codebase](https://archflowai.dev/guides/existing-codebase/)\n\n### 3. From prototype to product\n\nYour 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.\n\n```\n/archflow:onboard\n```\n\nOnboarding 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.\n\nFrom there, the road to a real product is the phases a prototype skips:\n\n| What a prototype usually lacks | Where it comes from |\n|---|---|\n| Product direction, personas, success metrics | Phase 1 |\n| A design system instead of ad-hoc styling | Phase 2 |\n| An API contract both sides build against | Phase 2.5 |\n| Tests and acceptance criteria per story | Phase 3 |\n| Security, code quality, and performance review | Phase 4 |\n| CI/CD, versioning, app store prep, analytics | Phase 5 |\n\nYou 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.\n\n**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.\n\n📖 [Full guide: taking a prototype to production](https://archflowai.dev/guides/prototype-to-product/)\n\n---\n\n## Then: Develop Features\n\n```\n/archflow:feature          # Interactive wizard\n/archflow:feature login    # Quick-add by name or description\n```\n\nArchflow 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.\n\nCapture an idea without committing to it, and detail it later when it's next up:\n\n```\n/archflow:feature          # → capture as a backlog stub\n/archflow:groom S2-11      # → add acceptance criteria, subtasks, gates\n/archflow:feature S2-11    # → pull it into the active release and start building\n```\n\n---\n\n## Or: Let It Run Unattended\n\n```\n/archflow:autopilot        # interview, then build the release's stories while you sleep\n```\n\nAutopilot 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\nafter story, running QA and acceptance on each. One report at the end.\n\nThe part that makes it safe is what happens when a *new* blocker appears at 3am. It never guesses and\nit never stalls the run: the story is **parked** with the open question and 2–4 candidate answers, the\nwork-in-progress stays committed but unmerged, and the run moves to the next story. A parked story\nblocks the release until you answer.\n\nEverything 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.\n\n```\n/archflow:autopilot --plan     # interview + show the queue, don't start\n/archflow:autopilot resume     # answer the parked questions and build those stories, even after a run finished or was aborted\n```\n\n---\n\n## Or: Skip the Terminal\n\n```\n/archflow:studio        # opens a local workspace at localhost:3456\n```\n\nStudio is a local web workspace over the same `.archflow/` files. The roadmap becomes a board, the\nrelease becomes a pipeline, and the agents work in front of you instead of behind a scroll of text.\n\n**It sets itself up.** Point it at a folder and Studio runs onboarding for you: the same nine agents,\nthe same approval gates, driven from a button instead of a prompt. A project still on the v1.0 schema\ngets a one-button migration to v2.0, backup included. After the plugin install, the terminal is\noptional.\n\n**Its chat runs your host, or feeds it.** On Claude Code, Studio's chat runs its own `claude`\nprocess; opt in with `STUDIO_MODE=companion` and it starts from your running session's history, on a\nbranch, so you don't re-explain the project to a second assistant. On Codex, Copilot CLI, Cursor,\nGemini CLI (enterprise/API), OpenCode and any `AGENTS.md` + Agent Skills agent it runs in forward mode: you compose in the panel, Studio spells the command\nthe way your host expects, and you paste it into the terminal session you already have open.\n`/archflow:studio status` says which host Studio resolved and what its chat does.\n\n**Local, and only local.** Binds to `127.0.0.1` with an origin allowlist covering the WebSocket\nupgrade. No cloud service and no account. Your code and your Claude credentials never leave the\nmachine. The coding-agent sessions Studio drives — Claude Code or any other supported host — send\nthe same anonymous usage telemetry as any other session (see [What Archflow runs on your\nmachine](#what-archflow-runs-on-your-machine)). Studio itself sends its own anonymous events too\n(which views are opened, by route template only, and which actions run); on a host without a native\nadapter, a command copied from Studio and pasted into that host's own session is reported by that\nhost, not by Studio.\n\nThe server is detached on purpose, so it outlives the session that started it and you can leave it\nopen beside your work.\n\n```\n/archflow:studio status     # is it running, and for which project?\n/archflow:studio stop       # shut it down\n/archflow:studio port 3457  # use a different port\n```\n\nStudio is what ships Studio: 4 releases and 71 stories so far, planned and driven from its own board.\nIt is marked beta because features are still landing, and because\n[what you tell us is missing](https://github.com/AZidan/archflow/issues) decides which land next.\n\n📖 [Full guide: using Archflow Studio](https://archflowai.dev/guides/studio/)\n\n---\n\n## How It Works\n\nBuilding software with AI means context gets lost, quality varies, and the same mistakes repeat. Archflow fixes this with three ideas:\n\n- **Specialized agents**: A UX designer doesn't write backend code. An API engineer doesn't make design decisions. 17 agents, each scoped to one domain.\n- **File-based handoffs**: Context survives between conversations. Agents communicate through artifacts, not chat, so nothing gets lost when a session ends.\n- **Phase gates**: 6 phases from strategy to deployment. Nothing moves forward without your approval. No skipped steps. No autonomous decisions on what ships. (`/archflow:autopilot` pre-authorizes those gates for one unattended run, and still stops short of `main`.)\n- **Contract-first development**: API contracts are defined before implementation. Frontend and backend build against the same spec, so they never disagree.\n- **Focused context**: Each phase loads only what the active agents need. Less noise, better results.\n- **Acceptance testing**: Features aren't done until they pass acceptance testing against your roadmap criteria.\n\n---\n\n## The Phases\n\n```\nPhase 1    Strategy & Planning         product-strategist, feature-planner\nPhase 2    Design                      ux-designer, dsl-generator\nPhase 2.25 High-Fidelity Screens       SuperDesign MCP (optional)\nPhase 2.5  API Architecture            api-contract-architect\nPhase 3    Implementation (Parallel)   ui-engineer + api-engineer, qa-engineer, pm-reviewer\nPhase 4    Quality & Optimization      code-reviewer, performance-optimizer, pm-reviewer\nPhase 5    Launch & Operations         devops-engineer, post-launch-analyst\nPhase 6    Enhancement (On-Demand)     i18n-engineer, post-launch-analyst, any agent as needed\n```\n\nSix numbered phases, plus two optional sub-phases: 2.25 needs the SuperDesign MCP server and can\nbe skipped entirely, and 2.5 is skipped for projects with no API. That is why you will see both\n\"6 phases\" and eight phase files.\n\nEach phase has explicit completion criteria, expected output artifacts, and requires user approval\nbefore advancing.\n\n---\n\n## Inside `/archflow:onboard`\n\nMost AI workflows assume you're starting from scratch. This is the one that doesn't, and it's the engine behind both the *existing codebase* and *prototype to product* paths above.\n\n```\nPhase A: Interactive Collection     Answer 5 questions about your stack and context sources\n\nPhase B: Autonomous Agent Dispatch  Up to 9 agents analyze your codebase in parallel:\n                                    codebase audit → doc deep-dive → design extraction →\n                                    route/API extraction → product-strategist → ux-designer →\n                                    api-contract-architect → dsl-generator → feature-planner\n\nPhase C: Synthesis & Presentation   Artifacts generated and presented for your approval\n```\n\nThe onboarding agents generate ready-to-use `project-context.md`, `roadmap.yaml`, `backlog.yaml`, `api-contract.md`, `theme.yaml`, `styled-dsl.yaml`, and `user-flows.md`, all reverse-engineered from your existing code and imported documentation. It also creates or updates your project's `CLAUDE.md` with architecture context derived from the analysis.\n\nTwo things make the result honest rather than aspirational: reconciliation moves any story whose code already exists into a shipped release, and the **gap report** tells you plainly what's missing: no tests, no contract, no design system, so you're choosing what to fix rather than discovering it later.\n\n---\n\n## Agents\n\n| Phase | Agents |\n|-------|--------|\n| 1. Strategy & Planning | `product-strategist`, `feature-planner` |\n| 2. Design | `ux-designer`, `dsl-generator` |\n| 2.25 High-Fidelity (optional) | SuperDesign MCP |\n| 2.5 API Architecture | `api-contract-architect` |\n| 3. Implementation | `ui-engineer`, `api-engineer`, `qa-engineer`, `pm-reviewer` |\n| 4. Quality & Optimization | `code-reviewer`, `performance-optimizer`, `pm-reviewer` |\n| 5. Launch & Operations | `devops-engineer`, `post-launch-analyst` |\n| 6. Enhancement | `i18n-engineer`, any agent as needed |\n\n---\n\n## Commands\n\nEvery command is namespaced `/archflow:<name>`. You'll use three of them regularly.\n\n**Getting set up**: run once per project\n\n| Command | What it does |\n|---------|-------------|\n| `/archflow:init` | Initialize a new project at Phase 1 |\n| `/archflow:onboard` | Analyze an existing codebase and generate all artifacts |\n| `/archflow:design` | The design system every UI agent builds against (set once), or one story's screens (`/archflow:design S7-20`). Shows the current choice with no args) |\n| `/archflow:setup-mcp` | Connect external tools (Jira, Notion, Linear, GitHub, etc.) |\n| `/archflow:migrate` | Upgrade a v1.0 project to schema v2.0 (releases replace phases) |\n\n**Day to day**: the ones you'll actually type\n\n| Command | What it does |\n|---------|-------------|\n| `/archflow:status` | Current phase, active release, progress, and what to run next |\n| `/archflow:help` | Every command with a one-line usage note, and how Archflow works |\n| `/archflow:feature` | Add a story: to the backlog, or straight into the active release with a branch |\n| `/archflow:groom` | Detail or refine a story: a backlog stub into `ready`, or one already in a release with its gates re-derived |\n| `/archflow:contract` | The API contract architecture, or one story's endpoints |\n| `/archflow:issue` | Record a defect on a story being built, see what is open, or defer a minor one to the backlog |\n| `/archflow:doctor` | Check the environment and project state. `--fix` repairs drift after a plugin upgrade |\n| `/archflow:studio` | Open the visual workspace over the same files (beta) |\n\n**Planning and pace**: when the project grows\n\n| Command | What it does |\n|---------|-------------|\n| `/archflow:release` | Inspect and manage releases (`new`, `start`, `ship`) |\n| `/archflow:mode` | Show or switch ceremony mode (`quick` \\| `full`) |\n| `/archflow:autopilot` | Build the release's queued stories unattended on one branch |\n| `/archflow:telemetry` | Show or change anonymous usage telemetry (on by default; `off` opts out) |\n\nRun `/archflow:status` any time you've lost the thread: it reports where the project stands and what's sensible to do next. Run `/archflow:help` for every command and a short primer on how Archflow works.\n\n---\n\n## Project Types\n\nArchflow detects and adapts to your project type:\n\n| Type | Frontend Agent | Backend Agent | Notes |\n|------|---------------|---------------|-------|\n| `fullstack` | Yes | Yes | Parallel frontend/backend development |\n| `frontend_only` | Yes | No | Pages, components, flows |\n| `backend_only` | No | Yes | Endpoints, services, modules |\n| `mobile` | Yes | Yes | React Native, SwiftUI, or Jetpack Compose |\n\nPhase instructions, agent selection, audit checks, and roadmap structure all adapt to the project type.\n\n---\n\n## Git Workflow\n\nArchflow uses a structured branching strategy:\n\n```\nmain\n └── feature/user-auth              (feature branch)\n      ├── user-auth/login-form       (task branch)\n      ├── user-auth/auth-api         (task branch)\n      └── user-auth/session-mgmt     (task branch)\n```\n\n- Feature branches from `main`\n- Task branches from the feature branch\n- Merges only happen after explicit user approval\n- Feature completion triggers cleanup and roadmap updates\n\n---\n\n## Key Artifacts\n\nArchflow manages these files in your project:\n\n| File | Purpose |\n|------|---------|\n| `.archflow/project-context.md` | Business goals, tech stack, architecture decisions |\n| `.archflow/roadmap.yaml` | Index: epic labels, release pipeline, ceremony mode |\n| `.archflow/backlog.yaml` | Unscheduled scope: stubs and groomed `ready` stories |\n| `.archflow/releases/{slug}.yaml` | Stories committed to a release, with gates and acceptance criteria |\n| `.archflow/history.yaml` | What shipped, when, and which files it touched |\n| `.archflow/current-phase.yaml` | Where the project is: phase, mode, active release |\n| `.archflow/project-settings.yaml` | How the project works: type, stack, contract path, optional agents |\n| `.archflow/current-feature.yaml` | Active feature scope and task tracking |\n| `docs/api-contract.md` | API specifications (single source of truth). Path is configurable via `api_contract_path` |\n| `design-artifacts/styled-dsl.yaml` | Component specifications with styling |\n| `design-artifacts/theme.yaml` | Design system tokens |\n| `design-artifacts/wireframes/` | Screen layouts |\n| `docs/acceptance-reports/` | End-to-end acceptance results and verdicts |\n\n---\n\n<details>\n<summary><strong>File Structure</strong></summary>\n\nArchflow is distributed as a Claude Code plugin marketplace, and for other hosts as generated adapter packages that `npx archflow install` copies into a project. The plugin contains all framework code; your project only stores state files.\n\n### Marketplace (this repo)\n\n```\narchflow/\n├── .claude-plugin/marketplace.json  # Marketplace registry\n├── CHANGELOG.md                     # Release history\n├── CONTRIBUTING.md                  # How to add an agent, command or schema\n├── SECURITY.md                      # Pinning policy, untrusted content, shell surface\n├── .github/workflows/ci.yml         # Mirror check, schema validation, tests\n├── tests/                           # Framework tests + fixture projects\n├── plugin/                          # Installable plugin\n│   ├── .claude-plugin/plugin.json   # Plugin manifest\n│   ├── hooks/                       # SessionStart, PreToolUse guard, Stop check\n│   │   ├── hooks.json               #   registration for both\n│   │   └── studio-session-context.mjs #  publishes session id/cwd for Studio companion mode\n│   ├── agents/                      # 17 specialized agent definitions (the ONLY agents tree)\n│   ├── commands/                    # Slash commands (namespaced /archflow:<name>)\n│   │   ├── status.md                # /archflow:status\n│   │   ├── help.md                  # /archflow:help\n│   │   ├── init.md                  # /archflow:init\n│   │   ├── onboard.md               # /archflow:onboard\n│   │   ├── migrate.md               # /archflow:migrate\n│   │   ├── mode.md                  # /archflow:mode\n│   │   ├── release.md               # /archflow:release\n│   │   ├── groom.md                 # /archflow:groom\n│   │   ├── feature.md               # /archflow:feature\n│   │   ├── autopilot.md             # /archflow:autopilot\n│   │   ├── design.md                # /archflow:design\n│   │   ├── contract.md              # /archflow:contract\n│   │   ├── issue.md                 # /archflow:issue\n│   │   ├── doctor.md                # /archflow:doctor\n│   │   ├── studio.md                # /archflow:studio\n│   │   ├── telemetry.md             # /archflow:telemetry\n│   │   └── setup-mcp.md             # /archflow:setup-mcp\n│   ├── scripts/migrate.py           # v1.0 → v2.0 migration engine (used by /archflow:migrate)\n│   ├── server/server.mjs            # Archflow Studio server bundle (built elsewhere, see below)\n│   ├── dist/                        # Archflow Studio web UI (built elsewhere, see below)\n│   └── skills/archflow/             # Framework knowledge + assets copied into projects\n│       ├── SKILL.md                 # Overview skill (what Archflow is, where things live)\n│       ├── instructions.md          # Core instructions (copied to .archflow/, reloaded via hook)\n│       ├── workflow.md              # Git branching strategy\n│       ├── phases/                  # Phase-specific instruction files (10 files)\n│       ├── schemas/                 # roadmap / release / backlog / history / autopilot schemas\n│       ├── design-systems/          # One markdown file per design system + examples/ screenshots\n│       │                            #   material3 · liquid-glass · shadcn · fluent2 · custom-tokens\n│       ├── base-dsl-structure.yaml  # DSL template for design artifacts\n│       └── mcp-registry.yaml        # Curated MCP server registry\n├── README.md\n└── LICENSE\n```\n\n### Project (created by `/archflow:onboard` or Phase 1 setup)\n\n```\nyour-project/\n├── .archflow/                       # Project state (version-controlled)\n│   ├── current-phase.yaml           # Where the project is (cursor)\n│   ├── project-settings.yaml        # How the project works (settings)\n│   ├── design-system.yaml           # The chosen design system (name, platform, library, theme)\n│   ├── design-systems/              # The design-system reference files, copied from the plugin\n│   ├── project-context.md           # Business goals, tech stack, architecture\n│   ├── roadmap.yaml                 # Index: epics, release pipeline, mode\n│   ├── backlog.yaml                 # Unscheduled scope (stubs + groomed stories)\n│   ├── releases/                    # One file per release; archive/ for shipped\n│   ├── history.yaml                 # Shipped ledger (institutional memory)\n│   └── current-feature.yaml         # Active feature scope and tasks\n├── .claude/settings.json            # Plugin reference (auto-created on install)\n└── CLAUDE.md                        # Updated with Archflow section by onboarding\n```\n\n</details>\n\n<details>\n<summary><strong>External Tool Integration</strong></summary>\n\nThe `/archflow:setup-mcp` command configures MCP servers to connect with your existing tools:\n\n| Tool | Transport | Purpose |\n|------|-----------|---------|\n| Jira | HTTP/OAuth | Import epics, stories, sprint data |\n| Confluence | HTTP/OAuth | Import documentation |\n| Notion | HTTP/OAuth | Import pages and databases |\n| Linear | HTTP/OAuth | Import issues, projects, cycles |\n| GitHub | HTTP/OAuth | Import issues, PRs, project boards |\n| Google Drive | stdio/OAuth | Import Google Docs and Sheets |\n| Slack | HTTP/OAuth | Import context from channels/threads |\n| Trello | stdio/env | Import boards, lists, cards |\n\nThese integrations are primarily used during `/archflow:onboard` to pull existing project context into Archflow's format.\n\n</details>\n\n---\n\n## Requirements\n\n### Required\n\n| Tool | Why | Used by |\n|---|---|---|\n| One of the supported coding agents: Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor, Gemini CLI (enterprise/API) and OpenCode (see [Hosts](#hosts)) | Archflow runs inside it | Everything |\n| Git | Branch-per-story workflow, release tags, the ship ritual | All phases |\n| Node.js 18+ | Archflow Studio and the `SessionStart` hook that ships with the plugin; some MCP servers too | Studio, hooks |\n\n### Recommended\n\n**[codemap](https://github.com/AZidan/codemap) — token optimization.** Archflow's agents navigate\nyour codebase through a structural index instead of reading whole files: `codemap find` locates a\nsymbol, `codemap show` gives a file's shape, and the agent then reads only the line ranges it needs.\nOn a real codebase that cuts token consumption on navigation by roughly 60-80%, which is the\ndifference between a story that fits in one context window and one that does not.\n\n```bash\npip install \"git+https://github.com/AZidan/codemap.git@v1.3.1\"\n```\n\nArchflow works without it. Every agent falls back to ordinary file search, and you will simply pay\nmore tokens per story. Run `/archflow:doctor` to see what is installed.\n\n### Per project type\n\n| Tool | Why | Needed for |\n|---|---|---|\n| Python 3 + PyYAML | Runs the v1.0 to v2.0 migration script | `/archflow:migrate` only |\n| An end-to-end test runner | `pm-reviewer` verifies acceptance criteria against the running app | `fullstack`, `frontend_only`, `mobile` |\n\nArchflow does not pick your e2e tool and never installs one. `pm-reviewer` uses whatever the project\nalready has — Playwright, Cypress, Detox, XCUITest, Espresso, Maestro, or a backend HTTP test stack.\nIf a project has none, it stops and asks you to choose rather than deciding for you.\n\n### Supply chain\n\nEverything Archflow can install from outside your machine is listed here, pinned to an immutable\nref. Nothing installs without asking you first.\n\n| Artifact | Source | Pin | Used by |\n|---|---|---|---|\n| codemap | `github.com/AZidan/codemap` | `v1.3.1` (`7e24f23ecbc7`) | Optional token optimization, all phases |\n| superdesign-mcp-claude-code | `github.com/AZidan/superdesign-mcp-claude-code` | `1bd2d1766b1e` | Phase 2.25 hi-fi screens (optional phase) |\n\nA `git+https://` or `npx github:` reference without a `@<ref>` or `#<ref>` tracks a moving branch,\nwhich means a compromise upstream reaches every user on their next install. If you edit one of those\nlines, keep the pin.\n\ncodemap is pinned to a **release tag** because it publishes releases. A tag is readable but mutable,\nso the commit it must resolve to is recorded beside it. Verify with:\n\n```bash\ngit ls-remote https://github.com/AZidan/codemap.git 'refs/tags/v1.3.1^{}'\n# expect 7e24f23ecbc74165d5d980b020fb69aa23d6cd95\n```\n\nsuperdesign-mcp-claude-code publishes no releases, so it stays pinned to a raw commit. To move\neither to a newer version, update the ref here, at the install site and in `SECURITY.md`, and note\nit in the changelog.\n\nArchflow never auto-updates either of these.\n\n### What Archflow runs on your machine\n\nArchflow drives your coding agent, Claude Code or one of the other hosts, so everything runs as ordinary tool calls you can see and approve:\n\n- **Git** — branch, commit, tag, and read history. It never merges to `main`; that stays yours.\n- **File writes** — inside `.archflow/`, `docs/`, `design-artifacts/`, and your source tree.\n- **Project commands** — your own test, build and lint scripts.\n- **One optional background process** — `codemap watch`, which keeps the index current. It is\n  opt-in, it starts only if codemap is installed, and `pkill -f \"codemap watch\"` stops it.\n- **An upgrade notice.** When the plugin updates ahead of your project's `.archflow/`, a\n  `SessionStart` hook says so before your first command, names what drifted, and points at\n  `/archflow:doctor --fix`. It goes quiet once the project is repaired.\n- **Two guard hooks, scoped to Archflow projects.** In a directory with an `.archflow/`, a\n  `PreToolUse` hook blocks a force-push to `main`, and any push, checkout or merge touching `main`\n  while an unattended `/archflow:autopilot` run is live. In any other repo it exits immediately and\n  changes nothing. A `Stop` hook warns when state files have drifted from their schemas. Both fail\n  open, so a bug in a guard can never break your session.\n- **Anonymous usage telemetry, on by default.** On every host and in `npx archflow install`,\n  Archflow sends session starts, which Archflow commands run, and the host, project type, version,\n  phase and mode, with a random id generated on your machine. It never sends project names, file\n  paths, file contents, prompts or command arguments. The first run says so once. Turn it off with\n  `/archflow:telemetry off` (your host's spelling of it) or `npx archflow telemetry off`, or set\n  `DO_NOT_TRACK=1`. It is off in CI. Turning it off with the command sends one last event recording\n  the opt-out, and nothing after; `DO_NOT_TRACK` and CI send nothing at all. The setting lives in\n  `~/.archflow/config.json` and applies to every project and every host.\n\nExternal code it can install is listed under [Supply chain](#supply-chain), and nothing there\ninstalls without asking you first.\n\nArchflow Studio needs Node.js 18+ and a project on schema v2.0. On Claude Code its chat also needs\nthe `claude` binary on your `PATH`, which you already have if Claude Code works; forward mode on the\nother hosts needs nothing more. A v1.0 project opens read-only until you take the one-button\nmigration Studio offers.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the mirrored-tree rule, how to add an agent or a\ncommand, and what an agent must never contain. Participation is covered by our\n[Code of Conduct](CODE_OF_CONDUCT.md), and security reports go through [SECURITY.md](SECURITY.md).\nRelease history is in [CHANGELOG.md](CHANGELOG.md).\n\n**Archflow Studio's files are generated, not authored here.** `plugin/server/`, `plugin/dist/`,\n`plugin/commands/studio.md` and `plugin/hooks/studio-session-context.mjs` are built in the\n[archflow-studio](https://github.com/AZidan/archflow-studio) repo and copied in by its\n`npm run sync:plugin`. Edits made directly in this repo are overwritten on the next sync. Run\n`npm run sync:plugin -- --check` there to detect drift. This adds roughly 5.6 MB to the plugin for\neveryone, including people who never open Studio, which is a deliberate tradeoff for one namespace\nand one install.\n\nContributions are welcome. Areas of interest:\n\n- **New agents**: Add specialized agents in `plugin/agents/` following the existing format, and\n  wire them into a phase file — an agent that no phase references can never be dispatched\n- **Phase improvements**: Refine phase instructions in `.archflow/phases/`\n- **MCP registry**: Add tool integrations in `skills/archflow/mcp-registry.yaml`\n- **Bug fixes**: Open an issue or submit a PR\n\n---\n\n## Community & Support\n\n- **Bug reports:** [GitHub Issues](https://github.com/AZidan/archflow/issues)\n- **Feature requests:** [GitHub Issues](https://github.com/AZidan/archflow/issues)\n- **Questions:** [GitHub Discussions](https://github.com/AZidan/archflow/discussions)\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n\n**Archflow: Because building software deserves structure, not chaos.**\n\n[Back to top](#archflow)\n\n</div>\n"}