🤖 AI-Powered Pipeline — v3.0

Build production-ready apps,
pipeline by pipeline.

CodeSleuth is a 7-agent software engineering pipeline powered by Python scripts and Go goroutines. From product idea to SHIP verdict — with human gates at every critical transition, parallel task execution, staged write approval, continuous SAST, coverage enforcement, and session forking.

⚡ Get Started 🏗️ Architecture ⌨️ Commands

🎯

Orchestrator

Agent 0

→

🔍

Discovery

Agent 1

→

📐

Planning

Agent 2

→

🔨

Builder

Agent 3

→

📊

Critic

Agent 4

→

🔒

Security

Agent 5

→

✅

Verifier

Agent 6

Directed by Agent 0 — Orchestrator · human gates between every stage

What's New in v3.0

Eight new capabilities ship in v3.0, powered by 17 Python + Go pipeline scripts that integrate directly into agent workflows.

⚡

Parallel Execution

Go goroutines execute independent task batches concurrently via parallel_runner.go. Write-conflict detection automatically splits conflicting tasks into sequential sub-batches.

🖊️

Staged Write Approval

Every file write shows a colored terminal diff before touching disk — powered by staged_write.py. No file is modified without explicit approval.

🍴

Session Forking

Run two pipeline branches in parallel via !fork. session_fork.py manages isolated copies with git branches. Use !merge to adopt the winner and clean up.

⏪

Pipeline Replay

Restore to any task checkpoint and resume from there using !replay TASK-NNN. pipeline_replay.py resets the codebase git state and marks later tasks PENDING.

🔎

Semantic Search

RAG-based codebase search using Ollama embeddings before every architecture-class task. semantic_search.py surfaces relevant existing code before new code is written.

🐳

Container Verification

Phase 12B of the Verifier builds a Docker image and runs the full test suite inside the container before issuing the final SHIP verdict. Catches environment mismatch bugs.

💰

Token Budget Tracking

Per-agent token usage, cumulative cost in USD, and context window % via !budget. token_tracker.py runs after every agent turn to keep spending visible.

🛡️

Migration Safety

Schema delta detection with data loss risk assessment and bidirectional SQL generation via migration_safety.py. HIGH severity risks block the pipeline until explicitly approved.

Explore the Docs

⚡

Quickstart

Get up and running in minutes. Load the Orchestrator and start your first pipeline session.

🏗️

Architecture

RARV cycle, artifact structure, Two-Phase Planning, Pattern Library, and state file system.

🌐

Platform Capabilities

Build for Web, Linux, Windows, macOS, Android, and iOS. Full toolchain, signing, and deployment guide.

🎯

Orchestrator

The conductor. Displays the startup banner, enforces human gates, manages Spec Change Protocol.

📐

Technical Planning

Full-contract planning in a single pass: TDD, INTERFACES, SCHEMA, TASK-GRAPH, Machine-Readable Contract Layer, and FILE_OWNERSHIP_MAP.

🔨

Application Builder

Continuous execution engine with Change Impact Tracking, contract validation, and STALE status management.

✅

Verifier

QA gate with Performance Budget enforcement, Contract Conformance Testing, and SHIP/NO-SHIP verdict.

📊

Critic

12-Dimension Product Scorecard with market intelligence tools and final survival verdict.

🧩

Pattern Library

Compounding knowledge base of reusable implementation patterns, indexed for instant lookup.

⌨️

Command Reference

Every command across all pipeline stages: gates, spec changes, pattern capture, and session control.

🔗

HANDOFF.json Schema

Six versioned HANDOFF.json schemas — one for each stage of the pipeline, progressively enriched.

🚦

Platform Gates

Tech stacks and quality gates for Web (Next.js), Desktop (Tauri, GTK4), CLI, Python, and AI platforms.

🐍

Pipeline Scripts

17 Python + Go tools that power v3.0 capabilities: staged writes, SAST scanning, parallel execution, semantic search, container verification, and more.

💡

Suggestion Tracker

29 pipeline enhancements implemented across agents and scripts — a living record of improvements and their current status.

What is CodeSleuth AI?

CodeSleuth AI is a structured, multi-agent software development system. Each agent has a precisely defined role, a set of absolute rules, and standardized artifact outputs that feed directly into the next stage.

No agent auto-advances. Every stage transition requires a human gate command (!plan, !build, !security, !verify).
RARV Cycle. Every agent follows Reason → Act → Reflect → Verify before producing output.
Full-contract Planning. Agent 2 produces TDD, INTERFACES, SCHEMA, TASK-GRAPH, Zod contracts, and the Parallelism Map in a single pass triggered by !plan.
Pattern Library. Every non-obvious implementation decision is captured in PATTERN_LIBRARY.md and reused across projects automatically.
Machine-Readable Contracts. The Planner emits Zod schemas and OpenAPI stubs that the Verifier independently validates — not just documentation.
Spec Change Protocol. Mid-build scope changes go through a formal !change flow — blast radius report, CHANGE_LOG.md entry, and STALE task marking — before any implementation starts.
Performance Budget Gate. Bundle sizes and API response times are enforced by scripts/perf.mjs with configurable budgets in .agent/PERF_BUDGET.json.
12-Dimension Product Scorecard. The Critic scores every product on 12 dimensions (1–5) before deep-dive critique. A score of 1 on any dimension is an automatic HOLD.
Multi-tool compatible. CLAUDE.md is the canonical agent activation file. Run node .cli/sync/sync-cli-instructions.mjs to propagate rules to Cline, Continue, Cursor, Copilot, Kiro, OpenCode, and 7 other tools. Each rule file embeds the Agent 0 Startup Protocol verbatim so all models produce a consistent banner.

ℹ️

Getting started

Type "Start agent 0" in any supported AI CLI or IDE to activate the Orchestrator. It will display the startup banner, initialize pipeline state, and guide you through the first human gate. See the Quickstart Guide for full details.

Pipeline at a Glance

Agent	Role	Gate Command	Primary Output
0 — Orchestrator	Director, never builder	`Start agent 0`	Pipeline state, gate enforcement, CHANGE_LOG.md
1 — Discovery	Spec author	Initial prompt	`feature-spec.md`, `HANDOFF.json v1`
2 — Planning	Technical architect	`!plan`	`TDD.md`, `TASK-GRAPH.md`, `INTERFACES.md`, contracts/
3 — Builder	Implementation engine	`!build`	Complete codebase, `CHECKPOINT.md`, `DECISIONS.md`
4 — Critic	Product accountability	`!critic`	`CRITICISM.md`, 12-D scorecard, product verdict
5 — Security	20-domain auditor	`!security`	`SECURITY_REPORT.md`, `HANDOFF.json v5`
6 — Verifier	QA & release gate	`!verify`	`VERIFICATION_REPORT.md`, SHIP/NO-SHIP verdict

v3.0 Upgrades at a Glance

Feature	What It Adds	Agents
Full-Contract Planning	Single-pass: TDD, INTERFACES, SCHEMA, TASK-GRAPH, Zod contracts, Parallelism Map	2
Spec Change Protocol	`!change` → blast radius → STALE marking	0, 3
Pattern Library	Compounding PATTERN-NNN knowledge across projects	2, 3
Machine-Readable Contracts	Zod + OpenAPI stubs validated by Verifier	2, 3, 5
Performance Budget Gate	Bundle KB + API p50/p95 enforcement	3, 5
12-Dimension Scorecard	D1–D12 product scores with auto-HOLD at 1	6
Change Impact Tracking	Reverse CIA — file ownership regression detection	3
Living Documentation	`!docs` generates human-readable changelogs	0

ℹ️

New in v3.0 — Pipeline Scripts and Suggestion Tracker

v3.0 ships 17 Python + Go scripts wired into agent workflows and a tracker of 29 implemented enhancements. See Pipeline Scripts and Suggestion Tracker for the full details.