A system for defining repeatable AI-driven processes — teams, roles, pipelines (structured workflows that prevent skipping steps), and review protocols — that you can adopt incrementally. Start with better AI reviews in 15 minutes, or build out a full multi-agent organization.
The system is team-agnostic. Engineering is the first fully-built team, but the same scaffolding works for sales, marketing, operations — any team where work benefits from structured review.
New here? See which path fits you, or jump to the FAQ.
| Problem | How Directives addresses it |
|---|---|
| AI agents skip steps under pressure | A pipeline defines every stage from requirements to delivery. GitHub labels track progress. Skip a stage and the system warns you. |
| Generic AI feedback is shallow | Personas (detailed character profiles — backstory, expertise, review lens) produce targeted, deep feedback instead of "looks good, maybe add some checks." |
| One agent reviews its own work | The architecture separates builder and validator agent types. Different agents — or isolated sessions — catch different blind spots. |
| Process lives in tribal knowledge | Manifests (YAML config files) are the single source of truth for teams, roles, stages, and vocabularies. Machine-readable, version-controlled, no drift. |
| Setting up takes too long | Three adoption levels let you start small. Use personas alone in 15 minutes. Add the pipeline when you're ready. Split agents later. |
graph TD
A{"What do you<br/>want to do?"} -->|"Understand<br/>the ideas"| B["docs/concepts.md<br/>→ why.md<br/>→ getting-started.md"]
A -->|"Set it up<br/>now"| C["docs/getting-started.md"]
A -->|"See the<br/>config"| D["Reference section<br/>below"]
style A fill:#333,color:#fff
style B fill:#0075ca,color:#fff
style C fill:#0e8a16,color:#fff
style D fill:#6f42c1,color:#fff
| Level | What you get | Time |
|---|---|---|
| Quick start | Better AI reviews using persona definitions — zero config | 15 min |
| Standard | Structured pipeline with labels, stage gates, and repeatable process | 30 min |
| Full system | Builder/validator split across different LLM providers (the AI tools that do the work) for independent review | 1 hour |
Each level builds on the last. See Getting Started for setup instructions.
| Doc | What you'll learn | Time |
|---|---|---|
| Key Concepts | Agent types, personas, pipeline, committee, manifests | 10 min |
| Why This Architecture? | The problems and thinking behind each decision | 10 min |
| Glossary | One-line definitions for every term | 3 min |
| FAQ | "Do I need all of this?", "Engineering only?", and more | 3 min |
A task flows through six pipeline stages. Each stage produces artifacts the next one consumes:
graph LR
A["Define<br/><code>/define</code>"] --> B["Design<br/><code>/design</code>"]
B --> C["Implement<br/><code>/implement</code>"]
C --> D["Review<br/><code>/review</code>"]
D --> E["Deploy & Verify<br/><em>(automatic)</em>"]
E --> F["Summarize<br/><code>/summarize</code>"]
style A fill:#6f42c1,color:#fff
style B fill:#0e8a16,color:#fff
style C fill:#fbca04,color:#000
style D fill:#6e5494,color:#fff
style E fill:#0075ca,color:#fff
style F fill:#d4c5f9,color:#000
A committee of personas — specialists with distinct professional backgrounds — reviews work at the Design and Review stages. Each persona reads all prior feedback before adding their own, building cumulative insight rather than repeating observations.
The engineering team has 11 personas. Each brings a different lens:
| Persona | Focus |
|---|---|
| UX Designer | Accessibility, design systems |
| Software Engineer | Code quality, patterns |
| System Architect | Coupling, scalability |
| Data Engineer | Migrations, query performance |
| AI/ML Engineer | LLM safety, prompt risks |
| Security Engineer | Vulnerabilities, auth bypass |
| QA Engineer | Test coverage, edge cases |
| SRE | Ops, health checks, logging |
| Writer | User-facing copy, docs |
| Engineering Manager | Synthesizes all feedback |
Other teams define their own personas and review sequences — the structure is identical, only the expertise changes.
The architecture separates work into two agent types: a builder (creates work — implements, produces, deploys) and a validator (reviews independently — audits, checks quality, flags issues). When backed by different LLM providers, they bring different training and biases, catching things the other misses. Even with a single provider, isolated sessions prevent the validator from inheriting the builder's blind spots.
Three config files drive the system at different scopes:
| File | Scope | What it controls |
|---|---|---|
agents.yml |
Global | Agent types, LLM providers, assignments, fallback chains |
manifest.yml |
Per-team | Role roster, pipeline stages, labels, vocabularies |
CONTRIBUTING.md |
Per-project | Team reference, pipeline mode, provider overrides |
Each team gets its own manifest, personas, pipeline, and vocabulary. Engineering is the first fully-built team — see teams/engineering/ for the complete example, including personas, process docs, and manifest. To create a new team, copy teams/TEMPLATE/ and customize.
Cross-team rules for how agents think and coordinate: agent architecture, orchestration, reasoning, safety.
Starter files for new projects: CONTRIBUTING.md, CLAUDE.md, GEMINI.md, worklog, pm-context.
Optional domain-specific rules layered on top of the base process. Currently available: healthcare (HIPAA, PHI handling, patient safety).
Configuration lives at three levels, each adding specificity without duplicating the tier above:
| Tier | Where | What |
|---|---|---|
| 1. Directives (this repo) | suniljames/directives |
Team scaffolding, personas, framework, templates |
| 2. Organization (optional) | <org>/.github or org-level repo |
Domain compliance, org-specific workflows, shared CI |
| 3. Project | Each project repo | Tech stack, architecture, environment config |