agents-factory

Agents Factory

A project-agnostic, multi-agent software-delivery framework. It takes a plain-language description of a product (a Stakeholder Input Packet) and carries it to a deployed full-stack application through a roster of specialized AI agents, coordinated by a strict handoff protocol and per-case playbooks.

It is not an app. It is a reusable set of agent definitions, skills, process docs, and templates you copy into your own AI coding environment (Claude Code, GitHub Copilot / VS Code, Cursor, or any agent harness) and run against your own project.

Portability. Copying .github/agents and the skills folders is a starting point, not a complete install. The agent definitions are portable across harnesses; the directory layout, the tools: frontmatter, and the orchestration model are platform-specific and need conversion. PORTABILITY.md documents per-platform setup and scripts/install.sh performs the conversion. This README explains the model; PORTABILITY explains the setup.

---

The mental model — four pillars

Pillar	What it is	Where
Packet	The single source of business truth — a structured, plain-language brief. Everything traces back to it.	templates/stakeholder-input-packet.md + the creating-stakeholder-packet skill
Roster	26 specialized agents (orchestrator, requirements, design, build, hardening, delivery + expansion agents). Each has one job and hard boundaries.	process/agent-roster.md
Playbooks	Per-case recipes — which agents run, in what order, with which gates. 9 cases (greenfield, defect, incident, refactor, …).	process/playbooks/
Handoff protocol	How work moves between agents: payload format, run workspace, gates, escalation, context budget.	process/agent-handoff-protocol.md

A run is driven by the Delivery Orchestrator (agent 01): it picks the next agent per the playbook, carries context via append-only handoff files, halts at human gates, and records everything under runs/<run-id>/ so any agent can be invoked cold and reconstruct state from disk alone.

---

Repository layout

.github/agents/      28 agent definitions — Copilot/VS Code `.agent.md` format. SOURCE OF TRUTH.
.github/skills/      skills in Copilot/manual form
.claude/skills/      the same skills, Claude Code layout
.claude/agents/      Claude Code agents — GENERATED from .github/agents by scripts/install.sh
.claude/commands/    run-delivery — the orchestrator driver for Claude Code
.claude-plugin/      plugin.json + marketplace.json — the Claude Code marketplace plugin
agents/ skills/ commands/   plugin component dirs (Claude Code format) — GENERATED from .github
process/             the spine: agent-roster.md, agent-handoff-protocol.md, playbooks/
templates/           the Stakeholder Input Packet template
runs/                per-run workspaces — the live state store (packet, requirements, gates, handoffs)
scripts/             install.sh — install/convert the roster for your platform
PORTABILITY.md       per-platform setup, directory map, tool-posture mapping

.github/agents/ is the source of truth. Other platforms' agent folders are derived from it — regenerate them with scripts/install.sh, don't hand-edit, or they drift.

---

Quick start

1. Install for your platform

# Claude Code — generates .claude/agents/ (tools frontmatter rewritten) + ensures .claude/skills/
scripts/install.sh --target claude

# Cursor — generates .cursor/rules/ reference rules
scripts/install.sh --target cursor

# GitHub Copilot / VS Code — agents are already native in .github/agents/ (no conversion)
scripts/install.sh --target copilot   # prints guidance only

# Claude Code marketplace plugin — generates root agents/ skills/ commands/ (+ .claude-plugin/ manifests)
scripts/install.sh --target plugin

Copy the relevant folders (.claude/, .github/, or .cursor/) plus process/ and templates/ into your project. See PORTABILITY.md for exactly which folders each platform needs.

2. Create the packet

Use the creating-stakeholder-packet skill (it interviews you), or copy templates/stakeholder-input-packet.md and fill it. Resolve every OPEN item. Freeze it under runs/<run-id>/00-packet/.

3. Start a run

• Claude Code: /run-delivery <run-id> — the main session becomes the Delivery Orchestrator and drives the roster.
• Copilot / VS Code: invoke the delivery-orchestrator agent and point it at the packet.
• Cursor / generic: drive the orchestrator in your main chat; see PORTABILITY for the invocation caveat.