agentflow

Full-stack agent-driven development pipeline by AgentSoft. An npm-installable ecosystem of 52 specialized agents, 130+ skills, and bundled MCP servers that runs on top of Claude Code. A single product-owner agent orchestrates the full pipeline — from discovery through deployment — by spawning specialist sub-agents and coordinating them via a shared MCP bus.

Agents are thin contracts: each agent body declares what it owns, and a per-phase skill family (<domain>:<phase>) tells it how. Cross-cutting concerns (memory protocol, PO bus mode, audit-fix protocol, project registry) live in shared agentflow:* skills so every agent applies them the same way.

Installation

Prerequisites

The installer will detect these and offer to install the ones it can:

• Node.js ≥18
• Claude Code CLI
• tmux ≥3.0 (agent-term bridge)
• Docker — optional, only needed if you use agent-vault
• pnpm — optional

Install

npm install -g @agentsoft/agentflow
agentflow init

agentflow init is interactive:

1. Detects prerequisites; offers to install missing ones via your platform's package manager (brew on macOS; apt / dnf / pacman on Linux).
2. Asks whether to install user-global (~/.claude/) or project-local (<cwd>/.claude/).
3. Copies agent definitions, skills, and hooks into the chosen scope.
4. Registers agent-knowledge, agent-memory, and agent-vault as MCP servers via claude mcp add.

Health check

agentflow doctor

Read-only check of prereqs, installed files, and MCP registrations.

Update

agentflow update

Bumps the bundled dependency packages (agent-term, agent-knowledge, agent-memory, agent-vault) and re-copies agent/skill/hook files. Note: user edits to copied files are overwritten silently. If you edit agent definitions, version-control ~/.claude/ as part of your dotfiles.

Uninstall

agentflow uninstall

Removes agentflow-installed files (not your own files). Optionally uninstalls the npm packages.

Quickstart

Once installed, the fastest way to go from idea to running code is to start the product-owner agent. It interviews you for a product brief, then drives the whole pipeline on your behalf.

# 1. Make sure you're healthy (one-time)
agentflow doctor

# 2. Go to a clean directory where deliverables will be written
mkdir my-new-app && cd my-new-app

# 3. Start the orchestrator (interactive)
agentflow start

What happens next:

1. Discovery (~10–15 minutes) — product-owner interviews you: product name, problem, users, metrics, constraints, tech preferences, deployment target, then 3–5 adaptive follow-ups. Produces agentflow-control/Product_Brief/product-brief.md.
2. Pipeline orchestration — product-owner spawns specialists in sequence: project-manager (Linear / Jira / Wrike) → business-analyst → ux-ui-designer + data-architect (parallel) → software-architect → 6 Phase 4 tracks in parallel (backend, frontend, mobile, devops, dba, qa-planner) → qa-orchestrator → senior-auditor. Each specialist runs in its own agent-term tmux session; you can watch them with agent-term list and agent-term logs <name>.
3. Your role during the run — you're only interrupted when a specialist asks product-owner something product-owner can't answer from your discovery brief. You see a formatted ─── ESCALATION ─── block in the terminal; you type the answer; the specialist resumes.
4. End of run — product-owner writes a run-summary to your Obsidian vault (at memory - product-owner - <project> - run-<date>) and stops all spawned tmux sessions.

By default, product-owner runs in stage-gate mode — it pauses after each phase boundary and asks you to confirm before dispatching the next one. To opt into autopilot (no pauses between phases, only interrupted on knowledge-gap escalations and critical audit findings):

agentflow start --autopilot

Pipeline

| Phase | Agent | Model | Effort | Role | |-------|-------|-------|--------|------| | 0. Orchestration | product-owner | Opus | max | Discovery with user, then end-to-end pipeline orchestration. Two modes: autopilot, stage-gate. Spawns all downstream agents as subprocess Claude sessions wired to the agentflow-bus MCP server. | | 1. Business Analysis | business-analyst | Opus | max | Domain modeling, requirements, business rules | | 1a. Domain Research | ba-researcher | Sonnet | low | Web research for industry/regulation/terminology | | 1b. Knowledge Mining | ba-knowledge-miner | Sonnet | low | Prior context from agent-knowledge + Obsidian | | 1c. Validation | ba-validator | Sonnet | low | Deliverable consistency and completeness check | | 2-A. UX/UI Design | ux-ui-designer | Opus | max | Design system, screen specs | | 2-A.a Knowledge Mining | ux-knowledge-miner | Sonnet | low | Prior design patterns from agent-knowledge + Obsidian | | 2-A.b UX Research | ux-researcher | Sonnet | low | Accessibility standards, design trends, patterns | | 2-A.c Validation | ux-validator | Sonnet | low | Design token consistency and completeness check | | 2-A.d Pencil Rendering | ux-renderer-pencil | Sonnet | low | Render designs into .pen files | | 2-A.e Stitch Rendering | ux-renderer-stitch | Sonnet | low | Render designs into Stitch cloud project | | 2-A.f Figma Rendering | ux-renderer-figma | Sonnet | low | Render designs into Figma files | | 2-B. Data Architecture (logical) | data-architect | Opus | max | Conceptual + logical ERD, entities, invariants, normalization (logical only — no migrations) | | 2-B.a Knowledge Mining | da-knowledge-miner | Sonnet | low | Prior data models from agent-knowledge + Obsidian | | 2-B.b Data Research | da-researcher | Sonnet | low | Database patterns, compliance, dialect features | | 2-B.c Validation | da-validator | Sonnet | low | Logical-model deliverable validation | | 3. Software Architecture | software-architect | Opus | max | C4 diagrams, API contracts, tech stack | | 3a. Knowledge Mining | sa-knowledge-miner | Sonnet | low | Prior arch decisions from agent-knowledge + Obsidian | | 3b. Architecture Research | sa-researcher | Sonnet | low | Industry patterns, reference architectures, best practices | | 3c. API Contract Drafting | sa-api-drafter | Sonnet | low | OpenAPI 3.1 YAML + API reference from design notes | | 3d. Diagram Drafting | sa-diagram-drafter | Sonnet | low | draw.io XML + Mermaid from diagram descriptions | | 3e. Architecture Validation | sa-validator | Sonnet | low | Cross-deliverable consistency + upstream traceability | | 4a. Backend Track | backend-planner → backend-executor → backend-tester | Opus + Sonnet | max + high + low | NestJS hexagonal — plan, execute, gate | | 4b. Frontend Track | frontend-planner → frontend-executor → frontend-tester | Opus + Sonnet | max + high + low | React/Next.js — plan, execute, gate | | 4c. Mobile Track | mobile-planner → mobile-executor → mobile-tester | Opus + Sonnet | max + high + low | Flutter — plan, execute, gate | | 4d. DevOps Track | devops-planner → devops-executor | Opus + Sonnet | max + high | Terraform/Docker/CI-CD — plan, execute | | 4e. DBA Track | dba-planner → dba-executor → dba-tester | Opus + Sonnet | max + high + low | Migrations, seeders, factory specs, indexes — plan, execute, smoke-test gate. Migrations are the schema source of truth. | | 4f. QA Planning | qa-planner | Sonnet | low | Test matrix from BA, SA, UX requirements | | 5. QA Execution | qa-orchestrator | Opus | medium | Matrix-driven test execution, dispatches specialists | | 5a. Unit/Integration | qa-unit-integration | Sonnet | low | Service/module-level tests | | 5b. API Tests | qa-api | Sonnet | low | REST/GraphQL endpoint tests | | 5c. Browser E2E | qa-e2e-browser | Sonnet | low | Playwright browser tests | | 5d. Mobile E2E | qa-e2e-mobile | Sonnet | low | Mobile device E2E tests | | 6. Audit | senior-auditor | Opus | max | Audit orchestrator, dispatches sub-auditors, consolidates reports, phase gates |

Orchestration modes (via product-owner)

| Mode | Behavior | Invocation | |------|----------|------------| | Autopilot | No pauses between phases. User is only interrupted on knowledge-gap escalations and critical audit findings. | agentflow start --autopilot | | Stage-gate | Pauses after each phase boundary. User types y / ask N / skip / abort to advance. | agentflow start |

Both modes begin with a required discovery conversation that produces agentflow-control/Product_Brief/product-brief.md. Specialists downstream interview product-owner (via the agentflow-bus MCP server), not the user.

Running individual agents (manual dispatch)

You can also invoke any specialist directly without product-owner orchestration. The specialist will interview you (not product-owner) and produce its own phase's deliverables:

# Business analysis only
claude --agent business-analyst

# Data architecture (requires business-analysis deliverables)
claude --agent data-architect

# ... etc. for any agent listed in the pipeline table

This is useful when you want to work phase-by-phase with your own direction, or iterate on one phase without triggering the full pipeline.

Monitoring a product-owner run

While product-owner is running, specialists execute in background agent-term tmux sessions. You can observe them from a second terminal:

# List all running specialists
agent-term list

# Tail a specific specialist's output
agent-term logs agentflow-<project>-<agent>-<short-id>

# Kill a stuck specialist (rare)
agent-term kill <name>

Responding to escalations

When product-owner needs input, it prints a block like:

─── ESCALATION [1/1] ────────────────────────────────────────────
From: data-architect (session da-a9c3)
Phase: 2-B (Data Architecture — logical)
Reason: knowledge gap (ask_po fallback)
Question: Should audit trails be stored in the same database as
          operational data, or a separate warehouse?
PO's partial view: brief mentions "compliance required" but no
                   retention details.
─────────────────────────────────────────────────────────────────
Your answer:

Type a free-form answer. The specialist's blocked MCP tool call resolves with your response and it continues.

Critical audit findings use a different header (─── CRITICAL AUDIT ESCALATION ───) and include the full auditor report for your review.

Cross-cutting agents

| Agent | Model | Effort | Role | |-------|-------|--------|------| | senior-auditor | Opus | max | Audit orchestrator, dispatches sub-auditors, consolidates reports, phase gates | | audit-design-alignment | Sonnet | max | Full pipeline traceability verification (BA→DA→SA→UX→Plans) | | audit-security | Sonnet | max | OWASP Top 10 security review | | audit-compliance | Sonnet | max | Audit entry validation, decision chains, risk classification | | audit-code-quality-backend | Sonnet | max | NestJS/TypeScript code quality review | | audit-code-quality-frontend | Sonnet | max | React/Next.js code quality review | | audit-code-quality-mobile | Sonnet | max | Flutter/Dart code quality review | | audit-code-quality-database | Sonnet | max | Database/migration quality (safety, indexes, dialect best practices, schema-vs-logical-model alignment) | | audit-design-implementation | Sonnet | max | Verify code matches UX design specs (structural + visual) | | project-manager | Sonnet | low | PM provider sync (Linear / Jira / Wrike), progress tracking |

Switching PM providers

The provider is chosen at project creation via PO discovery Q9 (or directly: create project X using jira). Once set, it is locked — the provider cannot be changed in-place for a given project. To use a different provider, archive the project and re-initialize with the new provider.

Supported providers (v1):

• Linear — stdio MCP, uses LINEAR_API_KEY from agent-vault.
• Jira — stdio MCP via the official Atlassian MCP, uses ATLASSIAN_OAUTH_TOKEN + cloudId.
• Wrike — hosted SSE MCP at https://mcp.wrike.com/app/mcp/sse, uses WRIKE_OAUTH_TOKEN.

The selected provider is stored in the Obsidian project registry frontmatter as pmProvider: <provider> and is read by agentflow-spawn when narrowing the PM session's MCP config.

Docs Providers

Deliverables (BA analyses, SA diagrams + prose, UX specs, QA test matrices, audit reports, PM summaries) can be published to either Notion or Confluence, on a per-project basis. The choice is captured during PO discovery and stored in the Obsidian project registry (docsProvider: notion | confluence + a docs: block with the provider-specific root).

| Provider | Tool surface | Images | |---|---|---| | Notion | Notion:* MCP | Inline upload | | Confluence | Atlassian MCP (shared with Jira) | URL reference via docs.docsImageBaseUrl |

Switching providers on an existing project requires editing the docs: block in the registry. No migration is provided — new writes go to the new provider; prior content stays where it was.

Conventions

• Phases 1, 2-A, 2-B, 3 produce documentation only — never code
• Phase 4 — Development: all six tracks (backend, frontend, mobile, devops, dba, qa-planner) run in parallel; within each track, planner → executor → tester is sequential (DBA is a full trio: dba-planner → dba-executor → dba-tester, with the tester running the migration smoke test)
• Phase 5 — QA Execution validates via testing pyramid
• Phase 6 — Audit can run after any phase; final pass is gate-style

Pipeline Topology

See docs/pipeline-topology.md for the canonical pipeline DAG, dispatch cheat sheet, and change propagation guide.

Bundled MCP Servers

| Server | Key | Purpose | |--------|-----|---------| | agent-knowledge | mcp__agent-knowledge__* | Semantic knowledge base — context recall across all agents (ingest, search, find-existing, relate, analyze) | | agent-memory | mcp__agent-memory__* | Obsidian-backed persistent memory vault (read, list, search, tag, backlinks, create, append, delete, move, property-set/remove) | | agent-vault | mcp__agent-vault__* | Secure secret management (get, set, delete, list, exists) | | chrome-devtools | mcp__chrome-devtools__* | Browser control for E2E testing | | mobile-mcp | mcp__mobile-mcp__* | Mobile device interaction | | pencil | mcp__pencil__* | Design file reading/writing (.pen files) | | drawio | mcp__drawio__* | Draw.io diagram preview | | linear-server | mcp__linear-server__* | Linear project management (when pmProvider is linear) | | atlassian-mcp | mcp__atlassian__* | Jira project management (when pmProvider is jira) | | wrike-mcp | mcp__wrike__* | Wrike project management (when pmProvider is wrike) | | playwright | mcp__playwright__* | Playwright browser automation (qa-e2e-browser) | | context7 | mcp__plugin_context7__* | Up-to-date library documentation |

Bundled CLIs (installed by npm install -g @agentsoft/agentflow)

| Command | Purpose | |---------|---------| | agentflow-bus serve | Start the PO↔specialist message-bus MCP server (HTTP transport, dynamic port). PO launches this automatically via agent-term. | | agentflow-spawn <agent> | Spawn a specialist Claude session into an agent-term tmux window, wired to the bus. Used internally by product-owner. |

External MCP Dependencies

These servers are not bundled — configure them separately:

| Server | Used by | Purpose | |--------|---------|---------| | Notion | All docs-writing agents (BA, DA, SA, UX, qa-planner, qa-orchestrator, senior-auditor, PM) via docs-writer:provider-notion when docsProvider=notion | Per-project deliverable publishing. Atlassian Confluence is the alternative provider (shares the Jira MCP). Local markdown is always the primary deliverable; the provider is the dual-write target. | | Stitch | ux-renderer-stitch, audit-design-alignment | Cloud-based design rendering and screen management | | Figma | ux-renderer-figma | Figma file design rendering and variable management |

Skills

Skills live under skills/ and are loaded on demand. Agent bodies are thin contracts that declare what they own; skills carry the how. The tables below group skills by where they sit in the pipeline.

Cross-cutting / foundational

Used by every agent or every track that participates in the contract.

| Skill | Used by | Contents | |-------|---------|----------| | agentflow:memory-protocol | All producers + planners + orchestrators | Standard Obsidian/agent-knowledge write protocol — when to ingest, what to tag, how to backlink | | agentflow:bus-mode | All specialists + planners + orchestrators | Detect PO orchestration (mcp__agentflow-bus__* present) and route interviews through ask_po instead of asking the user | | agentflow:audit-fix-protocol | All audited agents | Read audit-gates/<phase>/<stage>.json, enter Audit Fix Mode, write AUDIT_FIXES.md, re-signal completion | | agentflow:project-registry | All agents that stamp decisions | Standard reader/writer protocol for agentflow-control/ProjectRegistry/<ProjectName>.md (PM bootstraps; downstream agents append decision rows) | | docs-writer:process | All docs-writing agents (BA, DA, SA, UX, qa-planner, qa-orchestrator, senior-auditor, PM) | Provider resolution from project registry + preflight + interactive setup; dispatches to docs-writer:provider-<name> via the 6-procedure contract | | docs-writer:provider-notion | (Internal — called by docs-writer:process) | Notion implementation of the 6-procedure docs contract | | docs-writer:provider-confluence | (Internal — called by docs-writer:process) | Atlassian Confluence implementation of the 6-procedure docs contract | | pipeline:stack-detection | product-owner, senior-auditor, planners | Detect backend/frontend/mobile/dba/devops stacks present in the workspace; derive the planner + sub-auditor roster | | pipeline:audit-severity | senior-auditor, audit-code-quality:, audit-design-implementation: | Shared CRITICAL/HIGH/MEDIUM/LOW severity vocabulary + rollup rules | | pipeline:change-propagation | All domain experts + planners | Cross-stage change manifests and blast-radius protocol | | obsidian-cli | (Out-of-agent admin only) | Ad-hoc Obsidian-vault bash scripting. Agents use mcp__agent-memory__memory_* instead. |

Phase 1 — Business Analysis

| Skill | Used by | Contents | |-------|---------|----------| | business-analysis:depth-detection / :discovery / :methodology / :deliverables / :validation | business-analyst | Phase pipeline — depth gate (lightweight vs full DDD), discovery interview, DDD methodology, deliverables, validation gate | | business-analysis:*-templates (domain-overview / business-rules / business-process / use-case / scenario / domain-model / domain-entities) + :event-storming + :context-mapping | business-analyst | Per-deliverable templates + event-storming notation + bounded-context mapping rules |

Phase 2-A — UX/UI Design

| Skill | Used by | Contents | |-------|---------|----------| | ux-ui-design:discovery / :deliverables / :validation / :rendering | ux-ui-designer | Tier-2 UX workflow (discovery gate, deliverables, validation gate, STATE_MATRIX rendering + publish-once) | | ux-ui-design:dependency-contract + :*-template (screen-spec / theme-properties / component-spec / design-tokens / layout-patterns / user-flows) | ux-ui-designer | Gap/citation protocol + per-deliverable spec-format templates | | ux-post-code-changes | ux-ui-designer + frontend-planner + mobile-planner | Recovery flow when UX changes after code already shipped (replay through implementation + audit-design-implementation) |

Phase 2-B — Data Architecture (logical)

| Skill | Used by | Contents | |-------|---------|----------| | data-architecture:discovery / :methodology / :deliverables / :validation | data-architect | Tier-2 logical data-architecture workflow (discovery gate, DDD methodology, deliverables, validation gate) | | data-architecture:dependency-contract + :ddd-data-modeling + :erd-diagrams | data-architect | Upstream-citation protocol + DDD→data modeling + draw.io ERD authoring | | data-architecture:*-templates (conceptual-model / logical-model / data-flows / data-integrity / governance / physical-design) | data-architect | Per-deliverable templates (logical-model is the source of truth the DBA track conforms to) |

Phase 3 — Software Architecture

| Skill | Used by | Contents | |-------|---------|----------| | software-architecture:discovery / :deliverables / :validation | software-architect | Tier-2 SA workflow (discovery gate, deliverables + drafter dispatch, validation gate) | | software-architecture:dependency-contract + :*-template (c4-context / c4-container / sequence / api-design / tech-stack / cross-cutting) | software-architect | Gap/citation protocol + per-deliverable design-note templates |

Phase 4 — Shared development contract

The dev:* family is the shared planner → executor → tester contract every Phase 4 stack uses.

| Skill | Used by | Contents | |-------|---------|----------| | dev:writing-plans | All planners | Author Development/<feature-slug>/plan.md — Source / Justified by / Stack headers, task IDs, Acceptance blocks | | dev:using-worktrees | All executors | Open .worktrees/<feature-slug> on dev/<feature-slug> before TASK-001 | | dev:executing-plans | All executors | Flip task status [ ]→[~]→[x]; respect plan ordering; one task per commit | | dev:verification-before-completion | All testers | Run static, build, unit, integration gates per stack before signaling PASS | | dev:finishing-branch | All testers | Present 4 finishing options (merge / PR / keep / discard) once the tester PASSes | | dev:systematic-debugging | All planners (on QA FAIL) | Root-cause loop; append ## Debug section to plan.md; re-dispatch executor for fix-only tasks |

Phase 4 — Backend (NestJS Hexagonal)

| Skill | Used by | Contents | |-------|---------|----------| | backend:nestjs-hexagonal | backend-executor, backend-planner | NestJS Hexagonal + DDD + CQRS templates | | backend:plan-authoring | backend-planner | C4 L3-4 backend docs + plan authoring (module-grouped, layer order) | | backend:architectural-review | backend-planner | Architectural review criteria/loop + executor↔tester verdict handling | | backend:dependency-contract | backend-planner | Gap detection + upstream-justification citations for plan.md | | backend:layer-rules | backend-planner | Hexagonal import-boundary hard constraints (shared) |

Phase 4 — Frontend (React / Next.js)

| Skill | Used by | Contents | |-------|---------|----------| | frontend:plan-authoring | frontend-planner | Analyze UX+SA, decompose screens, C4 L3-4, author plan.md | | frontend:layer-rules | frontend-planner | Hexagonal + atomic-design + DI import-boundary rules (shared) | | frontend:design-tokens | frontend-planner | Design-token → Tailwind/CSS mapping table + .pen extraction | | frontend:architectural-review | frontend-planner | Review criteria/loop + executor↔tester verdict handling | | frontend:dependency-contract | frontend-planner | Gap detection + upstream-justification citations for plan.md | | frontend:security-planning | frontend-planner | Per-page security posture + SERVER/CLIENT designation |

Phase 4 — Mobile (Flutter)

| Skill | Used by | Contents | |-------|---------|----------| | mobile:plan-authoring | mobile-planner | Analyze UX+SA, decompose features, state & data flow, C4 L3-4, author plan.md | | mobile:layer-rules | mobile-planner | Flutter Clean-Architecture feature-first + injectable/get_it DI rules (shared) | | mobile:design-tokens | mobile-planner | Design-token → Flutter ThemeData mapping table + .pen extraction | | mobile:architectural-review | mobile-planner | Review criteria/loop + executor↔tester verdict handling | | mobile:dependency-contract | mobile-planner | Gap detection + upstream-justification citations for plan.md |

Phase 4 — DevOps (Cloud / IaC)

| Skill | Used by | Contents | |-------|---------|----------| | devops-cloud:terraform | devops-executor, devops-planner | Terraform provider, backend, module, variables, outputs | | devops-cloud:docker | devops-executor, devops-planner | Dockerfile, docker-compose | | devops-cloud:ci-cd | devops-executor, devops-planner | GitHub Actions, GitLab CI, Cloud Build | | devops-cloud:scripts | devops-executor, devops-planner | deploy.sh, setup-env.sh | | devops-cloud:infra-planning / :infra-review / :provisioning-protocol | devops-planner | Plan authoring + C4 infra docs, architectural review loop, provisioning approval protocol | | devops-cloud:ports-registry | devops-planner, devops-executor | Per-project Obsidian port/env/topology registry (single source of truth across sessions) |

Phase 4 — Database (DBA track)

| Skill | Used by | Contents | |-------|---------|----------| | database:dialect-gate | dba-planner | Relational → proceed via SQL track; document (MongoDB) → branch into mongo skills | | database:migration-planning | dba-planner | Topological migration ordering, FK deps, migrations-are-schema-source-of-truth rule | | database:postgres-migrations | dba-planner, dba-executor, audit-code-quality-database | Postgres transactional DDL, index types, partitioning, JSONB, online DDL | | database:mysql-migrations | dba-planner, dba-executor, audit-code-quality-database | MySQL/InnoDB online DDL (INSTANT/INPLACE), generated columns, JSON, partitioning | | database:sqlserver-migrations | dba-planner, dba-executor, audit-code-quality-database | T-SQL DDL, online index ops, filtered/included-column indexes, partitioning | | database:mongo-schema | dba-planner, dba-executor, audit-code-quality-database | MongoDB schema versioning via up.js / down.js mongosh change scripts | | database:seed-and-factories | dba-planner, dba-executor | Idempotent dev + test seed datasets, the runnable seeder mechanism, factory specs (SQL track) | | database:mongo-seed-and-factories | dba-planner, dba-executor | Mongo equivalent — idempotent seeders + factory specs | | database:smoke-test | dba-tester | Ephemeral-DB up/down round-trip + rollback verify + seeder smoke (HARD STOP) | | database:mongo-smoke-test | dba-tester | Mongo equivalent — apply/reverse .js change scripts + seeder smoke | | database:index-recommendations | dba-planner | API-driven index derivation from openapi.yaml query patterns | | database:cross-context-contracts | dba-planner | Event/API contract validation across bounded contexts |

Phase 4/5 — QA

| Skill | Used by | Contents | |-------|---------|----------| | qa:test-classification | qa-planner, qa-orchestrator | Shared Layer/Owner → specialist routing + Priority + Test-Type rules | | qa:test-design | qa-planner | Mode detect + read BA/SA/UX/DBA-seed + derive & classify test cases | | qa:matrix-authoring | qa-planner | Build + render + publish the test matrix, stamp pageId, ingest (layer: qa) | | qa:execution-dispatch | qa-orchestrator | Read matrix + status-normalize + preflight gates + group by Layer + test-code-location resolution + specialist prompt/ordering/MCP-check + re-dispatch | | qa:matrix-update | qa-orchestrator | Merge Status/Evidence + status transitions + flaky-test trail + write canonical workspace file + re-render via docs-writer:process | | qa:result-reporting | qa-orchestrator | Coverage thresholds + aggregate ---REPORT--- blocks + AMBIGUOUS resolution + QA report template with regression deltas |

Phase 6 — Audit

| Skill | Used by | Contents | |-------|---------|----------| | audit:dispatch | senior-auditor | Scope + pipeline:stack-detection + sub-auditor team/dispatch matrix/single-parallel-batch + re-dispatch | | audit:consolidation | senior-auditor | JSON-first findings parse + severity rollups (pipeline:audit-severity) + code-quality-skip + ambiguity resolution | | audit:reporting | senior-auditor | Publish via docs-writer:process + the full stage-organized report template + overall-status rules + present | | audit:gates | senior-auditor | Audit entries + AUDIT_FIXES.md review + gate cascade (dependency map + topological status) + audit-gates/*.json mirror + index + PM notify + critical escalation | | audit-code-quality:nestjs | audit-code-quality-backend | NestJS quality check catalog | | audit-code-quality:react-nextjs | audit-code-quality-frontend | React/Next.js quality check catalog | | audit-code-quality:flutter | audit-code-quality-mobile | Flutter quality check catalog | | audit-design-implementation:react-nextjs | audit-design-implementation | React/Next.js design fidelity checks | | audit-design-implementation:flutter | audit-design-implementation | Flutter design fidelity checks |

Orchestrator (Phase 0)

| Skill | Used by | Contents | |-------|---------|----------| | product-owner:discovery | product-owner | Pre-flight memory + structured/adaptive interview (Q1–Q9 + Q10 docs-provider with conditional Q10b) + Product Brief + knowledge_ingest (tag: product-brief) + git commit | | product-owner:run-setup | product-owner | BUS_URL / BUS_TMUX_NAME env-handoff check + filesystem registry stub at agentflow-control/ProjectRegistry/<ProjectName>.md | | product-owner:dispatch | product-owner | 8-step dispatch DAG (cites pipeline:stack-detection for the planner roster) + per-specialist agentflow-spawn mechanics + handoff to PM + bootstrap-prompt template | | product-owner:orchestration-loop | product-owner | po_poll hot loop + Stage-gate UX with 4 reply codes + standard + CRITICAL AUDIT ESCALATION block formats + 4-row audit retry policy | | product-owner:teardown | product-owner | End-of-run Obsidian writes (run-summary + lesson) + specialist tmux teardown (NOT the bus) + signal-handler hygiene (abort path skips run-summary) |

Project Manager (cross-cutting, long-lived)

| Skill | Used by | Contents | |-------|---------|----------| | project-manager:contract | project-manager | The 12-procedure Provider Contract + Two Modes (Command/Audit) + Two-File Memory Model (registry + working note + snapshots) + Pipeline Entry Point note + Error Handling catalog | | project-manager:provider-resolution | project-manager | Steps 0–5 of provider resolution + HARD GATE lock-enforcement (stub vs registry mismatch → ABORT with migration message); dispatches to the matching :provider-<name> | | project-manager:init | project-manager | Project Initialization Steps 1–11 + Project Summary Template + PM Working Note schema (creates the shared registry; populates ### Product Owner from PO's brief; stamps docs: block) | | project-manager:audit | project-manager | Long-lived audit cadence (3600s loop in bus mode) + 8-step Audit Procedure + Audit Gate Sync + audit-snapshot schema + Working-Note Updates + agent-term-injected audit-fix branch | | project-manager:commands | project-manager | Phase Management + Issue Management (blocker/mark-done/what's-left/audit-status) + Archive + Trend & History + Daily Log Procedure-11/12 wrappers | | project-manager:daily-log | project-manager | Notion calendar entry per day — parent + per-project sub-pages with 8 activity sources (commits, deliverables, audits, tickets, OpenSpec, decisions, QA, free-form). Driven by agentflow pm-daily-log. | | project-manager:provider-linear | (Internal — called by :provider-resolution) | Linear implementation of the 12-procedure PM provider contract | | project-manager:provider-jira | (Internal — called by :provider-resolution) | Jira implementation of the 12-procedure PM provider contract (via Atlassian MCP) | | project-manager:provider-wrike | (Internal — called by :provider-resolution) | Wrike implementation of the 12-procedure PM provider contract (via hosted Wrike SSE MCP) |

Agent Permissions

All agents use permissionMode: dontAsk — tools not in the tools: allowlist are silently blocked. See PERMISSIONS.md for the full permission table.

Memory

Agents use two complementary memory systems:

• agent-knowledge — semantic knowledge base for cross-session context recall. Producers ingest deliverables; consumers search by project name and layer tag (business, data, software-arch, ux-ui, infrastructure).
• agent-memory — Obsidian-backed persistent memory for per-agent notes, project registries, and decision logs. All filesystem-level memory writes now go through mcp__agent-memory__memory_* tools.

Versioning

Releases follow Conventional Commits enforced via commitlint + husky. Use:

pnpm release          # auto-detects bump from commits
pnpm release:minor    # force minor bump
pnpm release:major    # force major bump
pnpm release:patch    # force patch bump

Then push with git push --follow-tags origin main.

Migration from ~/.claude/agents/

If you were using agents directly from ~/.claude/agents/:

1. Install agentflow (see above)
2. Start a new Claude Code session and verify the pipeline context appears
3. Delete the agent .md files from ~/.claude/agents/ that agentflow now provides
4. Delete ~/.claude/agents/references/ if it exists — templates are now skills

Rollback

agentflow uninstall
# When prompted, confirm npm package removal to fully roll back.

Troubleshooting

agentflow doctor reports "Claude Code CLI" as missing

The installer does not auto-install Claude Code itself. Install it from claude.com/claude-code, then re-run agentflow doctor.

agentflow doctor reports an optional prereq as missing

Optional prereqs (Docker, pnpm) are only flagged, not required. You can safely proceed without them unless you plan to use agent-vault (needs Docker for Infisical).

MCP server agent-knowledge, agent-memory, or agent-vault shows as not connected in Claude Code

Check registration:

claude mcp list

You should see all three in the user or project scope. If not:

# Re-register (global)
claude mcp add agent-knowledge --scope user -- agent-knowledge serve
claude mcp add agent-memory --scope user -- agent-memory serve
claude mcp add agent-vault --scope user -- agent-vault serve

Or run agentflow update which re-registers all three.

Spawned specialist reports "Permissions required for agentflow-bus MCP tools"

This means --allowedTools wasn't passed to claude. agentflow-spawn adds it automatically; if you're invoking claude manually against a bus, add:

claude --agent <specialist> \
  --mcp-config <bus-config.json> \
  --allowedTools "mcp__agentflow-bus__ask_po mcp__agentflow-bus__escalate_to_human mcp__agentflow-bus__signal_complete" \
  --permission-mode dontAsk \
  "<prompt>"

The agent's frontmatter tools: allowlist does NOT auto-approve MCP servers declared via --mcp-config; the CLI flag is required.

agent-term session disappeared or specialist is unresponsive

# Check what's alive
agent-term list

# Tail logs if the terminal still exists
agent-term logs <name>

# Force-kill if stuck
agent-term kill <name>

Product-owner will detect the missing session and either retry (on stage-gate) or escalate to you (on autopilot).

Bus port conflict on re-run

The bus picks a dynamic port, so port conflicts are rare. If agentflow-bus-* terminals from a prior run are still active:

agent-term list | grep agentflow-bus
agent-term kill <stale-name>

Edits to installed agent files disappeared after agentflow update

update overwrites copied files silently (by design). If you edit agent definitions, version-control your ~/.claude/ directory (or install project-local) so your edits survive.

agentflow uninstall left some files behind

uninstall only removes files it tracked in the install manifest (.agentflow-install.json). Files you added to ~/.claude/agents/ yourself are preserved intentionally — this is the safety guarantee.

License

UNLICENSED — Internal use only.