The universal blueprint and skill standard for AI coding agents — teaching agents how to think, audit, architect, and properly document any software project.
"The agent must adapt to the project. The project must not be forced to adapt to the skill."
Install Agent Blueprint into any project with your preferred method:
curl -fsSL https://raw.githubusercontent.com/botdigit-official/agent-blueprint/main/install.sh | bashnpx @botdigit/agent-blueprint init # Initialize standards & skills in current repo
npx @botdigit/agent-blueprint plan # Generate a wave-based plan in TASK.md
npx @botdigit/agent-blueprint verify # Run automated test suites & doc sync check
npx @botdigit/agent-blueprint doctor # Check repository compliance scoregit clone --depth 1 https://github.com/botdigit-official/agent-blueprint.git ~/.agent-blueprint
~/.agent-blueprint/install.sh .| AI Tool | Configuration File Generated | Workflow Activated |
|---|---|---|
| Google Antigravity | AGENTS.md + .agents/skills/ |
Full modular skill hierarchy & subagent waves |
| Claude Code | CLAUDE.md |
Context & architecture guardrails |
| Cursor AI | .cursorrules |
Architectural & testing rules |
| Windsurf / Cline / Aider | AGENTS.md |
Autonomous discovery & audit |
| Command | Phase / Skill | Purpose |
|---|---|---|
/blueprint:discuss |
Phase 1 (13-phase-loop) |
Resolve ambiguities & lock architecture decisions |
/blueprint:plan |
Phase 2 (12-context-eng) |
Decompose feature into atomic task waves in TASK.md |
/blueprint:execute |
Phase 3 (12-context-eng) |
Execute active wave within bounded subagent context |
/blueprint:verify |
Phase 4 (08-testing) |
Execute automated test suite & verify 0 regressions |
/blueprint:ship |
Phase 5 (13-phase-loop) |
Conventional atomic commit, sync docs/, update CHANGELOG.md |
/blueprint:forensics |
Diagnostic (14-forensics) |
Minimal reproducer & root-cause verification |
/blueprint:doctor |
Compliance (10-audit) |
Project conformance audit & score |
Most AI coding agents jump straight to generating code or rewriting working systems without understanding the domain, architecture, dependencies, or conventions.
Agent Blueprint is a composable, technology-agnostic skill and documentation standard. It provides structured guidance so any AI agent can:
- Discover the project layout and entry points across the repo
- Understand its stack, framework, database, and maturity
- Audit what exists before modifying or breaking anything
- Document findings into living, structured architectural documentation
- Architect changes grounded in real business needs, not guesswork
- Plan features with Architectural Decision Records (ADRs)
- Implement following existing patterns and conventions
- Test & Verify to preserve regression safety and data integrity
- Review & Audit against security and performance baselines
🤖 Direct LLM Ingestion: Feed
llms.txtto web crawlers/agents or copy the 1-click system prompt inPROMPT.md.
| Scenario | Raw AI / Default Copilot | With Agent Blueprint |
|---|---|---|
| Entering a project | Guesses architecture, invents new dependencies | Runs discovery, detects existing stack, checks docs/ |
| Refactoring code | Often rewrites working systems and breaks logic | Obeys established ADRs, respects existing state machines |
| Documentation | Leaves zero comments and zero docs | Automatically updates docs/ living documentation |
| New Features | Injects unverified patterns | Writes automated tests, updates API specs |
| Multi-Agent Teams | Claude Code, Cursor, and Antigravity fight | All agents share a single source of truth |
These rules live at the top of every skill and guide every agent decision:
- Understand before changing.
- Inspect before assuming.
- Document before redesigning.
- Prefer simple architecture.
- Use the project's existing technology when practical.
- Do not introduce technology without a measurable reason.
- Business logic comes before code structure.
- Security and data integrity come before features.
- Deterministic tools before AI.
- AI only where reasoning adds value.
- APIs only where they provide unique value.
- Never rewrite working systems unnecessarily.
- Preserve existing functionality unless explicitly deprecated.
- Every architectural decision needs a reason (ADR).
- Every major change needs automated tests.
- Every project needs a source of truth.
- Every agent must leave the project better documented than it found it.
Agent Blueprint is not a single unwieldy prompt. It is a directory of modular, composable skills. The autonomous orchestrator selects only what applies to the current project:
skills/
├── 00-orchestrator/ # Triage, detect, activate
├── 01-discovery/ # Find project roots in monorepos or nested dirs
├── 02-project-context/ # Stack, framework, database, infrastructure
├── 03-business-architecture/ # Domain, actors, business rules, workflows
├── 04-architecture/ # Architectural review, ADRs, gaps
├── 05-documentation/ # Living documentation standard
├── 06-codebase-audit/ # Code-level inspection and hygiene
├── 07-security/ # Security review, secrets, CSRF, auth audit
├── 08-testing/ # Test strategy, coverage, regression suite
├── 09-performance/ # Latency, queries, throughput, bottlenecks
├── 10-audit/ # Combined holistic audit workflow
├── 11-controlled-source-of-truth/ # 19-Document enterprise specification standard
├── 12-context-engineering/ # Context rot prevention & subagent wave execution
├── 13-phase-loop-delivery/ # 5-Phase GSD delivery loop (Discuss-Plan-Execute-Verify-Ship)
└── 14-forensics-and-debugging/# Root-cause analysis, state capture & regression shields
Stack & framework adapters activate automatically based on detected project manifests (Cargo.toml, package.json, pyproject.toml, go.mod, pom.xml, etc.):
stacks/ frameworks/
├── rust/ ├── axum/
├── typescript/ ├── nextjs/
├── python/ ├── react/
├── go/ ├── fastapi/
├── php/ ├── django/
├── java/ ├── laravel/
├── ruby/ ├── spring/
└── dotnet/ └── rails/
Not every project needs 50 documents. Agent Blueprint selects the minimum documentation set appropriate to the project's size and risk:
| Project Scope | Required Documentation Baseline |
|---|---|
| Script / CLI Tool | README.md only |
| Web App / API | Project Brief, Architecture, Database, API Spec, Security |
| SaaS / Marketplace | + Business Architecture, Testing, Deployment, Runbook |
| Regulated / Enterprise | + Compliance, Audit Trail, Data Governance, Disaster Recovery |
agent-blueprint/
├── README.md # Project overview & quickstart
├── AGENTS.md # Primary instruction manual for coding agents
├── CONTRIBUTING.md # Guidelines for community skill additions
├── LICENSE # MIT License
├── install.sh # 1-click project linker & installer
│
├── skills/ # Core, technology-independent skills
│ ├── 00-orchestrator/
│ ├── 01-discovery/
│ ├── 02-project-context/
│ ├── 03-business-architecture/
│ ├── 04-architecture/
│ ├── 05-documentation/
│ ├── 06-codebase-audit/
│ ├── 07-security/
│ ├── 08-testing/
│ ├── 09-performance/
│ └── 10-audit/
│
├── stacks/ # Technology adapters (Rust, TS, Python, Go, etc.)
├── frameworks/ # Framework adapters (Next.js, Axum, FastAPI, etc.)
│
├── templates/ # Production-grade documentation templates
│ ├── project-brief/ # Initial scoping & objectives
│ ├── business-requirements/ # Domain entities & actor rules
│ ├── architecture/ # System design & component diagrams
│ ├── adr/ # Architecture Decision Records
│ ├── api-spec/ # REST / GraphQL API contracts
│ ├── database/ # Schema, migrations & relationships
│ ├── security/ # Threat models & access controls
│ ├── testing/ # Quality gates & verification plans
│ ├── deployment/ # CI/CD pipelines & hosting
│ ├── runbook/ # Incident response & operational SOPs
│ └── changelog/ # Semantic version releases
│
└── examples/ # Real-world audits & walkthroughs
├── botdigit-site/ # Multi-tenant directory & site builder
├── saas/ # Multi-tier subscription platform
├── marketplace/ # Two-sided buyer/seller marketplace
├── fintech/ # High-security payment processing
├── ecommerce/ # Catalog, cart, and order fulfillment
├── directory/ # Geo-spatial search & discovery
├── mobile-app/ # Cross-platform iOS/Android app
├── ai-product/ # LLM agents & deterministic pipelines
└── internal-tool/ # Backoffice admin control panels
Read AGENTS.md first. It specifies the step-by-step discovery, inspection, and execution lifecycle.
- Browse
skills/to understand the reasoning frameworks. - Check
templates/for ready-to-use architecture and documentation templates. - Review
examples/botdigit-site/to see a real forensic audit and remediation.
We welcome contributions! You can add new technology stacks, framework adapters, or domain patterns:
- Review
CONTRIBUTING.md. - Follow the metadata schema in
skills/00-orchestrator/SKILL.md. - Submit a Pull Request.
Agent Blueprint enforces a strict rule: "The agent must adapt to the project; the project must not adapt to the skill." Before an agent is allowed to write or edit code, it must execute Discovery, inspect existing frameworks, review active state machines, and check existing unit tests.
Yes. When you run ./install.sh or npx agent-blueprint init, it automatically creates .cursorrules (for Cursor), CLAUDE.md (for Claude Code), and AGENTS.md + .agents/skills/ (for Antigravity, Cline, Windsurf). All agents follow the exact same architectural guidelines.
Instead of outdated wikis or empty READMEs, Agent Blueprint establishes a structured docs/ hierarchy (Business Model, Architecture Decision Records, Database Schemas, API Specs, Security). Every time an agent modifies system behavior, it is required to update the corresponding document.
A single giant prompt gets truncated and forgotten in long context windows. Agent Blueprint is a modular, composable skill hierarchy. The autonomous orchestrator activates only the skills required for the specific task at hand.