Wrong way
Ask one agent to run the whole team
agent.run("understand, plan,
build, review, and remember")Hidden context becomes the integration layer. Failures are difficult to locate and retries repeat too much work.
The portable systems guide
Build the team,
not the prompt chain.
Learn how agents, skills, commands, artifacts, and deterministic orchestration combine into an engineering system you can port to any language.
- 01 Explicit handoffs
- 02 Independent judgment
- 03 Deterministic gates
Interactive system map
Follow one feature
Stage 01Main conversation
Discovery turns intent into a contract
The agent interviews you, resolves ambiguity, and writes the user truth. It does not inspect application code.
- Reads
- You, AGENTS.md, existing briefs, open GitHub issues
- Writes
- 001.01-dis-feature-name.md
Choose a stage to inspect its boundary and handoff.
01 / The boundary
Judgment belongs to agents. Mechanics belong to code.
A dependable AI system does not make everything probabilistic. It gives interpretation to specialists and keeps sequence, validation, persistence, and routing explicit.
System boundary
Give each role one contract
route(stage, artifact)
require_file(output)
combine(verdicts)Code controls the rails. Each agent performs one kind of judgment, writes evidence, and terminates.
“The handoff is an artifact, not hidden reasoning.”Open the full architecture guide
02 / The primitives
Three files create the operating model.
An agent owns judgment. A skill carries reusable policy. A command gives the workflow a deterministic entrance.
Probabilistic specialist
Agent
A bounded expert that reads approved context, makes domain judgments, and produces one defined result.
name: architect
tools: [Read, Write]
skills:
- language-principles
- spec-format- Identity and mental model
- Inputs and output address
- Tools, process, and prohibitions
Reusable policy
Skill
A focused rule set injected only where needed, so experience compounds without bloating every agent.
# Scope capture
Trigger: adjacent work noticed
Record: idea + route tag
Do not: expand current scope- Recognition trigger
- Required behavior and vocabulary
- Ownership boundary
Routing contract
Command
The user-facing boundary that parses intent, selects a mode, and adopts or launches the correct coordinator.
/feature "Add sync status"
/feature resume 001
/roadmap- Arguments and modes
- Validation and error handling
- Workflow adoption
03 / The compounding system
Shipping is one loop, not the whole system.
Delivery creates product evidence. Strategy orders what should happen next. Learning improves the rules used on the next run.
Loop 01
Delivery
Intent becomes a reviewed implementation through explicit, append-only handoffs.
Brief→Build→Gate
Loop 02
Product strategy
Adjacent ideas become labeled GitHub issues; persona ICP files give the Roadmap Analyst a definition of value.
Issue+ICP→Order
Loop 03
Learning
Structured evidence becomes proposed policy, but only after a human approves the change.
Evidence→Rule→Next run
04 / Build the smallest team
Prove the loop before you add the organization.
Start with one coordinator, one builder, one reviewer, and an artifact directory. Add roles only after the first retry can resume without hidden context.
Start with system architecture- 01
Define the contracts
Paths, schemas, verdicts, and done conditions.
- 02
Build one vertical slice
Coordinator → engineer → artifact existence check.
- 03
Add an independent gate
A reviewer returns PASS, NOTES, or NEEDS WORK.
- 04
Prove resumability
Restart at the first missing artifact without replaying finished work.
Reference implementation
See the complete Rails team.
The repository contains the working agents, skills, commands, artifact grammar, review loop, evidence recorder, scope capture, ICP workflow, and Roadmap Analyst.
Open the repository
Use it as a reference implementation. Preserve the contracts; replace the Rails-specific judgment.