PA·co Framework is a markdown-first, zero-code multi-agent operations system for Claude Code. It enables 3-22+ specialized AI agents to coordinate via file-based state management, maintain institutional memory through 4-layer Context Engineering, and operate autonomously with human oversight -- without writing a single line of Python.
PA·co stands for Penguin Alley Commander/Officer. It transforms a Claude Code instance into an autonomous team of AI agents that coordinate, learn, and evolve using only markdown files.
PA·co uses a file-based architecture where each AI agent reads markdown files to understand its role, the current system state, and what work needs to be done. Agents coordinate through shared state files rather than message passing:
+---------------+
| CEO |
| (Human) |
+-------+-------+
| halt / resume / approve
+-------v-------+
| PA-co |
| Orchestrator | <- 4-layer context
+-------+-------+
+---------------+---------------+
| | |
+------v------+ +-----v-----+ +-------v------+
| Engineering | | Q & S | | Intelligence | ...
| | | | | |
| Builder | | QA | | Researcher |
| Designer | | Auditor | | Strategist |
+------+------+ +-----+-----+ +-------+------+
| | |
products/ state/ catalogs/
{name}/STATE PIPELINE.md sectors.md
HALT.md tech-stacks.md
| Capability | Description |
|---|---|
| Multi-agent coordination | 3-22+ specialized AI agents organized into 8 departments, each with clear roles, Knowledge Graph navigation, and handoff protocols |
| 7-phase product workflow | Structured pipeline from Research to Refine to Post-Refine to CEO Gate to Develop to Deploy to Evolve |
| 4-layer Context Engineering | Identity, State, Relevant, Archive -- ensures every agent session receives precisely the context it needs |
| Quality gates | Mandatory checks at every phase transition, preventing defects from propagating |
| Emergency halt system | Instantly pause any product or all operations with a single markdown edit |
| Human-in-the-loop governance | CEO approval gates for critical decisions; agents operate autonomously within defined boundaries |
| Tool whitelisting | Per-agent tool restrictions (allow/deny lists) enforcing least-privilege access, compatible with Anthropic Subagents API |
| Subagents API integration | Spawn PA·co agents programmatically via the Claude Agent SDK with isolated contexts, parallel execution, and enforced tool restrictions |
| Pipeline visualization | ASCII DAG shows where every product sits in the 7-phase workflow -- run python tools/pipeline-viz.py for an instant snapshot |
| Zero-code setup | Everything is configured through markdown files -- no Python, no YAML configs, no infrastructure code |
- Clone this repo into your project
- Run the bootstrap prompt in Claude Code:
Read paco-bootstrap.md and execute the setup - Answer 5-7 questions about your project
- PA·co generates your entire multi-agent system
- Run your first standup:
Run as /paco -- execute daily standup
Full setup guide: docs/getting-started.md
Every product goes through the full workflow. No shortcuts, no skipped phases.
RESEARCH -> REFINE -> POST-REFINE -> CEO GATE -> DEVELOP -> DEPLOY -> EVOLVE
| Phase | What happens | Gatekeeper |
|---|---|---|
| Research | Find problems worth solving. Scan market sectors. Output: specification template. | PA·co |
| Refine | All departments enrich the spec in parallel. Engineering defines the solution. Each agent asks minimum 10 questions with mandatory web search. | PA·co |
| Post-Refine | Auditor reviews all specs. Fix issues or kill the product. | Auditor |
| CEO Gate | Human approves, rejects, or defers. No product advances without human approval. | CEO |
| Develop | Builder + Designer build from specs. No improvisation. Build/QA alternation enforced. | QA + Security |
| Deploy | Ship to production. Security scan. Health verification. | CEO |
| Evolve | Continuous improvement: health reviews, competitive defense, feature iteration. | Auditor (biweekly) |
See core/workflow-schema.md for the full schema.
Context Engineering is the core innovation of PA·co Framework. It solves the fundamental problem of multi-agent AI systems: how does each agent get the right information at the right time without exceeding context limits?
| Layer | What it provides | Source | Lifecycle |
|---|---|---|---|
| Identity | CLAUDE.md + agent definition + role catalogs | Repository files | Read-only per session |
| State | Product STATE.md + Pipeline + today's dispatch | state/, products/*/ |
Rewritten every session |
| Relevant | Semantic search results from vector database | pgvector (Supabase) | ~5-10 results per query |
| Archive | All historical knowledge not returned by search | Vector database | Grows indefinitely |
Same agent + different context = different behavior per product. Agent definitions are generic; products/{name}/ directories make them product-specific.
See core/context-engineering.md for the full specification.
Products track their own state. A global pipeline tracks all products.
state/
PIPELINE.md -- All products and their current phase
HALT.md -- Emergency stop system
CEO_BLOCKERS.md -- Items requiring human decision
products/{name}/
CLAUDE.md -- Product-specific rules and stack
STATE.md -- Progress, bugs, last_actor, metrics
DISPATCH.md -- Cross-department handoffs
mvp-specs/ -- What to build (specifications)
Build/QA alternation is enforced via the last_actor field in STATE.md: if the last actor was the Builder, QA runs next, and vice versa. This guarantees every build session is followed by a quality check.
See core/state-schema.md for the full schema.
Each agent is defined as a markdown file with YAML frontmatter:
---
name: "Builder"
department: "engineering"
expected_frequency: "hourly"
tools: ["Bash", "Read", "Write", "Glob", "Grep"]
---
You are the Builder. Your job is to write code, deploy, and maintain products.
## I DO:
- Write code from specifications
- Run database migrations
- Deploy to production
## I DO NOT:
- Create marketing content (that is the Marketer)
- Make spending decisions (requires CEO approval)PA·co supports 3-16 agents organized into departments. A typical production setup uses 8-12 agents across 5 departments: Executive, Engineering, Quality & Security, Intelligence & Strategy, and Growth & Revenue.
Each agent can declare which tools it is allowed or denied. This enforces least-privilege access and maps directly to the Anthropic Subagents API's per-agent tool restrictions:
# Auditor: read-only, cannot modify code it reviews
tools_allowed: ["Read", "Glob", "Grep"]
# Researcher: can search and read, but not modify files
tools: ["Read", "Glob", "Grep", "WebSearch", "Bash"]
tools_denied: ["Write", "Edit"]See core/agent-schema.md for the full schema, resolution logic, and common patterns.
Agents run on schedules via Claude Code scheduled tasks:
| Schedule type | Examples |
|---|---|
| Work hours (jornada) | Standup at 8am, Refine phases 8:30-10:30am, Competitive Defense at 2pm |
| 24/7 automation | Build sessions hourly, QA alternating, email relay |
| Weekly | Friday reports, open source sync |
Schedules include smart-skip logic: if there is nothing to do, the agent exits silently instead of generating empty output.
The HALT system provides instant, global control over all agent operations:
# state/HALT.md
## Current: CLEARWrite HALT [product] or HALT ALL to stop operations instantly. Every schedule reads HALT.md before doing anything. Only the CEO (human operator) can halt or resume.
PA·co Framework takes a fundamentally different approach from Python-based multi-agent frameworks. While CrewAI, LangGraph, and AutoGen require writing code to define agents and workflows, PA·co uses markdown files exclusively.
| Feature | PA·co Framework | CrewAI | LangGraph | AutoGen (retired) |
|---|---|---|---|---|
| Language required | None (markdown only) | Python | Python | Python |
| Setup time | 5 minutes | Hours | Hours | Hours |
| Product lifecycle management | 7-phase workflow with gates | No built-in workflow | State machine (manual) | No built-in workflow |
| Context management | 4-layer Context Engineering | In-memory / optional RAG | State machine variables | Message history |
| Quality gates | Built-in at every phase transition | None | None | None |
| Emergency halt | Built-in (HALT.md) | None | None | None |
| Knowledge persistence | Vector DB + markdown files | Optional RAG | None built-in | None built-in |
| Human approval gates | CEO Gate built into workflow | None | Interrupt points (manual) | Human-in-the-loop (manual) |
| Per-agent tool restrictions | Built-in (tools_allowed/tools_denied) | None | None | None |
| Agent coordination (A2A) | File-based A2A (5 patterns, no infra) | Runtime A2A + task delegation | Graph edges | Group chat / nested |
| Cost model | $0 (MIT, uses your Claude subscription) | $99-$120K/year | $39/user/mo + per-node | Free (retired) |
| LLM support | Claude Code only | Multi-LLM | Multi-LLM | Multi-LLM |
| Best for | Autonomous operations with governance | Python developers, enterprise teams | Complex agent graphs | Legacy projects (see migration guide) |
When to choose PA·co: You want structured, governed multi-agent operations without writing code. You use Claude Code. You need a product lifecycle (not just task execution). You want human-in-the-loop by default.
When to choose CrewAI: You need multi-LLM support. Your team writes Python. You need enterprise features and support.
When to choose LangGraph: You need fine-grained control over agent execution graphs. You are building complex, branching agent workflows in Python.
For a detailed comparison, see docs/comparisons.md.
| Template | Agents | Best for |
|---|---|---|
solo-founder |
4 (orchestrator, builder, devops, marketer) | Solo builders shipping fast |
startup |
8 (adds QA, researcher, strategist, sales) | Small teams with product-market fit goals |
context-engineering |
N/A (add-on) | Adding pgvector semantic memory to any PA·co setup |
Industry-specific templates with specialized agents, workflows, and dispatch patterns.
| Template | Agents | Price | Get it |
|---|---|---|---|
| Agency | 6 (multi-client coordination) | $99 | Buy on Gumroad |
| E-Commerce | 6 (inventory, support, analytics) | $79 | Buy on Gumroad |
| Content Studio | 5 (writer, editor, SEO, social) | $49 | Buy on Gumroad |
| Dev Team | 6 (code review, QA, security, DevOps) | $79 | Buy on Gumroad |
| Complete Bundle | All 4 + future templates | $249 | Buy on Gumroad |
PA·co Framework is not theoretical. It runs Penguin Alley's entire operations:
- 12 agents across 5 departments + Executive
- 19 scheduled tasks running autonomously 24/7
- 4-layer Context Engineering with pgvector semantic search
- Multiple products shipped through the full 7-phase pipeline
- $0 infrastructure cost -- built entirely on free tiers
Every pattern in this framework comes from real production experience. The 7-phase workflow, Build/QA alternation, emergency halt system, and Context Engineering layers were all developed and refined through shipping real products.
| Schema | What it defines |
|---|---|
| agent-schema.md | Agent file structure, roles, jurisdictions |
| context-engineering.md | 4-layer context system specification |
| context-engineering template | pgvector setup: schema, ingest, search scripts |
| workflow-schema.md | 7-phase product lifecycle |
| state-schema.md | Product state and pipeline tracking |
| dispatch-schema.md | Cross-department handoff system |
| memory-schema.md | File-based knowledge persistence |
| schedule-schema.md | Agent scheduling patterns |
| executive-orders-template.md | CEO directives template |
- Getting Started -- Full setup guide
- Architecture -- Technical architecture, context layers, and system design
- Concepts -- Departments, context layers, and workflows
- 7-Phase Workflow -- Complete guide to the product lifecycle
- Adding Agents -- Create custom agents
- A2A Protocol -- Agent-to-agent coordination patterns
- Subagents API -- Spawn PA·co agents via the Claude Agent SDK
- MCP Transports -- Connect agents to external tools via MCP
- Pipeline Visualization -- ASCII DAG of your product pipeline
- FAQ -- 50+ questions and answers about multi-agent systems
- Comparisons -- PA·co vs CrewAI vs LangGraph vs AutoGen
- AutoGen Migration Guide -- Migrate from AutoGen (maintenance mode) to PA·co
- Claude Code (CLI, Desktop app, VS Code extension, or JetBrains extension)
- Claude Pro/Max for scheduled tasks (optional -- can run agents manually)
- Any project type: SaaS, agency, content, dev tools, research, etc.
AGPL-3.0 — open source, free to use, modify, and distribute.
If you modify PA·co Framework and offer it as a service, you must share your changes under the same license. This keeps the ecosystem open and fair.
For commercial use without AGPL obligations (e.g., proprietary products, enterprise deployments where sharing source is not an option), contact hello@penguinalley.com for a commercial license.
See CONTRIBUTING.md for guidelines. We welcome:
- New agent templates
- New department configurations
- Industry-specific templates
- Documentation improvements
- Bug reports and feature requests
Built by PA·co -- A Penguin Alley System