agentflow

Full-stack agent-driven development pipeline by AgentSoft. An npm-installable ecosystem of 48 specialized agents, 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.

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 → data-architect + ux-ui-designer (parallel) → software-architect → data-architect Phase 2 → 5 planners (parallel) → executors → 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 stage boundary and asks you to confirm before dispatching the next one. To opt into autopilot (no pauses between stages, only interrupted on knowledge-gap escalations and critical audit findings):

agentflow start --autopilot

Pipeline

| Stage | 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. Data Architecture | data-architect | Opus | max | ERD, data models, migrations | | 2a. Knowledge Mining | da-knowledge-miner | Sonnet | low | Prior data models from agent-knowledge + Obsidian | | 2b. Data Research | da-researcher | Sonnet | low | Database patterns, compliance, dialect features | | 2c. Validation | da-validator | Sonnet | low | Phase 1/Phase 2 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 | | 4. UX/UI Design | ux-ui-designer | Opus | max | Design system, screen specs | | 4a. Knowledge Mining | ux-knowledge-miner | Sonnet | low | Prior design patterns from agent-knowledge + Obsidian | | 4b. UX Research | ux-researcher | Sonnet | low | Accessibility standards, design trends, patterns | | 4c. Validation | ux-validator | Sonnet | low | Design token consistency and completeness check | | 4d. Pencil Rendering | ux-renderer-pencil | Sonnet | low | Render designs into .pen files | | 4e. Stitch Rendering | ux-renderer-stitch | Sonnet | low | Render designs into Stitch cloud project | | 4f. Figma Rendering | ux-renderer-figma | Sonnet | low | Render designs into Figma files | | 5a. Backend Planning | backend-planner | Opus | max | OpenSpec tasks for NestJS hexagonal | | 5b. Frontend Planning | frontend-planner | Opus | max | OpenSpec tasks for React/Next.js | | 5c. Mobile Planning | mobile-planner | Opus | max | OpenSpec tasks for Flutter | | 5d. DevOps Planning | devops-planner | Opus | max | OpenSpec tasks for infrastructure | | 5e. QA Planning | qa-planner | Sonnet | low | Test matrix from BA, SA, UX requirements | | 6a. Backend Execution | backend-executor | Sonnet | high | Executes NestJS tasks from skills | | 6a.1 Backend QA Gate | backend-tester | Sonnet | low | Build, test, lint, coverage gate before senior review | | 6b. Frontend Execution | frontend-executor | Sonnet | high | Executes React/Next.js tasks | | 6b.1 Frontend QA Gate | frontend-tester | Sonnet | low | Typecheck, build, test, lint, coverage gate before senior review | | 6c. Mobile Execution | mobile-executor | Sonnet | high | Executes Flutter tasks | | 6c.1 Mobile QA Gate | mobile-tester | Sonnet | low | Analyze, test, build, UI verification gate before senior review | | 6d. DevOps Execution | devops-executor | Sonnet | high | Executes IaC tasks from skills | | 7. QA Execution | qa-orchestrator | Opus | medium | Matrix-driven test execution, dispatches specialists | | 7a. Unit/Integration | qa-unit-integration | Sonnet | low | Service/module-level tests | | 7b. API Tests | qa-api | Sonnet | low | REST/GraphQL endpoint tests | | 7c. Browser E2E | qa-e2e-browser | Sonnet | low | Playwright browser tests | | 7d. Mobile E2E | qa-e2e-mobile | Sonnet | low | Mobile device E2E tests |

Orchestration modes (via product-owner)

| Mode | Behavior | Invocation | |------|----------|------------| | Autopilot | No pauses between stages. User is only interrupted on knowledge-gap escalations and critical audit findings. | agentflow start --autopilot | | Stage-gate | Pauses after each stage 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 stage'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 stage-by-stage with your own direction, or iterate on one stage 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)
Stage: 2 (Data Architecture Phase 1)
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-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

• Stages 1–4 produce documentation only — never code
• Stage 5: Senior agents produce OpenSpec task lists; qa-planner produces the test matrix (never code)
• Stage 6 executor agents consume tasks + skills to produce code
• Stage 7 QA validates via testing pyramid

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 | business-analyst, ux-ui-designer, data-architect, software-architect, qa-orchestrator | Dual-write publishing of deliverables to Notion (optional — local markdown is always the primary deliverable) | | 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

Reference templates are bundled as skills under skills/ and loaded on demand:

| Skill | Used by | Contents | |-------|---------|----------| | backend:nestjs-hexagonal | backend-executor, backend-planner | NestJS Hexagonal + DDD + CQRS templates | | 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 | | obsidian-cli | All agents with Obsidian memory | Obsidian CLI command reference | | business-analysis:process | business-analyst | Collaborative discovery + self-review | | data-architecture:process | data-architect | Collaborative discovery + self-review | | software-architecture:process | software-architect | Collaborative discovery + self-review | | ux-ui-design:process | ux-ui-designer | Collaborative discovery + self-review | | 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 | | pipeline:change-propagation | All domain experts + planners | Cross-stage change manifests and blast-radius protocol |

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.