Version: 3.0 | Status: Active | Language: English

Audience: Developers using AI coding assistants, technical leads, engineering teams, DevOps engineers

Cyber Pilot — Deterministic Agent Tool for Structured Workflows

Cypilot is a deterministic agent tool that embeds into AI coding assistants and CI pipelines to provide structured workflows, artifact validation, and design-to-code traceability.

Everything that can be validated, checked, or enforced without an LLM is handled by deterministic scripts; the LLM is reserved only for tasks that require reasoning, creativity, or natural language understanding.

Problem

• AI Agent Non-Determinism — AI agents produce inconsistent results without structured guardrails; deterministic validation catches structural and traceability issues that LLMs miss or hallucinate
• Design-Code Disconnect — code diverges from design when there is no single source of truth and no automated traceability enforcement
• Fragmented Tool Setup — each AI agent (Windsurf, Cursor, Claude, Copilot) requires different file formats for skills, workflows, and rules; maintaining these manually is error-prone
• Inconsistent PR Reviews — code reviews vary in depth and focus without structured checklists and prompts
• Manual Configuration Overhead — project-specific conventions, artifact locations, and validation rules require manual setup and synchronization

What Cypilot Provides

Two layers of functionality:

• Core — deterministic skill engine, universal workflows (generate/analyze/plan), multi-agent integrations (Windsurf, Cursor, Claude, Copilot, OpenAI), global CLI (cypilot/cpt), config directory management, extensible kit system, ID/traceability infrastructure, execution plans for context-safe phased execution, and Cypilot DSL (CDSL) for behavioral specifications
• SDLC Kit — artifact-first development pipeline (PRD → DESIGN → ADR → DECOMPOSITION → FEATURE → CODE) with templates, checklists, examples, deterministic validation, cross-artifact consistency checks, and GitHub PR review/status workflows

Works with any language, stack, or repository.

---

Table of Contents

• • Cyber Pilot — Deterministic Agent Tool for Structured Workflows
  • Problem
  • What Cypilot Provides
  • Table of Contents
  • Prerequisites
  • Installation
    • Global CLI (recommended)
  • Project Setup
    • Update
  • Using Cypilot
    • Example Prompts
    • Agent Skill
    • Workflow Commands
    • Checklists and Quality Gates
  • Architecture
    • Directory Structure
    • Kit System
  • Extensibility
    • Kit: Cypilot SDLC
  • Contributing

---

Prerequisites

• Python 3.11+ — required for the CLI tool and skill engine (uses tomllib from stdlib)
• Git — for project detection and version control
• AI Agent — Windsurf, Cursor, Claude Code, GitHub Copilot, or OpenAI Codex
• gh CLI (optional) — required only for PR review/status workflows
• pipx (recommended) — for global CLI installation

---

Installation

Global CLI (recommended)

pipx install git+https://github.com/cyberfabric/cyber-pilot.git

To update to the latest version:

pipx upgrade cypilot

This installs cypilot and cpt commands globally. The CLI is a thin proxy shell — on first run it downloads the skill bundle into ~/.cypilot/cache/ and delegates all commands to the cached or project-local skill engine.

---

Project Setup

# Initialize Cypilot in your project
cpt init

# Generate agent entry points for your IDE
cpt generate-agents --agent windsurf

# Generate all agents for your IDE
cpt generate-agents

cpt init creates the Cypilot directory (default: cypilot/) with three subdirectories:

Directory	Purpose	Editable?
.core/	Read-only core files (skills, workflows, schemas, architecture, requirements) copied from cache	No
.gen/	Auto-generated aggregate files (SKILL.md, AGENTS.md, README.md)	No
config/	User-editable config (core.toml, artifacts.toml, AGENTS.md) and kit outputs	Yes

The command also:

• Defines a root system (name/slug derived from the project directory)
• Creates config/core.toml and config/artifacts.toml
• Installs all available kits (copies kit files to config/kits/{slug}/)
• Injects a managed <!-- @cpt:root-agents --> block into the root AGENTS.md

Supported agents: windsurf, cursor, claude, copilot, openai.

Update

cpt update

Updates .core/ from cache, regenerates .gen/ aggregates, and updates kit files in config/kits/ with interactive diff prompts for modified files.

---

Using Cypilot

Start requests with cypilot in your AI agent chat. This switches the agent into Cypilot mode: it loads config and rules, routes the request to the right workflow (plan vs generate vs analyze), and gates file writes behind explicit confirmation.

cypilot on            — enable Cypilot mode
cypilot off           — disable Cypilot mode
cypilot auto-config   — scan project and generate convention rules

A full walkthrough is available in guides/STORY.md.

Example Prompts

Setup & Configuration

Prompt	What the agent does
cypilot init	Initializes Cypilot — creates config directory, generates rules, injects root AGENTS.md
cypilot auto-config	Scans project structure and generates per-system convention rules
cypilot show config	Displays config structure, registered artifacts, and codebase mappings
cypilot generate-agents --agent windsurf	Regenerates agent entry points for a specific agent

Artifact Generation

Prompt	What the agent does
cypilot make PRD for user authentication system	Generates PRD with actors, requirements, flows following the template
cypilot make DESIGN from PRD.md	Transforms PRD into architecture design with full traceability
cypilot decompose auth feature into tasks	Creates DECOMPOSITION with ordered, dependency-mapped implementation units
cypilot make FEATURE for login flow	Produces feature design with acceptance criteria, CDSL flows, edge cases

Execution Plans (phased execution)

Prompt	What the agent does
cypilot plan generate PRD for task manager	Decomposes PRD generation into self-contained phase files (≤500 lines each)
cypilot plan analyze DESIGN	Creates phased analysis plan with focused checklist groups per phase
cypilot execute next phase	Reads next phase file, follows compiled instructions, reports against acceptance criteria
cypilot plan status	Reports plan progress: completed/pending/failed phases, next actionable phase

Validation & Quality

Prompt	What the agent does
cypilot validate PRD.md	Runs deterministic template validation + semantic quality scoring
cypilot validate all	Validates entire artifact hierarchy, checks cross-references, reports issues
cypilot validate code for auth module	Scans code for @cpt-* markers, verifies coverage against feature docs
cypilot review DESIGN.md with consistency-checklist	Multi-phase consistency analysis detecting contradictions

Traceability & Search

Prompt	What the agent does
cypilot find requirements related to authentication	Searches artifacts for IDs matching pattern, returns definitions and references
cypilot trace cpt-myapp-fr-auth	Traces requirement through DESIGN → FEATURE → code
cypilot list unimplemented features	Cross-references feature docs with code markers

Code Review & Pull Requests

Prompt	What the agent does
cypilot review PR #123	Fetches PR diff, analyzes against checklists, produces structured review report
cypilot PR status #123	Assesses unreplied comments by severity, audits resolved comments, reports CI status

Agent Skill

Cypilot provides a unified Agent Skill (cypilot) defined in skills/cypilot/SKILL.md. The skill is loaded into the agent's context when Cypilot mode is enabled and provides:

• Deterministic validation and traceability commands
• Protocol Guard for consistent context loading
• Workflow routing (plan vs generate vs analyze)
• ID lookup and cross-reference resolution
• Auto-configuration for brownfield projects

Workflow Commands

Cypilot has exactly three universal workflows:

Command	Workflow	Description
/cypilot-plan	plan.md	Plan: decompose large tasks into self-contained phase files for phased execution
/cypilot-generate	generate.md	Write: create, edit, fix, update, implement, refactor, configure
/cypilot-analyze	analyze.md	Read: validate, review, check, inspect, audit, compare

Routing priority: plan > generate > analyze. "Plan to generate PRD" routes to plan.md, not generate.md.

Plan Escalation: generate.md and analyze.md include a mandatory escalation gate — if the estimated context exceeds the safe budget (>2500 lines for generate, >2000 for analyze), the agent MUST offer to switch to /cypilot-plan for phased execution.

Kit-specific workflows (e.g., PR review, PR status) are provided by kits and exposed as agent entry points automatically.

Checklists and Quality Gates

Artifact checklists (from SDLC kit):

• PRD — 300+ criteria for requirements completeness
• DESIGN — 380+ criteria for architecture validation
• DECOMPOSITION — 130+ criteria for feature breakdown quality
• FEATURE — 380+ criteria for implementation readiness
• ADR — 270+ criteria for decision rationale

Generic checklists in requirements/:

• Code checklist — 200+ criteria for code quality
• Consistency checklist — 45+ criteria for cross-artifact consistency
• Reverse engineering — 270+ criteria for legacy code analysis
• Prompt engineering — 220+ criteria for AI prompt design

Architecture

Directory Structure

After cpt init, a project has:

project/
├── cypilot/                    # Cypilot install directory
│   ├── .core/                  # Read-only core (from cache)
│   │   ├── skills/             # Skill engine + scripts
│   │   ├── workflows/          # Core workflows (generate.md, analyze.md, plan.md)
│   │   ├── schemas/            # JSON schemas
│   │   ├── architecture/       # Core architecture docs (PRD, DESIGN, specs)
│   │   └── requirements/       # Core requirements + checklists
│   ├── .gen/                   # Auto-generated aggregates
│   │   ├── AGENTS.md           # Aggregated WHEN rules from kits
│   │   ├── SKILL.md            # Composed skill with kit extensions
│   │   └── README.md           # Aggregated kit documentation
│   └── config/                 # User-editable
│       ├── core.toml           # System definitions, kit registrations
│       ├── artifacts.toml      # Artifact registry, autodetect rules
│       ├── AGENTS.md           # User WHEN rules
│       ├── SKILL.md            # User skill extensions
│       └── kits/sdlc/          # Kit files (artifacts, workflows, constraints)
│           ├── artifacts/      # Templates, rules, checklists, examples
│           ├── workflows/      # Kit-specific workflows
│           ├── constraints.toml
│           ├── SKILL.md
│           └── AGENTS.md
├── AGENTS.md                   # Root entry (managed block → cypilot/.gen/)
├── .windsurf/                  # Agent entry points (generated)
├── .cursor/
├── .claude/
└── .github/prompts/

Kit System

Each kit is a direct file package containing ready-to-use resources:

Kit Content	Purpose
artifacts/{KIND}/template.md	Writing instructions for artifact kind
artifacts/{KIND}/rules.md	Validation rules
artifacts/{KIND}/checklist.md	Quality criteria
artifacts/{KIND}/examples/	Example artifacts
constraints.toml	Heading/ID constraints for validation
workflows/	Kit-specific workflows (e.g., PR review)
SKILL.md	Kit skill extensions
AGENTS.md	Agent system prompt content

Kits are installed to config/kits/{slug}/. Running cpt update updates kit files with interactive diff prompts for any user modifications.

---

Extensibility

Cypilot is extensible through Kits — self-contained packages that bundle templates, rules, checklists, examples, and workflows for a specific domain. The kit plugin system supports extension at three levels:

1. Kit-level — new kits for entirely new domains (e.g., API design, infrastructure-as-code)
2. Artifact-level — new artifact kinds within an existing kit
3. Resource-level — override templates, extend checklists, modify rules within an artifact kind

Kit: Cypilot SDLC

The built-in SDLC Kit provides an artifact-first development pipeline with end-to-end traceability:

PRD → ADR + DESIGN → DECOMPOSITION → FEATURE → CODE

Each artifact kind has templates, rules, checklists (300+ criteria), and examples. The kit also provides PR review and PR status workflows for GitHub.

See the SDLC Kit repository for the full pipeline overview, artifact kinds, and guides.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for the full guide covering:

• Development setup and self-hosted bootstrap architecture
• Versioning — where versions live and how to bump them
• DCO requirement — all commits must be signed off (git commit -s)
• CI pipeline — Makefile targets and GitHub Actions checks
• Pull request process — what must pass before merge

Quick start:

git clone https://github.com/cyberfabric/cyber-pilot.git
cd cyber-pilot
make install-proxy   # install cpt CLI from local source
make update          # sync .bootstrap/ from source
make test            # run tests
make validate        # validate artifacts