Agents of the Alley

A structured methodology for managing multi-agent Claude Code projects.

Agents of the Alley

The context-engineering OS for multi-agent Claude Code projects. Template + discipline that runs Penguin Alley's PA·co (22 agents, 8 departments, production SaaS) — distilled for your team.

License: Apache 2.0 Claude Code Docs: ES · EN

The problem

You've built 3 Claude Code agents. They contradict each other. Your CLAUDE.md is 800 lines. Agent A thinks the product uses Postgres; Agent B ships with MongoDB. Your memory/ is a graveyard. Your tokens are gone.

Multi-agent systems don't fail because agents are dumb. They fail because nobody designed the brain.

The solution

4 context layers, one knowledge graph, zero contradictions:

Layer 1 — Identity    (CLAUDE.md + agents/*.md)        — never changes mid-session
Layer 2 — State       (state/ + products/*/STATE.md)   — rewritten per session
Layer 3 — Relevant    (pgvector or SQLite RAG)         — fetched on demand
Layer 4 — Archive     (everything else)                — searchable, never loaded

Every agent reads the same layers in the same order. Every insight lives in ONE canonical file, gets embedded in RAG, and is cross-referenced. Contradictions surface instantly; token bloat is impossible.

This is the pattern that keeps PA·co (22 agents, 8 departments, multiple live SaaS products, 3rd of 91 at AgentX 2026) coherent. We've run on it for months. Now it's yours.

What's inside

agents-of-the-alley/
├── CLAUDE.md                    # Root identity — the 4-layer contract
├── agents/                      # 5 sample agents (Planner, Builder, Reviewer, Researcher, Deployer)
│   └── *.md                     #   ≤55-line definitions — no bloat
├── .claude/
│   └── skills/
│       ├── brainstorming-visual.md  # HTML mockup A/B/C before building
│       └── writing-skills.md        # TDD for creating new skills
├── playbooks/
│   ├── context-engineering.md   # The 4-layer discipline
│   ├── agent-teams.md           # Multi-agent debate pattern
│   └── knowledge-graph.md       # EO-006: canonical file + RAG + cross-ref
├── wiki/
│   └── topics/                  # Cross-referenced knowledge (bidirectional links)
├── memory/                      # Session-surviving context (feedback, references, projects)
│   └── MEMORY.md                # Index, ≤200 lines (auto-truncated)
├── examples/
│   └── simple-multi-agent/      # Runnable pattern: 3 agents + shared context
└── wiki/topics/INDEX.md         # Knowledge graph entrypoint

Quickstart (5 minutes)

# 1. Clone as template
git clone https://github.com/PenguinAlleyApps/agents-of-the-alley.git my-project
cd my-project

# 2. Point Claude Code at it
# (Claude Code auto-loads CLAUDE.md + agents/*.md from root)

# 3. Customize the 5 sample agents for your domain
#    Each agent file has: Identity + Context Loading + Output + Refinement Questions

# 4. Write your first knowledge graph entry
#    wiki/topics/your-topic.md  →  cross-ref in agents that need it

# 5. Verify the discipline
grep -rh "→ Wiki:\|→ Agents:\|→ Playbooks:" agents/ playbooks/
# Every file should have bidirectional links. Zero orphans.

Why this matters

The top Claude Code repositories (affaan-m/everything-claude-code, anthropics/skills, obra/superpowers) give you frameworks and plugins. None give you the operating discipline that keeps multi-agent systems from devolving into contradiction soup.

Agents of the Alley is the missing methodology layer. You bring the agents; we bring the rules that make them not fight each other.

Who runs on this

  • PA·co — 22 agents, 8 departments, Windows + RTX 4090 + Claude Code + pgvector.
  • Compliora — AI Decision Audit Trail SaaS (Starter $29 / Pro $99 / Team $199 USD). Built by PA·co agents following this exact pattern.
  • Penguin Alley consulting — production multi-agent systems for regulated SMBs.

Want yours listed? Open a PR editing this section.

Philosophy

  1. Files are the source of truth. No database locks you in. Git is your agents' memory.
  2. Markdown is the language. Every agent reads the same format. LLMs parse markdown better than XML.
  3. Cross-references are mandatory. Every insight lives in one canonical file + RAG + is linked bidirectionally. Triple-write or it didn't happen.
  4. Size limits are discipline. CLAUDE.md ≤150 lines. Agent files ≤55. Overflow = compress or split.
  5. Agents specialize, don't generalize. One agent per role. A "do everything" agent is a failed agent.

Community

  • Consulting: need help implementing at scale? penguinalley.com/es/consulting
  • Issues: bug reports, pattern proposals, questions welcome. Please include your Claude Code version + OS.
  • PRs: small improvements welcome (docs, examples). For new core patterns, open a Discussion first.
  • Spanish community: docs nativos en español, no traducidos. Vea docs/es/.

License

Apache 2.0. Patent grant included. Attribution required (keep the "Built by PA·co — A Penguin Alley system" footer in derivative repos).

Roadmap

  • MVP: template repo with 5 agents + 2 skills + core playbooks (v0.1)
  • CLI: paco-kit doctor — detect contradictions across layers
  • CLI: paco-kit ingest — repomix + pgvector pipeline
  • CLI: paco-kit graph — visualize knowledge graph
  • Bilingual docs: full ES + EN parity
  • Demo video: "22 agents, one shared brain" (5 min walkthrough)
  • Python SDK (alongside current markdown-only approach)

Documentación

English: Philosophy · Quickstart · What's inside

Español: docs/es/README.md (en desarrollo)

Built by PA·co — A Penguin Alley system. Made in Monterrey, México. 🐧

If this saved you time, consider our consulting for production multi-agent deployment.