1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

A starting point for working with AI coding agents. Rules, agents, skills — ready to use, easy to change.

What is this?

Claude Code reads agents, rules, and skills from a .claude/ directory — either ~/.claude/ (global) or {project}/.claude/ (project-local). The full spec is at code.claude.com/docs/en/claude-directory. The AI Toolkit is a curated set of those files, maintained by the engineering team, plus a CLI that copies the right ones into place.

The profile system controls what loads. Pick a profile for the task at hand — data work, security review, product engineering — and the CLI deploys the matching rules to your ~/.claude/ directory. Agents and skills deploy to every profile; only the knowledge set changes. Switch profiles when the task changes.

It is also a shared space. Check in your team’s conventions as rules, add agent specialisations, contribute workflow skills. The toolkit is as useful as what the team puts into it.

What it does	What it doesn’t do
Deploys agents, rules, and skills to `.claude/`	Change how Claude Code itself works
Lets you switch knowledge sets per task type	Guarantee agent output quality — that depends on your prompts and rules
Gives the team a shared place to evolve conventions	Replace your judgement on what to build or review

The mechanism is simple: it copies files. The value is in which files — and the team’s discipline to keep them current.

Agents

Rules

Skills

Phases

Get started →

Get started

bolt

Quick Start

Up and running in three commands

group_add

Contributing

Add your team's rules and skills

forum

Talk to Your Team

Just say what you need

smart_toy

Meet the Agents

36 specialists, ready when you are

hub

Learn the Phases

Explore, Plan, Build, Validate

Browse workflows

Pre-built sequences of skills and agents, auto-discovered from workflows/ directories.

account_tree

Workflows

See all available workflows

🤔 Take a moment: What task do you currently do alone that a team of specialists would do better?

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

bolt Quick Start

Install the CLI, then run setup to pick your team and role. You can change what's installed at any time with toolkit commands — no need to re-run setup.

1 — Install the CLI

Requires uv:

brew install uv
git clone https://github.com/toknapp/ai-toolkit.git
cd ai-toolkit
uv tool install .

This binds the toolkit binary to this repository path. Once installed, run toolkit from anywhere — it always reads agents, rules, skills, and profiles from the cloned repo location.

2 — Run setup

Pick your team, role, and any workflows you want. Takes about a minute:

toolkit setup

The wizard asks which team you're on, what your role is, and which workflows to add. It then deploys everything to ~/.claude/. Start a new Claude Code session to pick up the changes.

3 — Add or remove things later

You don't need to re-run setup. Use toolkit directly:

toolkit agent add <name>          # add an agent
toolkit rule add <name>           # add a rule
toolkit skill install <name>      # install a skill
toolkit workflow install <name>   # install a workflow

Use toolkit agent list, toolkit skill list, toolkit rule list, or toolkit workflow list to browse what's available. If you're stuck: toolkit --help or the docs.

Something not working?

Agents not responding in Claude Code

Run toolkit verify to check deployed state. If agents are missing, run toolkit profile reload to re-sync. Check the docs or run toolkit --help for more options.

toolkit: command not found

Run uv tool install . from the ai-toolkit/ directory. If uv is not on your PATH, add $HOME/.local/bin to your PATH.

Next steps

forum

Talk to Your Team

Learn natural language interactions

swap_horiz

Browse Profiles

Switch knowledge for different tasks

smart_toy

Meet the Agents

See who's on the team

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

group_add Contributing

Your team has its own namespace. Add your domain rules, skills, and agents freely — no cross-team approval needed. PRs touching only your namespace need only your team's review. Your team also owns its profile file at profiles/<team>.yaml — add profiles there without cross-team approval. See CONTRIBUTING.md for the full guide.

Deploy your first rule in under 5 minutes

Create a file under teams/<your-team>/
Add frontmatter and content
Register it in profiles/
Run toolkit validate

No gatekeeping. Your namespace, your rules.

Team Namespaces

Each team owns teams/<your-team>/ across rules, skills, and agents. PRs touching only your namespace need only your team's review. CODEOWNERS enforces this automatically.

What You Can Add

Content type	Team-specific (in your namespace)	Cross-team shared
Rules	`rules/teams/<team>/my-rule.md`	`rules/general/my-rule.md`
Skills	`skills/teams/<team>/my-skill/SKILL.md`	`skills/general/my-skill/SKILL.md`
Agents	`agents/teams/<team>/my-agent.md`	`agents/general/my-agent.md`
Workflows	`*/workflows/<workflow-name>/` — auto-discovered from any resource type

Five Steps to Your First Contribution

Your namespace is teams/<your-team>/ (check the directory or CODEOWNERS)
Create a file: src/upvest-agency/rules/teams/<your-team>/my-pattern.md (or a skill/agent)
Add frontmatter and content — see templates in CONTRIBUTING.md
Register it in profiles/, then run toolkit validate && toolkit profile reload
Open a PR — your team reviews and merges. No other team involved.

Autonomy: Each team controls their domain. No cross-team approval gates. Move at your team's pace.

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

forum Talk to Your Team

Once deployed, the toolkit lives inside your coding session. No special syntax needed — talk naturally and agents respond based on the rules and skills loaded in your profile.

Starting work

You say	What happens
`"learn about this repo"`	Knowledge Manager scans the codebase and returns a structured summary of architecture, conventions, and entry points
`"what does the checkout flow do?"`	Agent traces the code path and explains the logic, referencing specific files
`"plan the user notifications feature"`	Planner breaks it into tasks with dependencies, ready for execution

Building

You say	What happens
`"add a retry mechanism to the webhook sender"`	Agent writes the implementation following your team's conventions (loaded via rules)
`"write tests for the payment service"`	Agent generates tests using your project's testing patterns and frameworks
`"refactor this into smaller functions"`	Agent restructures the code while preserving behaviour

Reviewing and shipping

You say	What happens
`"review my changes"`	Judge checks correctness, safety, and completeness against your team's standards
`"draft a PR"`	Technical Writer generates a PR description from your branch diff
`"is this ready to merge?"`	Judge validates tests pass, no TODOs remain, and conventions are followed

Managing knowledge

You say	What happens
`"teach the team about our error handling pattern"`	Knowledge Manager distills your description into a rule and deploys it to profiles
`"switch to the security profile"`	Swaps the active rule set — now agents apply security and compliance conventions
`"recruit an agent for frontend work"`	Knowledge Manager finds and installs a specialist from the Agency catalog

Slash commands

For structured workflows, slash commands give you precise control:

Command	What it does
`/write-plan`	Generate a formal implementation plan
`/judge`	Code review with structured findings
`/judge-audit`	Deep adversarial audit of any output
`/rune`	Dispatch agents in parallel waves
`/km-learn`	Research a repo, feature, or domain
`/tw-draft-pr`	Draft a PR description

Natural language and slash commands are interchangeable. Use whichever feels right for the moment. The agents respond to both.

Next steps

move_to_inbox

Knowledge Pipeline

Teach agents your team’s conventions

swap_horiz

Profiles

Switch knowledge for different tasks

smart_toy

Meet the Agents

See who’s on the team

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

hub The Four-Phase Model

Four phases that take a loose request and deliver verified, shippable output.

One generalist agent doing everything is like one developer who's also the database engineer, security auditor, frontend dev, and infra architect. The work happens — but not as well as a specialist would do it, and definitely not in parallel.

Knowledgeable agents are specialists. Each one arrives with relevant rules already loaded. A Go developer agent knows your module layout. A security agent knows your compliance requirements. The rules carry the expertise — not the conversation history.

Every meaningful task follows the same lifecycle:

Phase 1: EXPLORE  →  Phase 2: PLAN  →  Phase 3: BUILD  →  Phase 4: VALIDATE
(understand)        (decompose)       (implement)         (verify + ship)

Phase 1: Explore

Before we do anything, we understand the problem. We dispatch read-only agents in parallel to gather context from different angles. They research, analyse, and return summaries — they never write code.

════════════════════════════════════════════
  DAG DISPATCH PLAN
  Tasks: 5  |  Waves: 2  |  Type: research
════════════════════════════════════════════

  Wave 0  --- 4 parallel -----------------------
  🔧  t1  developer         Read existing API structure
  🔍  t2  researcher        Check upstream data sources
  🛡  t3  security          Assess compliance requirements
  🧪  t4  tester            Review current test coverage

  Wave 1  -----------------------------------------
  ⚖️  t5  judge             Synthesize all findings
                              ↳ depends on: t1, t2, t3, t4

════════════════════════════════════════════

Why this works: Four agents read four different parts of the codebase at the same time. Each returns a 2–3 sentence summary. The Judge in wave 1 merges them into one clear picture. Total wall time: roughly 2 minutes. Doing it one by one: roughly 8.

Key principle: Subagents are context collectors, not implementers. They read and report. The main conversation (or the Planner) takes their findings and builds the plan.

Phase 2: Plan

The Planner takes those findings and produces a structured plan. This is where the DAG (Directed Acyclic Graph) comes in. A good plan spells out what needs to happen, who owns each task, what depends on what, and what can run in parallel.

tasks:
  - id: t1
    agent: developer
    title: Implement API endpoint
    depends_on: []
    files: [src/api/]
    output: Working endpoint with validation

  - id: t2
    agent: developer
    title: Implement data layer
    depends_on: []
    files: [src/db/]
    output: Database queries and migrations

  - id: t3
    agent: developer
    title: Wire API to data layer
    depends_on: [t1, t2]
    files: [src/api/, src/db/]
    output: Integrated endpoint with persistence

  - id: t4
    agent: reviewer
    title: Review implementation
    depends_on: [t3]
    files: [src/]
    output: Review feedback

Critical path: t1 → t3 → t4  (3 of 4 tasks = 75%)
Benefit: 4/3 = 1.33x

Tasks t1 and t2 don't depend on each other — different files, different concerns. They run at the same time in wave 0. Task t3 needs both to finish first. Task t4 reviews everything at the end.

Phase 3: Build

The DAG dispatcher picks up the plan and runs it wave by wave:

Wave 0: Launch independent tasks in parallel
Collect results: Each agent hands back a summary of what it built
Inject context: Condense wave 0 results into wave 1 prompts (2–3 sentences per predecessor — never dump raw output)
Wave 1: Launch dependent tasks with context from their predecessors
Repeat until every wave completes
Report: Surface token usage, cost, and time saved

Passing context between waves

Wave 0 finishes. Each agent returns a short summary. The dispatcher condenses these into the next wave’s prompt:

Predecessor results:
- t1 created POST /v1/retirement in internal/handler/retirement.go.
  Accepts JSON, returns 200. Route registered in server/routes.go.
- t2 created compute_l19() in src/calc/l19_retirement.py.
  Function signature: compute_l19(personal, financial, scenario_params).

Your task: Wire the endpoint to the calculation backend.

Task t3 gets exactly what it needs — the endpoint shape from t1 and the function signature from t2 — without wading through the hundreds of lines of code they wrote. That's context injection, not context dumping.

When something goes wrong

If a task fails, every task that depends on it is automatically blocked. The dispatcher reports the failure and gives you three options: retry, skip and carry on with unblocked tasks, or stop entirely. You decide — agents never silently swallow failures.

Phase 4: Validate

Build produces output. Validate makes sure it's correct, safe, complete, and ready to ship. This isn't a final wave bolted onto Build — it's a deliberate quality gate with its own agents and criteria.

Validate agents work independently from Build. They receive the finished output and review it without the bias of having written it.

Agent	What they look at
code-reviewer	Correctness, test coverage, PII exposure
security-engineer	Compliance, threat model, DORA requirements
performance-engineer	SLA budgets, latency impact
Judge	Brings findings together, then gates or approves shipping

If Validate finds critical issues, it routes them back to the relevant Build agent for a fix — not to you first. Only genuinely unresolvable blockers escalate to a human.

In regulated environments, this maps neatly to your deployment review gate. The Judge brings findings together the same way a four-eye review aggregates feedback before a release.

When to keep it simple

Situation	What to do instead
Single-file bug fix	One agent, main conversation
Quick config change	No planning needed
Question about the codebase	Direct search or an Explore agent
Task fully within one agent’s domain	No handoff needed

Rule of thumb: If the task touches one file in one domain, just do it. If it spans multiple files across multiple domains, plan and dispatch.

Next steps

move_to_inbox

Knowledge Pipeline

How knowledge flows into your agents

swap_horiz

Profiles

Swap knowledge sets for different work

account_tree

DAG Dispatch

Context compression and parallel execution

🤔 Think about it: where in your current workflow are you doing things one by one that could safely run at the same time?

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

move_to_inbox Knowledge Pipeline

Teach your agents your team's rules and standards. Once loaded, every agent knows them.

AI agents start each session knowing nothing about your project. Without structured knowledge, every conversation begins from scratch. The Knowledge Pipeline changes that.

Three tools, one goal

Tool	What it does	Command
Rules	Structured knowledge files your agents follow	Files in `src/upvest-agency/rules/`
Profiles	Control which rules load per session	`toolkit profile use <name>`
Knowledge Manager	Feeds, shapes, and grows the rule base	`"hey knowledge manager"`

How it works

Step	What happens	Who
1. Ingest	Raw material lands in `src/upvest-agency/knowledge/`	You
2. Distill	Structured rules created in `src/upvest-agency/rules/`	Knowledge Manager
3. Wire	Rules added to profiles in `profiles/`	Knowledge Manager
4. Deploy	Profile redeployed with `toolkit profile reload`	You
5. Grow	Audits surface gaps, triggering fresh ingestion	Knowledge Manager

src/upvest-agency/knowledge/ is our staging area. Drop raw material in — PDFs, research summaries, extracted docs. The Knowledge Manager distils it into structured rules in src/upvest-agency/rules/. Always go through the inbox; never write directly to rules.

What makes a good rule

Criterion	Test
Actionable	Tells agents what to do, not just what to know
Structured	Tables, checklists, and code blocks over prose
Sourced	Claims tied to a specific source
Scoped	One coherent topic, not sprawling
Current	Version numbers, APIs, and pricing are accurate

A rule that says “BigQuery supports partitioning” is knowledge. A rule that says “Always partition tables by date. Set require_partition_filter = true” is actionable knowledge. The second one actually changes how agents behave.

Context budget

Every token loaded into an agent’s context takes space away from reasoning. We treat context like a budget:

toolkit profile budget

Aim to keep rules under 25% of the context window — that leaves 75%+ free for real work.

Next steps

swap_horiz

Profiles

How rules reach your agents

menu_book

Rules Catalog

Browse all 47 rules

payments

Token Economics

Why lean profiles matter

🤔 Think about it: what does a new team member need to know in their first week that an agent currently doesn't?

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

swap_horiz Profiles

Swap rules on the fly based on what you're working on. Focused context instead of loading everything.

Why profiles exist

Loading every rule into every session wastes context tokens and dilutes focus. A developer writing Go doesn't need GDPR compliance rules. A security reviewer doesn't need CSS conventions. Profiles solve this — swap the entire knowledge set with one command and keep context clean.

Think of it as role-based context. A platform engineer, a data analyst, and a security auditor all use the same agents and skills — but each loads only the rules relevant to their domain. Every token in context earns its place.

How profiles are organized

Profiles live in the profiles/ directory, one file per team plus a shared shared.yaml:

Section	Naming	Example
`profiles/<team>.yaml`	`<team>/<profile>`	`payments/product-engineer`, `data-platform/analyst`
`profiles/shared.yaml`	`shared/<profile>`	`shared/platform-engineer`, `shared/default`

Team profiles are owned by the team and carry domain-specific rules and skills. Shared profiles are not owned by any specific team and provide a general-purpose context. Personal profiles live in .local-profile.yaml (gitignored).

How to switch profiles

A profile controls which rules load into context. All agents and skills deploy to every profile — only the knowledge set changes.

Terminal

toolkit profile use my-profile    # deploy
toolkit profile budget            # measure footprint
toolkit profile list              # see all options
toolkit profile show my-profile   # preview contents

Raycast — prefer a visual interface? The Raycast plugin lets you browse and switch profiles without opening a terminal. From the repo root:

cd ai-toolkit && npm --prefix tools/raycast-plugin ci && npm --prefix tools/raycast-plugin run dev

Open Raycast, search Switch Profile, and pick from the list.

Design principles

Principle	Why
Lean over complete	Every token in context displaces reasoning space. Only include what the session actually needs.
One per task type	A data profile, a platform profile, a security profile. Each tuned to its domain.
Core is always loaded	Git, collaboration, and planning rules deploy to every profile. These are universal.
Personal variants	Customising a shared profile creates a personal variant. Shared profiles are never overwritten.

Profile examples

Profile	Section	Who uses it	Rules loaded
`shared/default`	shared	Full engineering	Core + engineering + infra + data
`shared/platform-engineer`	shared	Infra & DevOps	Core + infra + terraform + DORA
`data-platform/engineer`	teams	Data platform team	Core + data (SQL, dbt, Kafka, pipelines)
`payments/product-engineer`	teams	Payments team	Core + Go + gRPC + Kafka + domain patterns

The economics of specialisation

If a profile loads 80K tokens before you even ask a question, 40% of the agent's working memory is already gone. A focused profile that loads 25K tokens leaves 87% free for real work.

Profile	Token Load	% of 200K Window	Remaining for Work
Full (everything)	~80K	40%	120K
Default	~45K	22%	155K
Focused domain	~25K	12%	175K

This is why profiles exist. Not for tidiness — for cognitive headroom.

Next steps

move_to_inbox

Knowledge Pipeline

How we create rules

payments

Token Economics

Deep dive into cost and context

menu_book

Rules Catalog

Browse all 47 rules

🤔 Think about it: what kind of work are you doing right now? Load only the rules that belong to it.

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

tune Configure & Apply Profiles

Edit files in profiles/, deploy with one command. Agents and skills are always available — only the rules change.

Profile anatomy

Profiles are organized as separate files in the profiles/ directory:

# profiles/payments.yaml — team file (accessed as payments/product-engineer)
product-engineer:
  description: "Go microservices, Kafka, gRPC"
  agents:
    core:
      - general/knowledge-manager
      - general/planner
    engineering:
      - in-training/go-developer
  rules:
    eng:
      - go/go-versioning
      - go/go-eventing
  skills:
    - go/test-driven-development

# profiles/shared.yaml — shared profiles (accessed as shared/platform-engineer)
platform-engineer:
  description: "Infra and DevOps engineering"
  agents:
    core:
      - general/knowledge-manager
      - general/planner
  rules:
    infra:
      - infra/gcloud-cli
      - infra/terraform-conventions

Personal profiles go in .local-profile.yaml (gitignored). Use toolkit profile use <name> with the flattened name (e.g. payments/product-engineer).

Switching profiles

toolkit profile use <name>        # switch to a different profile
toolkit profile list              # see all available profiles

Creating a profile

Add your profile to the appropriate file in profiles/ (shared) or .local-profile.yaml (personal, gitignored)
Run toolkit validate to check for schema errors
Run toolkit profile use <name> to deploy

Personal variants

Customising a shared profile creates a {name} (custom) personal variant in .local-profile.yaml. This file is gitignored by default, so personal tweaks never pollute the shared repo. The shared profile in profiles/ is never overwritten. To share your customisation, move it to the appropriate file in profiles/ and open a PR.

Run toolkit profile list for the full list including personal variants.

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

account_tree DAG Dispatch

Run independent tasks at the same time. Pass results between them. Save time and tokens.

Define tasks with dependencies. /rune computes waves via topological sort and dispatches each wave in parallel. Independent tasks run at the same time. Dependent tasks wait their turn.

───────────────────────────────────────────
  DAG DISPATCH PLAN
  Tasks: 7  |  Waves: 3  |  Benefit: 1.8x
───────────────────────────────────────────

  Wave 0  --- 4 parallel -----------------------
  🏗  t1  architect         Design API contract
  🎨  t2  designer          Design UI components
  🔧  t3  developer         Set up database schema
  ✍  t4  writer            Draft documentation

  Wave 1  --- 2 parallel -----------------------
  🔧  t5  developer         Implement API and UI
                              ↳ depends on: t1, t2, t3
  🧪  t6  tester            Write tests
                              ↳ depends on: t1, t3

  Wave 2  -----------------------------------------
  🔍  t7  reviewer          Final review
                              ↳ depends on: t4, t5, t6
───────────────────────────────────────────

The context squeeze

The real efficiency gain here is context compression — a property of any subagent architecture, not just DAG dispatch. Each subagent starts with a fresh context window, does its work internally (reading files, parsing logs, running queries), and returns only a distilled summary. The heavy context disappears when the subagent finishes. Only the summary survives. This is also why we avoid mixing unrelated tasks in the same context window — see Context Hygiene for practical guidelines.

DAG dispatch amplifies this by running multiple subagents in parallel, so you get both compression and wall-time savings together.

Subagent internally: ~200K tokens (file reads, log parsing, dead ends)
  → Returns to parent: ~400 tokens.

Parent never sees the raw material. It sees only the distilled summary.

Subagents Dispatched	Total Work Done	Main Context Growth	Budget Used (200K window)
1	~200K tokens	~400 tokens	0.2%
5	~1M tokens	~2,000 tokens	1.0%
10	~2M tokens	~4,000 tokens	2.0%
20	~4M tokens	~8,000 tokens	4.0%

Context squeeze in practice

Here's what happens when you compare a monolith agent (one context window doing everything in sequence) with DAG dispatch (subagents with fresh contexts, only summaries returned). The longer the task list, the bigger the gap.

We're assuming each task processes roughly 200K tokens internally, each summary is roughly 400 tokens, and the monolith accumulates full context from every task. DAG dispatch accumulates only summaries, with an average parallelism factor of 2.5x (tasks per wave).

Tasks	Monolith Context	DAG Parent Context	Compression	Wall Time Savings
5	1M tokens	2,000 tokens	500x	~60%
10	2M tokens	4,000 tokens	500x	~60%
15	3M tokens	6,000 tokens	500x	~60%
25	5M tokens	10,000 tokens	500x	~60%

The compression ratio stays constant because each subagent is independent — but the absolute savings scale linearly. A 25-task DAG compresses 5M tokens of work into 10,000 tokens of parent context. That's the difference between a context window that overflows and one that stays fast and focused.

The wall-time savings come from parallelism: with an average of 2.5 tasks per wave, a 25-task DAG finishes in roughly 10 wave-steps instead of 25 sequential ones — about 60% faster.

The compounding effect

Context compression matters more as task counts grow. A 5-task DAG saves roughly 1M tokens of context pollution. A 25-task DAG saves roughly 5M. At 25 tasks, a monolith agent would blow past most context windows entirely — losing coherence, forgetting earlier results, or hallucinating. DAG dispatch keeps the parent context at 10,000 tokens regardless.

The DAG (Directed Acyclic Graph) format

tasks:
  - id: t1
    agent: architect
    title: Design API contract
    depends_on: []
    files: [docs/api-contract.yaml]
    output: API schema with endpoints and error codes

  - id: t2
    agent: developer
    title: Implement API handlers
    depends_on: [t1]
    files: [src/api/]
    output: Working handlers wired to database

Field	What It Does
`id`	Unique identifier — the task’s name in the dependency graph
`agent`	Who does the work — must match an agent in your team
`title`	What gets done — imperative verb phrase
`depends_on`	What must finish first — empty list means no prerequisites
`files`	What this task touches — used to detect conflicts between parallel tasks
`output`	What this task produces — tells dependent tasks what to expect

Validation

Six safety checks run before anything dispatches. All six must pass.

Check	What It Catches
Unique IDs	Two tasks with the same `id`
No cycles	t1 depends on t3, which depends on t1
No orphans	A task that nothing can reach
No file conflicts	Two parallel tasks writing to the same directory
Valid agents	An `agent` field that does not match any deployed agent
Valid references	A `depends_on` pointing to a task ID that does not exist

Ad-hoc dispatch

You don't always need a formal plan. Just say /rune with a natural language request and the dispatcher builds a DAG on the fly.

How the DAG runs tasks

A DAG doesn't care what happens inside its tasks — only the order and conditions. The task's agent handles execution. The DAG handles coordination. This separation is what makes it composable: any task can be swapped, retried, or parallelised without redesigning the whole plan.

Trigger rule

Every task uses the implicit rule all_success: a task only runs when all of its upstream dependencies have completed successfully. Failures and skips cascade downstream — if a task is BLOCKED, everything that depends on it is also BLOCKED. This is intentional. A task that needed a result from a failed upstream task should not run with incomplete inputs.

Upstream state	Downstream task becomes
All succeeded	Runs
One failed	BLOCKED
One skipped	BLOCKED (cascade)

Common topologies

Pattern	Shape	When to use
Fan-out	1 → [t2, t3, t4]	One task produces work that can be done in parallel
Fan-in (join)	[t1, t2, t3] → 1	Multiple parallel branches converge at a review or merge step
Diamond	t1 → [t2, t3] → t4	Fan-out then fan-in; t4 waits for both branches
Pipeline	t1 → t2 → t3	Strictly sequential; use sequential execution instead of DAG

Keep the topology stable — the shape of the dependency graph should be predictable before dispatch begins. Use DAG structure for orchestration decisions, not for conditional logic mid-run.

Next steps

payments

Token Economics

Cost tracking and context budgets

smart_toy

Agents

Meet the team that runs the tasks

hub

Four-Phase Model

The full workflow

🤔 Think about it: parallel and sequential cost the same tokens — parallel just burns them faster. Is the speed worth the added coordination?

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

smart_toy Agents

✍️

technical-writer

Use this agent when you need to create, improve, or maintain technical…

Use this agent when building or modifying the Upvest Upfront platform —…

AgentExplore

🔬

ux-researcher

Use this agent when you need user behavior analysis, usability testing…

Python (1)

AgentBuild

🐍

python-developer

Use this agent when you need to build type-safe, production-ready Python code…

Teams/Data Platform (4)

AgentExplore

📈

data-analyst

Use when you need to extract insights from business data, write or review dbt…

AgentBuild

📈

data-analytics-engineer

Use this agent when building or modifying dbt intermediate and mart models,…

AgentBuild

⚙️

data-engineer

Expert data engineer for Upvest's data platform — Kafka→BigQuery streaming…

AgentValidate

⚠️

data-risk-manager

Use this agent when investigating P&L risk, position exposure, FX risk,…

Workflows/Incident Investigation (1)

AgentExplore

📊

datadog-assistant

Use this agent when investigating production health, errors, performance…

Workflows/Shell Configuration (1)

AgentBuild

🐚

shell-config

Shell configuration specialist for macOS zsh environments. Manages prompt…

Workflows/Validation (2)

AgentValidate

🔍

code-reviewer

Expert code review specialist. Proactively reviews code for quality, security,…

AgentValidate

⚖️

judge

The Judge — supreme validation authority over all Upvest dream team agents (23…

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

person_add Onboarding an Agent

Add a specialist to your team. Either recruit one from the open-source catalog, or write one yourself.

Every agent is a plain markdown file. The YAML frontmatter tells the AI tool how and when to use the agent. The body is the system prompt — the instructions the agent follows.

Two paths

Path	When to use it	How to start
Recruit from catalog	A specialist already exists that fits your need	`/km-recruit [description]` — pulls from msitarzewski/agency-agents
Write from scratch	Your domain is specific and no catalog match exists	Create a `.md` file and follow the steps below

Step 1 — Create the file

All new agents go in src/upvest-agency/agents/in-training/. This is a staging area. Agents stay here until you are confident they work well. Use the naming pattern domain-role.md.

src/upvest-agency/agents/in-training/upvest-product-my-specialist.md

Do not place new agents directly in core/, data/, or engineering/. Those are for agents that have been validated in real use.

Step 2 — Write the frontmatter

The frontmatter is the first block in the file, between two --- lines. Every field below controls how the agent appears and behaves.

---
name: upvest-product-my-specialist
description: Use this agent when you need to... Also invoke when
  the user says 'hey my-specialist' or any similar phrase.
model: sonnet
tools: Read, Write, Edit, Bash, fd, rg, Glob, Grep, mcp:upvest_mcp_gateway
color: teal
emoji: "🔍"
version: 1.0.0
phase: build
---

All frontmatter fields

Field	Required	What it does	Allowed values
`name`	Yes	Unique identifier. Used in task plans and dispatch diagrams.	Lowercase, hyphens only. Example: `upvest-data-analyst`
`description`	Yes	Tells the AI when to invoke this agent. Write trigger phrases here.	Plain text. Include “Also invoke when the user says…” examples.
`model`	No	Which AI model this agent uses. Match the model to the phase.	`haiku` (explore/coordinate) · `sonnet` (build) · `opus` (plan/validate)
`tools`	No	Which tools the agent can use. Restrict to what it actually needs.	Comma-separated: `Read`, `Write`, `Edit`, `Bash`, `fd`, `rg`, `Glob`, `Grep`, `mcp:upvest_mcp_gateway`
`color`	No	Card border color in the docs site.	`red` · `orange` · `yellow` · `green` · `teal` · `cyan` · `blue` · `indigo` · `violet` · `purple` · `pink` · `gray`
`emoji`	No	Icon shown in dispatch diagrams and the agent card.	Any single emoji. Example: `"🔧"`
`version`	No	Semantic version. Increment when you make significant changes.	Format: `1.0.0`
`phase`	No	Which phase of the four-phase model this agent belongs to. Used for grouping in the docs site.	`explore` · `plan` · `build` · `validate`

Step 3 — Write the system prompt

The body of the file (everything after the closing ---) is the agent’s system prompt. This is what the agent reads before every task.

A good system prompt has three parts:

Role statement. One sentence. Who is this agent and what is their specialty?
Core responsibilities. Three to five bullet points. What does this agent do?
Collaboration. Which agents does it hand off to? Which agents hand off to it?

---
(frontmatter here)
---

> Agent collaboration: see `rules/core-agent-collaboration.md`

# My Specialist

You are a specialist in [domain]. Your job is to [one sentence purpose].

## Core responsibilities

- [What you do — be specific]
- [What you do — be specific]
- [What you do — be specific]

## Collaboration

- Route to `core-judge` when your output needs validation
- Receive from `core-planner` when tasks are assigned to you

Step 4 — Register in a profile

An agent file alone does nothing. You must add it to a profile so it deploys to your AI tool.

Open profiles/. Find the profile you want to add the agent to. Add the agent name under an agent group.

my-profile:
  agents:
    specialist:
      - upvest-product-my-specialist  # add this line

Step 5 — Validate and deploy

toolkit validate         # check frontmatter against the schema
toolkit profile reload   # deploy to your AI tool

If validation fails, the error message tells you which field is wrong and what values are allowed. Fix it and run again.

Step 6 — Test the agent

Open your AI coding tool in any project. Type a trigger phrase from the agent’s description field. If the agent responds, it is working.

To see all deployed agents: toolkit verify

Step 7 — Promote out of in-training

When you are confident the agent works well in real tasks, move it from src/upvest-agency/agents/in-training/ to the appropriate domain folder:

Folder	Who goes here
`src/upvest-agency/agents/general/`	Orchestration agents. Planner, Judge, Technical Writer, Knowledge Manager only.
`src/upvest-agency/agents/data/`	Data platform specialists — dbt, Kafka, BigQuery, analytics.
`src/upvest-agency/agents/engineering/`	Software engineering specialists — Go, Python, platform, security.
`src/upvest-agency/agents/in-training/`	All new agents start here. Move them when they are ready.

Promotion is a deliberate choice. It signals that the agent has been validated in real use and is ready for others on the team to rely on.

🤔 Take a moment: What does your team repeat every sprint that an agent with the right rules could do instead?

1 · Orientation

2 · First Run

3 · Customise

4 · Contribute

terminal Skills

Skills are slash commands that trigger structured workflows. They load on demand — zero tokens until invoked.

Agent	Phase	Why Opus
core-planner	Plan	Resolves ambiguity and constructs the Directed Acyclic Graph (DAG). A bad dependency graph cascades into race conditions or wasted parallel work. One Opus call here avoids many Sonnet rework calls later.
core-judge	Validate	Cross-domain adversarial verification. A cheap reviewer produces cheap reviews — misses the security issue, approves the broken migration, ships the PII leak. Opus is our only viable choice for the final gate.

Agent	Why Sonnet, not Opus	Why Sonnet, not Haiku
core-knowledge-manager	Distillation and toolkit ops need judgment, not adversarial review	Rule creation and profile decisions go beyond template-following
go-developer, python-developer	Code quality stays bounded by the plan — no ambiguity to resolve	Production code needs language reasoning and error handling judgment
data-engineer, analytics-engineer	Schema and pipeline logic is well-scoped; no cross-domain synthesis needed	SQL correctness and dbt model design go beyond pattern matching
platform-engineer, protocol-engineer	Infrastructure decisions stay within a plan, not open-ended	K8s manifests, Terraform, and gRPC schemas need structural reasoning
security-engineer	DORA compliance assessment follows defined frameworks	Threat modelling and compliance analysis are too nuanced for templates
code-reviewer	Reviews completed output within defined criteria	Catching subtle correctness issues, N+1 queries, and PII leaks needs real reasoning depth
software-architect	Refactoring plans are scoped, not adversarial	Safe refactoring needs understanding of call graphs, blast radius, and ordering
performance-engineer	SLA analysis applies known thresholds to observed data	Latency root cause and budget calculations go beyond simple lookup
ux-researcher, developer-advocate	Research synthesis is structured, not open-ended	Qualitative analysis and pattern extraction from user data need judgment
data-risk-manager	FIFO P&L logic is domain-specific but well-defined	Financial business rules and regulatory impact need careful reasoning

Agent	Why Haiku
core-technical-writer	Doc generation follows templates and style rules. Consistency and formatting are the job — no deep synthesis needed.
data-analyst	Read-only Looker/BigQuery work, dashboard summarization. Pattern recognition against known data shapes.
cicd-engineer	Pipeline config is template-driven. GitHub Actions and CI/CD YAML follow established patterns.
ops-tooling	Operational scripts and config management are mechanical. Low ambiguity, high repetition.
engineering-upfront	Frontend IAM and UI work follows component templates. No novel reasoning required.
product-manager, product-technical-manager	Ticket writing, backlog grooming, and stakeholder communication follow defined formats.
business-analyst	Requirements translation from regulatory specs to engineering tickets. Template-driven output.
customer-success-engineer	Ticket categorization, escalation routing, and client communication follow playbooks.
delivery-manager	Release coordination and dependency tracking. Primarily information aggregation and status formatting.

Scenario	Agents	Tokens	Estimated cost
All Opus, always	10 explore + 8 build + 2 validate	2M total	~$30.00
Pyramid model (Haiku/Sonnet/Opus)	Same 20 agents	2M total	~$6.50
All Haiku, always	Same 20 agents	2M total	~$0.50 — but plan quality and review depth suffer

What Loads	When	Typical Size
Agent frontmatter (all agents)	Session start	~2K tokens
Rules (per profile)	Session start	20-80K tokens
Hooks	Session start	~1K tokens
Skill full text	When slash command invoked	2-5K tokens per skill
Agent full prompt	When sub-agent dispatched	3-10K tokens per agent

Profile Strategy	Token Load	% of 200K Window	Reasoning Space
Load everything	~80K	40%	120K — constrained
Domain-specific	~35K	17%	165K — comfortable
Minimal + on-demand	~15K	7%	185K — maximum headroom

Indicator	Tier	Range	Typical cause
🟢	Low	< $5	Haiku agents, small plans
🟡	Medium	$5 – $20	Mixed Sonnet agents, 4–8 tasks
🔴	High	> $20	Opus agents or large parallel fans

Stage	Volume	What Happens
Raw input	~40 MB (10 agents × 4 MB)	Documentation, specs, code, logs fed to parallel subagents
First distillation	~200–400 KB	Each agent produces structured rules from its 4 MB slice
Refinement pass	~40–80 KB	A synthesis agent merges, deduplicates, and tightens the rules
Final polish	~10–20 KB	LLM-friendly formatting: tables over prose, checklists over paragraphs, code blocks over descriptions

Pass	Value Captured	Cost	Recommendation
First distillation	~80%	Base cost	Always do this
Refinement	~15%	+50% of base	Do for critical rules
Polish	~5%	+30% of base	Only for rules loaded in every session

File	Purpose
`plans/`	Saved DAG plans from `/write-plan` and `/rune`
`history/`	Execution logs with token usage, cost, and timing
`_pipeline-status.json`	Current pipeline state for the `on-stage-complete` hook

Model	Input (per 1M tokens)	Output (per 1M tokens)
Opus	$15.00	$75.00
Sonnet	$3.00	$15.00
Haiku	$0.25	$1.25

PM Responsibility	Planner Equivalent
Scope decomposition	Breaks feature into atomic tasks (WBS leaf nodes)
Resource assignment	Assigns an agent type to each task
Sequencing	Defines `depends_on` relationships between tasks
Schedule optimization	DAG dispatcher computes waves for maximum parallelism
Risk identification	File conflict detection, cycle detection, orphan detection
Progress tracking	Wave-by-wave execution with token and cost reporting

Mechanism	How it prevents diverging context
Phases	Explore, Plan, Build, and Validate each have a focused goal. You don’t ask a Build agent to also validate. You don’t ask an Explore agent to also write code.
Subagents	Each task dispatched by `/rune` gets a fresh context window. It reads what it needs, does its work, and returns a short summary. The heavy context dies when the task ends.
Profiles	Each profile loads only the rules relevant to one type of work. A security profile doesn’t load SQL conventions. A data profile doesn’t load compliance checklists.
Rules	Rules are pre-loaded at session start — not discovered mid-task. This keeps the conversation itself free for actual work instead of background reading.

#	Principle	AI Toolkit Mapping
1	Continued justification	Every plan must have a valid reason to proceed. If justification weakens, agents escalate rather than build work that delivers no value.
2	Learn from experience	Our Knowledge Manager captures lessons and distils them into rules. Each cycle refines what agents know before the next task starts.
3	Clear roles and responsibilities	Every task is assigned to a named agent. Ownership is explicit in the DAG — no task is unowned, no boundary is ambiguous.
4	Stage-by-stage delivery	The four-phase model (Explore → Plan → Build → Validate) breaks work into stages with clear handoffs. No phase begins until the prior one is complete.
5	Manage by exception	Agents operate autonomously within their scope. They escalate to you only when a tolerance is breached — a failure, a conflict, or a decision outside their authority.
6	Focus on outputs	Every task defines its `output` field before work begins. The DAG is a plan of deliverables, not just activities.
7	Tailor to context	Profiles adapt the knowledge set to the task. A security review loads different rules than a feature build. Planning depth matches project scale.

Project Management	DAG Dispatch
Tasks take hours to weeks	Tasks take seconds to minutes
Resources are humans with judgment	Resources are LLMs following rules
Communication is rich and nuanced	Communication is compressed summaries between waves
Replanning is expensive	Replanning is cheap — generate a new DAG
Scope creep is a risk	Scope is fixed by the plan; agents do not add work

Property	Behaviour
Synchronous	Blocks until the check finishes. The command can’t race past it.
Stateless	Each command is evaluated independently. No session state.
Fail-open	If the config is missing, all commands pass. A broken config won’t lock you out.
Zero dependencies	Includes a minimal YAML parser. No PyYAML needed.

Pattern	Catches	Severity
`rm-recursive-force`	`rm -rf`, `rm -fr`, `rm -r -f`, all flag orderings	Block
`rm-recursive`	`rm -r`, `rm --recursive`	Block

Pattern	Catches	Severity
`drop-table`	`DROP TABLE` (case-insensitive)	Block
`drop-database`	`DROP DATABASE`	Block
`drop-schema`	`DROP SCHEMA`	Block
`alter-table-drop`	`ALTER TABLE ... DROP`	Block
`delete-from`	`DELETE FROM`	Block
`truncate`	`TRUNCATE`	Block

Pattern	Catches	Severity
`git-force-push`	`git push --force` (allows `--force-with-lease`)	Block
`git-reset-hard`	`git reset --hard`	Block
`git-clean`	`git clean -f`	Block
`git-checkout-dot`	`git checkout .`	Block
`git-restore-dot`	`git restore .`	Block
`git-branch-force-delete`	`git branch -D`	Block

Pattern	Catches	Severity
`kubectl-delete`	`kubectl delete`	Block
`terraform-production-apply`	`terraform apply` + production keywords	Block
`bq-all-commands`	All `bq` CLI commands	Block

Pattern	Catches	Severity
`gcloud-auth`	`gcloud auth`	Block
`gh-auth`	`gh auth`	Block
`confluent-auth`	`confluent login`	Block

Field	Required	Description
`name`	Yes	Identifier for logs and messages
`match`	Yes	Python regex matched against the command
`flags`	No	`i` for case-insensitive
`message`	Yes	Shown to the user when blocked
`severity`	Yes	`block` (prevent) or `warn` (allow with warning)

Extension	Commands	Condition
`.py`	`ruff check --fix`, `ruff format`	—
`.sql`	`sqlfluff fix --force`	`dbt/dbt_project.yml` exists
`.sqlx`	`sqlfluff fix --force`	`dbt/dbt_project.yml` exists
`.go`	`goimports -w`	—
`.tf`	`terraform fmt`	—

Field	Required	Description
`extension`	Yes	File extension without the dot
`commands`	Yes	List of commands. Use `{file}` as placeholder for the file path.
`timeout`	No	Max seconds per command (default: 10)
`condition`	No	Only run if this file exists relative to project root

Field	Description
`workflow`	Name of the active workflow
`current_stage`	Stage that just completed
`ticket`	Associated ticket or task ID
`next_agent`	Suggested agent for the next stage (empty if all done)

Group	What it manages
`agent`	Agent definitions (Markdown + YAML frontmatter)
`rule`	Rule files loaded into agent context
`skill`	Slash-command workflows
`profile`	Profile composition, deployment, budget
`mcp`	MCP server enable/disable per profile
`team`	Team global instructions deployed to `~/.claude/CLAUDE.md`
`tool`	Optional system tools (e.g. ripgrep, sqlfluff)

Option	Description
`--format [text\|json]`	Output format on every `list` command. Default: `text`. Use `json` for scripting.
`--project <path>`	Target a project-local `.claude/` instead of `~/.claude/`. Supported by `profile use` and the `install`/`uninstall` verbs. MCPs are skipped for project installs.

Command	What it does
`toolkit profile use <name>`	Deploy a profile — replaces the previously active profile.
`toolkit profile use <name> --project <path>`	Deploy into `<path>/.claude/` instead of `~/.claude/` (project-local install). MCPs are skipped.
`toolkit profile list`	List all available profiles (shared and personal variants). Add `--format json` for scripting.
`toolkit profile show <name>`	Preview what a profile contains: agents, rules, skills, hooks, MCPs.
`toolkit profile current`	Print the currently active profile name.
`toolkit profile reload`	Redeploy the active profile — use after editing files in `src/`.
`toolkit profile budget`	Measure the token footprint of the active profile's rules.

Command	What it does
`toolkit agent list`	List resources, grouped by category. Use `--format json` for machine-readable output.
`toolkit agent show <name>`	Preview a single resource (frontmatter + body).
`toolkit agent add <name>`	Add the resource to the active profile and redeploy.
`toolkit agent remove <name>`	Remove the resource from the active profile and redeploy.
`toolkit agent install <name>`	Install a single resource ad-hoc (no profile edit). Honours `--project`.
`toolkit agent uninstall <name>`	Remove an ad-hoc-installed resource. Honours `--project`.

Command	What it does
`toolkit mcp list`	List all available MCP servers. Add `--format json` for scripting.
`toolkit mcp status [--profile <name>]`	Show which MCPs are enabled for a profile.
`toolkit mcp enable <name> [--profile <name>]`	Enable an MCP in the active (or specified) profile.
`toolkit mcp disable <name> [--profile <name>]`	Disable an MCP in the active (or specified) profile.

Command	What it does
`toolkit team list`	List available team global instructions.
`toolkit team use <name>`	Deploy team instructions to `~/.claude/CLAUDE.md`.
`toolkit team clear`	Remove deployed team instructions.

Command	What it does
`toolkit validate`	Validate all YAML files against JSON schemas and check agent frontmatter.
`toolkit verify`	Verify that installed resources match the managed state (detects drift).
`toolkit reset`	Remove all managed resources from platform directories. Prompts for confirmation.