Key Concepts

Key concepts

This page defines the core vocabulary of WorkPilot AI. If you read just one page, read this one.

---

🤖 Agent

An agent is a program driven by an AI model (Claude, GPT-4, Gemini…) that performs a precise task: planning, coding, testing, fixing, documenting, etc.

Each agent has:

• a system prompt (apps/backend/prompts/<agent>.md) defining its role
• an assigned model (configurable per phase)
• a thinking budget (max_thinking_tokens)
• allowed tools (file read, bash, etc.)
• an isolated session via ClaudeSDKClient

WorkPilot AI uses exclusively the Claude Agent SDK to unify the agent layer. This centralizes logging, security hooks and error handling.

---

📝 Spec (specification)

A spec is a self-contained folder describing everything to do for a given task.

.workpilot/specs/001-feature-name/
├── spec.md                   # human-readable description
├── requirements.json          # structured acceptance criteria
├── context.json               # relevant files, dependencies
├── implementation_plan.json   # phased breakdown
├── qa_report.md               # QA review results
└── QA_FIX_REQUEST.md          # in-flight correction requests

The spec is the contract between user, agents, and validation system. It's also the persistence unit: you can resume an interrupted spec with --continue.

---

🎯 Acceptance criteria

Acceptance criteria are verifiable conditions written in the spec. Examples:

• "The /health endpoint returns 200 OK"
• "All existing tests pass"
• "A new integration test covers the 500 error case"

The QA Reviewer checks each criterion one by one. As long as one fails, the QA Fixer keeps correcting (up to 50 iterations max).

---

🌳 Worktree (git)

A git worktree is an isolated copy of the repo on a separate branch. WorkPilot AI creates a dedicated worktree for each task:

my-project/
├── .git/
├── src/                      # ← your main
└── .worktrees/
    └── workpilot-ai/         # ← isolated worktree where agents code
        └── src/

Why it matters:

• Your main branch cannot be broken by an in-flight task
• Multiple tasks can run in parallel without interference
• You can test the worktree like a normal project (npm run dev inside)
• If the result isn't right, a simple --discard removes the worktree

---

🧪 QA pipeline

After the Coder finishes, a validation loop kicks off automatically:

QA Reviewer  →  Criteria OK? →  [yes] Ready to merge
     ↓                [no]
QA Fixer  →  Correct and re-run
     ↓
(loop until success or 50 iterations)

The QA Reviewer reads acceptance criteria and verifies each. On failures, it produces a QA_FIX_REQUEST.md the QA Fixer reads and applies.

👉 More details: Multi-agent pipeline

---

🔀 Semantic merge

When multiple worktrees come back to main, classic git conflicts can appear. WorkPilot AI uses an AI semantic merge engine that understands each change's intent and combines them intelligently.

Example: if two tasks modify config.ts to add two different new keys, semantic merge preserves both — where a classic git merge would raise a conflict.

---

🎛 Mission Control

NASA-inspired multi-agent dashboard. It shows in real time:

• All running agents
• Their status (planning, coding, reviewing…)
• Token consumption per agent
• Modified files
• Live thinking (chain-of-thought)
• Global budget and cost alerts

Especially useful when multiple tasks run in parallel.

---

🧠 Memory (Graphiti)

Graphiti is a semantic graph memory system that lets agents retain knowledge across sessions. Instead of rediscovering your project on every task, agents can query:

• "What have I learned about authentication in this project?"
• "Which files are related to feature X?"
• "What code style does the team prefer?"

Graph nodes = entities (files, classes, concepts), edges = relationships (imports, calls, depends on, etc.).

👉 More details: Memory system

---

⚡ Skills (dynamic capabilities)

Skills are reusable and optimized agent capabilities: framework migration, refactoring, test generation, etc.

Features:

• Token optimization (compressed metadata, ≤ 512-char descriptions)
• Context management (aggressive compaction at 70% of budget, checkpoints)
• Delegation to subagents (default max_workers=3, 25s timeout)
• Dynamic registration (runtime validation)

A skill is invoked via skill_manager:

result = await skill_manager.execute_skill(
    skill_name="framework-migration",
    action="analyze",
    context={"framework": "react", "project_path": "/path/to/project"}
)

---

🔗 MCP (Model Context Protocol)

MCP is an open standard to connect LLMs to external tools (databases, APIs, filesystem, browsers…). WorkPilot AI includes:

• An MCP Marketplace to browse and install MCP servers
• Support for custom MCPs with local authentication
• Built-in integrations: Chrome DevTools MCP, Electron MCP, grepai…

👉 More details: Integrations

---

👤 Claude profile

A Claude profile is a credentials set (OAuth or API key) for an AI account. WorkPilot AI lets you register multiple profiles and auto-switches between them:

• Rate limit hit on account A → auto-switch to account B
• Scored by availability and recent usage (profile-scorer.ts)
• Secure storage in OS keychain (Keychain / Credential Manager)
• Automatic OAuth token refresh

---

🔒 Sandbox and allowlist

Each agent execution runs under three security layers:

1. OS Sandbox — bash commands run in isolation
2. Filesystem restrictions — operations limited to project directory
3. Dynamic allowlist — commands approved based on detected stack (no rm -rf /, no unexpected network access…)

👉 More details: Security

---

📊 Workflow Logger

Structured logging for all executions (agents, skills, hooks) with:

• 🤖 Agent logs
• ⚡ Skill logs
• 🪝 Hook logs
• Trace IDs to correlate events
• Automatic durations
• Human-readable + JSON output

File: logs/workflow.log.

---

🧭 Complexity tier

Each task is automatically classified by the assessment agent into three levels:

Tier	Phases	Trigger
SIMPLE	3	1-2 files, no integration
STANDARD	6	3-10 files, 1-2 services
COMPLEX	8	10+ files, multi-service, external integrations

The phase count influences planning depth and QA check robustness.

---

Next step

➡️ User interface tour