The Big Picture
Understand how all the pieces of the AI toolkit fit together. This conceptual overview is designed for technical people who want to grasp the mental model before diving into specifics.
Jump to a concept
- Agents— Primary vs sub-agents
- Agent Workflows— Update queues & coordination
- Skills— Task-specific workflows
- Meta-Skills— Generate project patterns
- Project Configuration— project.json & structure
- PRDs & Planning— The Agent Loop
- Testing System— Multi-layered architecture
- Vectorization— Semantic code search
- Scaffolds— Project templates
- The Human in the Loop— Your role in the system
- Roadmap— Upcoming features
System Architecture
The toolkit organizes AI capabilities into a layered system where each piece has a clear purpose.
Primary Agents
Sub-Agents (Specialists)
Skills
On-demand workflows loaded when needed (migrations, PRDs, screenshots...)
Project Context
project.json, CONVENTIONS.md, PRDs that guide agent behavior
How It All Works Together
You're always in control. The three primary agents—@planner, @builder, and @toolkit—are orchestrators that understand your requests and delegate work to specialized sub-agents. You choose which agent to invoke, review outputs, and approve changes.
Planner helps you turn ideas into structured PRDs with user stories. Builder executes those PRDs by delegating to domain-specific sub-agents—a React developer for components, a security critic for vulnerability checks, a tester for test coverage. Toolkit maintains and evolves the agent system itself.
When agents encounter complex, multi-step workflows, they load skills. A skill is a detailed instruction set—like a recipe—that guides the agent through tasks that benefit from explicit structure: database migrations, screenshot capture, merge conflict resolution.
All of this is informed by your project context. The project.json file tells agents about your tech stack, coding conventions, and active PRDs. This ensures agents produce code that fits your codebase—not generic boilerplate.
Working with the Primary Agents
These three agents are your entry points to the system. Each has a distinct role—Planner helps you think, Builder helps you ship, Toolkit helps you improve.
Planner
Turn ideas into implementation-ready PRDs
- • Creates and refines PRDs with user stories
- • Asks clarifying questions to tighten scope
- • Defines acceptance criteria
- • Never writes code—planning only
How you use it:
@planner I want to add [feature]...Builder
Execute PRDs and handle ad-hoc tasks
- • Implements user stories from PRDs
- • Delegates to specialist sub-agents
- • Runs quality gates and commits code
- • Handles quick fixes without PRDs
How you use it:
@builder Implement the PRD or @builder Fix the login bugToolkit
Evolve the agent system itself
- • Processes pending updates from agents
- • Creates and modifies agents, skills, scaffolds
- • Maintains toolkit-wide consistency
- • Used less frequently than Planner/Builder
How you use it:
@toolkit Review pending updatesHow They Work Together
- 1Plan — Start with
@plannerto create a PRD with user stories - 2Build — Hand the ready PRD to
@builderfor implementation - 3Improve — Agents discover gaps and queue updates for
@toolkit - 4Repeat — Better agents lead to better planning and building
This is the Agent Loop. Each phase has clear ownership between you and the agents.
See the full Agent Loop →Which Agent Should I Use?
| Scenario | Agent | Why |
|---|---|---|
| New multi-story feature | Planner | Needs requirements before code |
| Quick bug fix | Builder | Scope is clear, just implement |
| Implement a ready PRD | Builder | Planning done, time to ship |
| Refine unclear requirements | Planner | Need to explore before building |
| Improve an agent's behavior | Toolkit | Meta-level toolkit change |
For detailed decision trees, see the Human in the Loop guide.
Explore Each Concept
Dive deeper into how each piece of the system works.
Agents
AI-powered specialists that perform development tasks autonomously. Primary agents orchestrate work; sub-agents handle specific domains.
Learn moreAgent Workflows
How agents communicate through asynchronous update queues. A self-improving system where agents discover gaps and queue improvements — all under your control.
Learn moreSkills
Loadable instruction sets for complex workflows. Agents invoke skills on-demand to handle specialized tasks like migrations, screenshots, or PRD creation.
Learn moreProject Configuration
The project.json file tells agents about your tech stack, conventions, and integrations. It enables context-aware assistance.
Learn morePRDs & Planning
Product Requirements Documents guide multi-step development. Learn how agents use PRDs to understand what to build and track progress through user stories.
Learn moreScaffolds & Templates
Pre-built project structures that bootstrap new codebases with best practices. Start a project with the right patterns from day one.
Learn moreMulti-Session Coordination
How multiple agent sessions work together without conflicts. Learn about session locks, update queues, and branch management for parallel work.
Learn moreTesting System
How the multi-layered testing architecture works. Unit test specialists, E2E testing, QA/adversarial testing, and three operating modes for different needs.
Learn moreVectorization
Semantic code search powered by embeddings. Vectorization lets agents find relevant code by meaning, not just keywords — enabling better context retrieval for large codebases.
Quick Links