git:20260909.4e760c0 to git:20260909.71021bd

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with this repository.

## Archflow Framework

This repository uses [Archflow](https://github.com/AZidan/archflow), a phase-based development

framework with a release-driven outer loop (schema v2.0).

**The framework flow is defined in a single agent-neutral base file:**

📖 **`.archflow/instructions.md`** — read it first. It is the always-injected CORE, deliberately

small. **`.archflow/reference.md`** holds the detail (release model, agent roster, rules in full) and

is read on demand rather than carried all session. It is the source of truth for how Archflow works:

core agents per phase, the release model (releases as the outer loop, backlog stubs, the per-story

readiness pipeline, quick/full modes), the command surface, the universal context files, and the

critical rules. Other coding-agent instruction files (this `CLAUDE.md`, a Cursor `.cursorrules`, a

Windsurf rules file, etc.) all point at `.archflow/instructions.md` rather than duplicating it — one

source, no drift.

Then load the current phase: read `.archflow/current-phase.yaml` → `phase_file`, and follow

`.archflow/phases/phase-{current}-{name}.md`.

## Commands

- `/archflow:status` — status + available commands

- `/archflow:init` / `/archflow:onboard` — set up a new / existing project

- `/archflow:migrate` — upgrade a v1.0 project to schema v2.0

- `/archflow:mode [quick|full]` — show/switch ceremony mode

- `/archflow:release [new|start|ship]` — manage releases

- `/archflow:groom [story-id]` — detail or refine a story (a backlog stub, or one already in a release)

- `/archflow:feature` — add a story to the backlog or active release

- `/archflow:autopilot` — run queued release stories unattended on one branch (interview, then silent)

- `/archflow:design [pick|list|name|story-id]` — the project's design system, and per-story screen design

- `/archflow:contract [story-id]` — the API contract architecture, and per-story endpoint specs

- `/archflow:doctor [--validate] [--fix]` — check environment + project state; `--fix` repairs drift

between the project and an upgraded plugin

- `/archflow:studio [stop|status|port <n>]` — open Archflow Studio, a local web workspace (beta)

- `/archflow:setup-mcp [tool]` — connect an external tool via MCP

All commands are namespaced (`/archflow:<name>`) and live in `plugin/commands/*.md`. There is no

argument-style `/archflow <sub>` — never document or suggest that form.

## Repository-specific rules

- Commit ONLY the changes you made — never `git add .` / all files.

- This repo mirrors framework files across two trees: `plugin/skills/archflow/` (the shipped

source) and `.archflow/` (this repo's own dogfood copy) — keep any edited framework file

identical in both. This includes `design-systems/`. (`plugin/.archflow/`, the root `skills/` and

`agents/` trees, and `skills/archflow.zip` are retired — the plugin is the only distribution.)

- Agents live in **`plugin/agents/` only** and are deliberately NOT mirrored. The marketplace ships

`./plugin`, so that is the single copy that reaches users, and Claude Code loads project agents

from `.claude/agents/`, which this repo does not use. Never recreate a second agents tree.