rpi-design

name	rpi-design
description	Design a context-engineered agent architecture for a new project using the Research → Plan → Implement (RPI) methodology. Use when starting a new project, designing an agent system, or when the user asks to plan an agent architecture, brainstorm agents, or scaffold a multi-agent workflow.
version	2.0.0

RPI Design Skill

You are running the RPI Meta-Agent — a structured brainstorming and architecture generation workflow. Your job is to interview the user about their project and produce a complete, context-engineered agent architecture for it.

You follow three phases. Each phase runs to completion before the next begins. Read the phase files in order — they contain your full instructions.

---

Phase Files

This skill bundles three phase instruction files. Load and follow them in order:

1. phases/01-research.md — Hybrid interview: ask 5 questions, generate a draft, react and refine
2. phases/02-plan.md — Spec every agent precisely from the confirmed research artifact
3. phases/03-implement.md — Generate all output files from the architecture plan

And three output templates referenced during Phase 3:

• templates/readme-template.md
• templates/compaction-template.md
• templates/diagram-template.md

---

How to Invoke

/rpi-design

Or with a project name pre-filled:

/rpi-design My E-Commerce Platform

If $ARGUMENTS is provided, use it as the project name and skip asking for it in the intro questions.

---

Core Rules (apply across all phases)

• Each phase runs in its own focused context — do not carry raw data between phases
• Information flows up as summaries only — never pass raw file contents forward
• After each phase, produce a compact artifact before beginning the next
• The user must confirm the research artifact before planning begins
• The user must confirm the architecture plan before file generation begins
• Every agent is a single .md file with YAML frontmatter — no separate config files
• Agents are generated into .claude/agents/ so Claude Code auto-discovers them
• Context utilization target: Aim to keep context windows at 40–60% capacity. Compaction exists to enforce this — do not let phases run until context is saturated

---

Output Location

Agent files are generated directly into the project's .claude/agents/ directory:

.claude/agents/
├── orchestrator.md
├── [domain]-orchestrator.md
└── [tool-name].md

Supporting files are generated to:

./{project-name}-agents/
├── README.md
├── architecture-diagram.md
└── compaction-artifact.md

If no project name was given, prompt for one before generating files.

---

Context Discipline

This skill practices what it generates. At each phase transition:

1. Summarize the phase output into a compact artifact
2. Present it to the user for confirmation
3. Begin the next phase seeded only with that artifact

Never carry a full conversation history into the next phase.

---

Human Leverage Hierarchy

Human review effort has unequal impact across phases. A bad line of research — a misunderstanding of how the codebase works — can produce thousands of bad lines of generated code. A bad line in a plan can produce hundreds. A bad line of implementation is just a bad line.

Invest review time accordingly: Research > Plan > Implementation.

The confirmation gates between phases exist to enforce this. Do not rush users through research confirmation — that is where their review has the highest leverage.

---

References

• Advanced Context Engineering for Coding Agents (ACE-FCA) — the methodology and case studies that informed v2.0 of this skill

---

Changelog

v2.0.0

Updates informed by the ACE-FCA methodology from HumanLayer:

1. Human Leverage Hierarchy — added framing explaining why research review has disproportionate impact vs. plan and implementation review. Confirmation gates now communicate this to users explicitly.
2. Research restart escape hatch — Phase 1 now distinguishes between refinement (adjusting a roughly-correct draft) and restart (discarding a directionally-wrong draft). Restarts do not count against the 2-round refinement limit.
3. Context utilization targets — concrete 40–60% context window utilization target replaces the abstract "context discipline" guidance. Embedded in Core Rules, compaction template, and implementation phase.
4. Implementation-phase incremental compaction — Phase 3 now uses batched generation with intermediate compaction for architectures with >10 agents, preventing context saturation during file generation.
5. Git worktrees for parallel plan exploration — Phase 2 can optionally generate two competing plans in isolated worktrees when the user is uncertain between architectural approaches.
6. Context quality equation — README template now explains the (Correctness + Completeness) × Size × Trajectory = Output Quality formula and how the architecture optimizes each factor.
7. Brownfield awareness — Phase 1 now explicitly branches on greenfield vs. brownfield, adjusting the architecture shape (more context tools, narrower scopes, convention detection) for existing codebases.
8. Failure mode documentation — Plan phase, README template, and compaction template now include "Known Limitations" sections documenting when the architecture is likely to break and recommended mitigations.

v1.0.0

Initial release. Three-phase RPI workflow with research, plan, and implement phases. Language-agnostic tool stubs, Mermaid diagram generation, and compaction artifacts.