A local-first, file-based workflow system that orchestrates AI agents across feature completion — from brainstorming to finalized content artifacts — using shared context and structured handoffs.
- Overview
- Architecture
- Pipeline Stages
- Getting Started
- After Clone Customization
- How Agents Pick Up Context
- Shared Context Layer
- Handoff System
- Usage Guide
- Spec Lifecycle
- Error Handling & Feedback Loops
- Project Structure
This workspace uses a 6-stage pipeline to manage feature completion lifecycle. Each stage is implemented as an Agent Skill (.agents/skills/kd-*/SKILL.md) with matching Cursor slash commands (.cursor/commands/kd-*.md). Skills read from a shared context layer and pass structured work items through a file-based handoff queue.
Key design principles:
- Local-first — All state lives in the filesystem. No external services required.
- Context-sharing via symlinks — The
_context/folder is symlinked between the product decisions repo and the codebase, giving all agents a unified view of product state. - Structured handoffs — Work moves between agents through markdown files with YAML frontmatter in
_handoff/queue/, ensuring nothing is lost between sessions. - Human-in-the-loop — Every critical transition (spec approval, finalization) requires explicit user confirmation.
- Cross-agent compatible — Skills follow the open Agent Skills standard, working across Amp, Cursor, Claude Code, Codex, and more.
┌─────────────────────────────────────────────────────────────────────────┐
│ AGENT PIPELINE │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌────────┐ ┌────────┐ │
│ │ BRAINSTORM├───►│ HANDOFF-SPEC ├───►│ DEV ├───►│ QA │ │
│ │ Research │ │ Approve & │ │ Build │ │ Verify │ │
│ │ & Ideate │ │ Queue │ │ & Test │ │ & Gate │ │
│ └──────────┘ └──────────────┘ └────────┘ └───┬────┘ │
│ │ │
│ FAIL ◄────────┤ │
│ (loop back) │ PASS │
│ ▼ │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ CONTENT │◄──────────────────────┤ HANDOFF-DEV │ │
│ │ Blog, │ │ Finalize & │ │
│ │ Changelog│ │ Prepare Content │ │
│ └──────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
┌────┴────────────────────┴────────────────────┴────┐
│ _context/ (Shared State) │
│ product-state.md │ specs/ │ decisions/ │ metrics/ │
└───────────────────────────────────────────────────┘
User idea
│
▼
_context/specs/SPEC-XXX.md ← brainstorm creates draft
│
▼
_handoff/queue/HO-XXX.md ← handoff-spec creates ticket
│
▼
Codebase changes ← dev implements
│
▼
QA Report (in handoff ticket) ← qa verifies
│
▼
_handoff/queue/HO-XXX-content.md ← handoff-dev creates content ticket
│
▼
_context/content/YYYY-MM-DD-slug/ ← content generates artifacts
│
▼
_handoff/archive/ ← everything archived
| # | Stage | Command | Agent Role | Input | Output |
|---|---|---|---|---|---|
| 1 | Discovery | /kd-brainstorm |
Research & ideate solutions | User idea or problem | Draft spec in _context/specs/ |
| 2 | Approval | /kd-handoff-spec |
Validate & queue for dev | Approved spec | Handoff ticket in _handoff/queue/ |
| 3 | Development | /kd-dev |
Implement across one or more services | Handoff ticket | Code changes + tests |
| 4 | Quality | /kd-qa |
Run tests, lint, verify acceptance criteria | Completed dev work | QA report (PASS/FAIL) |
| 5 | Finalization | /kd-handoff-dev |
Finalize implemented work | QA-passed ticket | Content handoff ticket |
| 6 | Content | /kd-content |
Generate changelog, blog, docs | Content ticket | Content artifacts |
| Command | Description |
|---|---|
/kd-fix |
Bug Fix Fast Path — skip brainstorm/spec, go straight to dev |
/kd-status |
Show pipeline status — scan queue, group by status/agent, flag at-risk tickets |
/kd-review |
Structured diff-aware code review gate with blocking/non-blocking findings |
/kd-browser-qa |
Playwright-first browser QA evidence capture (screenshots/logs) for UI/web changes |
/kd-ship |
Finalization hygiene checks (non-deploy) before /kd-handoff-dev |
/kd-health |
Environment readiness checks for workflow skills and tooling |
Note: Playwright is a project dependency in target service repos under apps/*; it is not installed via MCP.
- An AI coding agent that supports the Agent Skills standard — for example Amp, Cursor, Claude Code, or OpenAI Codex
- Required MCP servers installed and configured:
- Ref MCP (documentation search/read): https://docs.ref.tools/install/index
- Exa MCP (web + code search): https://exa.ai/docs/reference/exa-mcp
- Context7 MCP (up-to-date library docs): https://context7.com/docs/installation
- Workspace with one or more project repos cloned:
Workspace/ └── apps/ └── <your-service>/ # Your repo(s): monorepo, separate FE/BE, or full-stack
Use your MCP client config and add this shared mcpServers block:
{
"mcpServers": {
"Ref": {
"type": "http",
"url": "https://api.ref.tools/mcp?apiKey=YOUR_REF_API_KEY"
},
"exa": {
"type": "http",
"url": "https://mcp.exa.ai/mcp"
},
"context7": {
"url": "https://mcp.context7.com/mcp",
"headers": {
"CONTEXT7_API_KEY": "YOUR_CONTEXT7_API_KEY"
}
}
}
}Client notes:
- Cursor: add in MCP config (for example
~/.cursor/mcp.json) or MCP settings UI. - OpenCode: add the same
mcpServersblock in OpenCode MCP configuration. - Codex: add the same
mcpServersblock in Codex MCP configuration. - Amp: add the same
mcpServersblock in Amp MCP configuration.
Notes:
- For Ref, you can also send the key as header
x-ref-api-keyinstead of query param. - For Exa, if your setup requires auth, follow Exa docs to pass API key.
1. Start a new feature:
/kd-brainstorm
> "I want to add real-time collaboration to the analysis page"
2. Check what's in the pipeline:
/kd-status
The agent scans _handoff/queue/ and reports pending work by priority, flags at-risk tickets.
3. Continue work on the next task:
> "Pick up next task."
The agent picks the highest-priority pending ticket and loads the appropriate skill.
4. Quick-fix a bug (skip brainstorm/spec):
/kd-fix Login fails when email contains plus sign
5. Run the full pipeline sequentially:
/kd-brainstorm → Draft & approve a spec
/kd-handoff-spec → Queue it for development
/kd-dev → Implement the feature
/kd-qa → Verify quality
/kd-handoff-dev → Finalize and create content handoff
/kd-content → Generate content artifacts
When someone clones this workflow template, update these items first so it matches your real project:
The apps/ directory holds one or more project repositories. Adapt to your setup:
| Setup | Example layout | Notes |
|---|---|---|
| Monorepo (FE + BE) | apps/my-app/ |
Single repo with both frontend and backend (e.g., Next.js full-stack, or separate src/api + src/web dirs) |
| Separate FE & BE repos | apps/api/ + apps/web/ |
Two repos, each with its own conventions and quality gates |
| Single framework | apps/my-app/ |
One repo, one framework (e.g., Next.js handling both FE routes and API routes) |
| Multiple services | apps/api/ + apps/web/ + apps/worker/ |
Three or more repos — document extras in AGENTS.md |
For each service/repo under apps/, create:
apps/<service>/AGENTS.md— agent conventions for that serviceapps/<service>/PRD.md— product requirements
For a single-repo setup (monorepo or full-stack framework), create these files in the repo root:
apps/my-app/AGENTS.mdapps/my-app/PRD.md
Include:
- language/framework conventions
- architecture boundaries
- quality gates (lint, typecheck, test commands)
- deploy/run commands
- required env vars
Adjust skill expectations to your stack:
- Python example gates (
ruff,mypy,pytest) if service is Python - Node/Frontend example gates (
npm run lint/build/test) if service is JS/TS - Replace defaults with your actual commands in service-level docs
- Replace
docs/deploy-project.shwith your real deploy script and command. - Add environment-specific release verification checklist.
Edit _context/product-state.md:
- product name/domain
- repository naming
- deploy model
Run a dry sequence with a small sample feature:
/kd-brainstorm/kd-handoff-spec/kd-dev/kd-qa
Ensure each stage reads/writes _context/ and _handoff/ correctly.
You do not need to paste a system prompt — the agent reads context automatically from:
AGENTS.md(root) — pipeline rules, workspace structure, agent behaviorCLAUDE.md— stage-by-stage rules, file standards, quality gates_context/product-state.md— current product info, active specs, priorities_context/lessons.md— cross-session memory (reviewed at session start)apps/<service>/AGENTS.md— service-specific conventions, tech stack, quality gatesapps/<service>/PRD.md— product requirements for that service
After completing the After Clone Customization steps, every agent session automatically has full project context. Just run a pipeline command (e.g., /kd-brainstorm) and the agent will load what it needs.
The _context/ directory is the single source of truth shared between all agents. It is designed to be symlinked between the product decisions repo and the codebase repos so that both Research Agents and Dev Agents operate on an identical state.
_context/
├── product-state.md # Current priorities, active specs, quality metrics
├── specs/ # Feature specifications
│ └── SPEC-XXX-feature-name.md # Lifecycle: draft → approved → implemented → archived
├── decisions/ # Architecture & product decision records
│ └── YYYY-MM-DD-decision.md # Immutable once recorded
├── research/ # Research notes, competitive analysis
│ └── YYYY-MM-DD-topic.md # Created by brainstorm agent
├── design/ # Design docs, wireframes, UX decisions
│ └── DESIGN-XXX-title.md # Referenced by specs
├── metrics/ # Quality metrics, KPIs, benchmarks
│ └── current-metrics.md # Updated by QA agent
└── content/ # Generated content artifacts
└── YYYY-MM-DD-feature-slug/ # Created by content agent
├── changelog.md
├── blog-draft.md
└── social-post.md
To share context between repos, create a symlink from each repo's root:
# On Linux/macOS
ln -s /path/to/Workspace/_context /path/to/docs-repo/_context
ln -s /path/to/Workspace/_context /path/to/codebase-repo/_context
# On Windows (run as Administrator)
mklink /D "D:\docs-repo\_context" "D:\Workspace\_context"
mklink /D "D:\codebase-repo\_context" "D:\Workspace\_context"- Append-only — Documents are never deleted; they move through lifecycle states and eventually get archived.
- Timestamped — Every entry carries an ISO 8601 date for traceability.
- Agent-tagged — Every entry records which agent created or modified it (e.g.,
[agent: brainstorm]). - Status-tracked — Specs follow a strict lifecycle:
draft → approved → implemented → archived.
The _handoff/ directory is the inter-agent work queue. It uses structured markdown files with YAML frontmatter to pass work between pipeline stages.
_handoff/
├── queue/ # Active work items awaiting pickup
│ └── HO-XXX-{from}-to-{to}-{title}.md
└── archive/ # Completed work items (audit trail)
└── (same naming convention)
Every handoff ticket follows this schema:
---
id: HO-001 # Unique identifier
from: brainstorm # Originating stage
to: dev # Target stage
priority: P1 # P0 (critical) | P1 (high) | P2 (normal)
status: pending # pending | in-progress | done | blocked
created: 2026-03-06T14:30 # ISO 8601 timestamp
spec: SPEC-001 # Reference to source spec
review_status: pending # pending | passed | failed
qa_gate_mode: fast # fast | full
qa_full_gate: pending # pending | passed | failed
---| From | To | Trigger |
|---|---|---|
brainstorm |
dev |
Spec approved via /kd-handoff-spec |
dev |
qa |
Implementation marked done (implicit — same ticket) |
qa |
dev |
QA fails — feedback loop with specific issues |
dev |
content |
QA passes with Full Gate (qa_full_gate: passed) → /kd-handoff-dev creates content ticket |
Start a product discovery session. The agent will:
- Load current product state and past decisions from
_context/ - Build a Fact Ledger (Known Facts, Unknowns, Assumptions) before proposing solutions
- Run mandatory parallel research tracks (codebase analysis + docs/best practices + external patterns when applicable)
- Explore the problem space with 2-3 solution approaches backed by research findings
- Produce a draft spec in
_context/specs/SPEC-XXX-title.md - Present the draft for your review
/kd-brainstorm
> "We need batch export — users want to download all analyses at once"
Output: Draft spec with problem statement, proposed solution, technical approach, acceptance criteria, source-backed decisions, and linked research notes.
Next step: Review the spec. When satisfied, run /kd-handoff-spec.
Convert an approved spec into a dev-ready handoff ticket. The agent will:
- Validate the spec has all required sections
- Update spec status from
draft→approved - Create a structured handoff ticket in
_handoff/queue/ - Update
_context/product-state.mdwith the active spec
/kd-handoff-spec
Output: Handoff ticket with implementation plan, file paths, and acceptance criteria.
Next step: Run /kd-dev to begin implementation.
Pick up the highest-priority handoff ticket and implement. The agent will:
- Scan
_handoff/queue/for pendingto: devtickets, sorted by priority - Load the spec, AGENTS.md conventions, and PRD requirements
- Implement across the impacted services as needed
- Run self-verification: lint, type-check, and relevant tests
- Update the handoff ticket with an implementation log
/kd-dev
Service conventions enforced (example for Python service):
- Python 3.10+, async/await, full type hints
ruff check && ruff format+mypy src+pytest
Service conventions enforced (example for Node/Web service):
- TypeScript strict mode, framework/client directives as required
npm run lint+npm run build+npm run test
Next step: Run /kd-qa to verify the implementation.
Run comprehensive verification against the completed work. The agent will:
- Execute all automated checks (lint, types, tests, contract verification)
- Review changed files against AGENTS.md conventions
- Verify each acceptance criterion from the spec
- Generate a structured QA report with PASS/FAIL verdict
/kd-qa
On PASS: Move forward with /kd-handoff-dev.
On FAIL: The existing ticket is returned to dev — QA appends its report, increments loop_count, and resets status: pending. Run /kd-dev to address the specific issues in the QA feedback.
Prepare QA-passed work for completion. The agent will:
- Verify the QA report shows PASS
- Ensure PRD and AGENTS.md documentation is updated
- Update spec status from
approved→implemented - Create a content handoff ticket with implementation and QA evidence
- Archive the original dev handoff ticket
/kd-handoff-dev
Next step: Run /kd-content to generate completion artifacts.
Generate content artifacts for the implemented feature. The agent will:
- Read the content handoff ticket and original spec
- Generate applicable content: changelog, blog post, social post, documentation updates
- Save all artifacts to
_context/content/YYYY-MM-DD-feature-slug/ - Archive the content ticket and mark the spec as
archived
/kd-content
Output directory:
_context/content/2026-03-06-batch-export/
├── changelog.md
├── blog-draft.md
├── social-post.md
└── docs-update.md
Pipeline complete.
Every feature spec passes through a strict lifecycle, tracked in its YAML frontmatter:
draft ──────► approved ──────► implemented ──────► archived
│ │ │ │
│ │ │ │
brainstorm handoff-spec handoff-dev content
creates it approves it code is done artifacts done
| Status | Set By | Meaning |
|---|---|---|
draft |
/kd-brainstorm |
Spec created, under review |
approved |
/kd-handoff-spec |
Spec approved, dev ticket queued |
implemented |
/kd-handoff-dev |
Code complete, QA passed, ready for content |
archived |
/kd-content |
Content generated, lifecycle complete |
The pipeline includes a built-in feedback loop at the QA stage:
┌──────────────────────────────┐
│ │
▼ │
┌──────────┐ FAIL ┌─────────┐
────────►│ DEV ├──────────────────►│ QA │
│ Implement│ │ Verify │
└──────────┘◄──────────────────┤ │
▲ feedback └────┬────┘
│ ticket │
│ │ PASS
│ ▼
│ ┌──────────┐
└────────────────────────┤HANDOFF-DEV│
(if issues found └──────────┘
during QA)
QA Failure Flow:
- QA agent identifies specific issues with evidence
- The existing ticket is reused — QA appends its report, increments
loop_count, and resetsstatus: pending - Dev agent picks up the same ticket on the next
/kd-devrun and reads the appended QA feedback - Cycle repeats until QA passes (escalates to user at
loop_count >= 3)
Workspace/
│
├── _context/ # Shared context layer
│ ├── product-state.md # Current product state & priorities
│ ├── specs/ # Feature specifications (lifecycle-tracked)
│ ├── decisions/ # Architecture decision records
│ ├── research/ # Research notes & analysis
│ ├── design/ # Design docs & UX decisions
│ ├── metrics/ # Quality metrics & KPIs
│ └── content/ # Generated content artifacts
│
├── _handoff/ # Inter-agent work queue
│ ├── queue/ # Active tickets awaiting pickup
│ └── archive/ # Completed tickets (audit trail)
│
├── .agents/ # Agent Skills (SKILL.md w/ frontmatter)
│ └── skills/ # Pipeline skill definitions
│ ├── kd-brainstorm/ # Stage 1: Discovery
│ ├── kd-handoff-spec/ # Stage 2: Approval
│ ├── kd-dev/ # Stage 3: Development
│ ├── kd-qa/ # Stage 4: Quality Assurance
│ ├── kd-handoff-dev/ # Stage 5: Finalization
│ ├── kd-content/ # Stage 6: Content
│ ├── kd-review/ # Utility: Structured review gate
│ ├── kd-browser-qa/ # Utility: Browser QA evidence
│ ├── kd-ship/ # Utility: Finalization hygiene
│ └── kd-health/ # Utility: Environment health checks
│
├── .cursor/ # Cursor slash commands (plain Markdown)
│ └── commands/ # Invoke via /kd-* in Cursor chat
│ ├── kd-brainstorm.md # Trigger kd-brainstorm skill
│ ├── kd-handoff-spec.md # Trigger kd-handoff-spec skill
│ ├── kd-dev.md # Trigger kd-dev skill
│ ├── kd-qa.md # Trigger kd-qa skill
│ ├── kd-handoff-dev.md # Trigger kd-handoff-dev skill
│ ├── kd-content.md # Trigger kd-content skill
│ ├── kd-fix.md # Bug Fix Fast Path (utility)
│ ├── kd-status.md # Pipeline status dashboard (utility)
│ ├── kd-review.md # Structured code review gate (utility)
│ ├── kd-browser-qa.md # Browser QA evidence capture (utility)
│ ├── kd-ship.md # Finalization hygiene (utility)
│ └── kd-health.md # Environment readiness checks (utility)
│
├── docs/ # Operational documentation
│ └── deploy-project.sh # Project deploy script (example name)
│
├── apps/ # One or more code repositories
│ └── <service>/ # Your repo(s): monorepo, FE/BE, or full-stack
│ ├── AGENTS.md # Service-specific agent conventions
│ └── PRD.md # Service requirements
│
├── AGENTS.md # Root orchestrator configuration
└── README.md # ← You are here
Adopt and customize for your project.