A spec-driven, audit-gated, self-improving development methodology for AI-assisted workflows.
Seven phases. Seven audit categories. Competitive intelligence. Browser automation. SAST. One direction: forward.

       

---

The Problem

AI coding tools are powerful but chaotic. Without structure, they produce code that works today and breaks tomorrow:

No specification — jumping straight to code without defining what or why

No audit gate — shipping whatever the AI generates without independent review

No learning — making the same mistakes because nothing is remembered

Tool lock-in — methodology tied to one AI tool, useless with another

The Solution

SPEAR is a drop-in methodology that adds structure, audit gates, and a learning ratchet to any AI-assisted workflow.

┌────────┐    ┌──────┐    ┌──────┐    ┌─────────┐    ┌───────┐    ┌─────────┐    ┌─────────────┐
│ IGNITE │───>│ SPEC │───>│ PLAN │───>│ EXECUTE │───>│ AUDIT │───>│ RATCHET │───>│ PRODUCTIZE  │
└────────┘    └──────┘    └──────┘    └─────────┘    └───────┘    └─────────┘    └─────────────┘

I	Ignite — Pre-spec intent clarification. Understand the real problem before defining the solution.
S	Spec — Socratic questioning to define what and why. Competitive research integration. Design validation before approval.
P	Plan — Break into phases with fitness functions, competitor analysis, and success criteria.
E	Execute — TDD-enforced (RED-GREEN-REFACTOR). Worktree isolation. 5-step verification gate. Subagent dispatch. Systematic debugging.
A	Audit — Independent review across 7 categories including browser visual verification. GO/NO-GO verdict.
R	Ratchet — Tighten thresholds, generate rules, remember decisions. Quality only goes up.
P	Productize — Post-ratchet productization. Packaging, distribution, and market readiness.

30-Second Install

curl -fsSL https://raw.githubusercontent.com/migueljnew-droid/spear-framework/main/install.sh | bash

Security note: We recommend cloning and inspecting the installer before running it.

Or manually:

git clone https://github.com/migueljnew-droid/spear-framework.git
cp -r spear-framework/.spear your-project/.spear
cd your-project && ./install.sh

The 7 Audit Categories

Every change is reviewed across seven independent, parallel categories. Each produces its own verdict.

Category	What It Checks
	Secrets, injection, auth, OWASP Top 10, SAST (CodeQL + Semgrep), variant analysis, supply chain audit
	CVEs, licenses, outdated packages, supply chain
	Complexity, bundle size, queries, memory
	Duplication, dead code, naming, error handling
	API docs, README accuracy, changelog
	Layer violations, circular deps, pattern consistency
	Browser verification via CDP — console errors, failed requests, accessibility tree, visual rendering

Severity levels: CRITICAL (blocks deploy) → HIGH (fix or justify) → MEDIUM → LOW → INFO

The Ratchet

The ratchet ensures quality only goes up. It tracks thresholds for metrics like test coverage, bundle size, and complexity:

• Floor thresholds (must stay above): test coverage ≥ 70%, doc coverage ≥ 60%
• Ceiling thresholds (must stay below): complexity ≤ 20, bundle ≤ 500kb
• Auto-tighten: When you exceed a threshold by 5%+, it ratchets to the new level (minus 2% buffer)
• Never loosens silently: Every threshold change is logged with justification

{
  "test_coverage": { "value": 70, "direction": "floor" },
  "max_complexity": { "value": 20, "direction": "ceiling" }
}

AI Tool Support

SPEAR is AI-agnostic at its core. Adapters translate the methodology into each tool's native format:

Tool	Adapter	What You Get
Claude Code	adapters/claude-code/	CLAUDE.md + slash commands + custom agents
Cursor	adapters/cursor/	.cursorrules with SPEAR directives
GitHub Copilot	adapters/copilot/	copilot-instructions.md
Antigravity	adapters/antigravity/	Project rules + agent workflows
Kiro	adapters/kiro/	Steering files + hooks + spec templates
Any LLM	adapters/generic/	Self-contained system prompt

Key Features

Phase State Machine	Sequential phases with 13 enforced rules. No skipping.
TDD Iron Law	No production code without a failing test first. RED-GREEN-REFACTOR per task. Code before test = delete and restart.
5-Step Verification Gate	Identify → Run → Read → Verify → Claim. No "should work" or "probably passes." Evidence before claims.
Socratic Spec Phase	One question at a time. Multiple choice preferred. Design validation. Hard gate before implementation.
Systematic Debugging	4-phase protocol: Root Cause → Pattern Analysis → Hypothesis → Fix. 3 failed fixes = escalate (architectural issue).
Subagent Execution	Fresh agent per task. Two-stage review (spec compliance → code quality). Model routing by complexity.
Worktree Isolation	Every execution phase starts in a clean git worktree. Verified baseline before any changes.
7-Category Audit	Parallel, independent audits with severity classification — includes browser visual verification
Browser CDP MCP	31-tool browser automation via Chrome DevTools Protocol. Accessibility tree, annotated screenshots, network interception, console capture.
Learning Ratchet	Auto-tightening thresholds. Quality only goes up.
Fitness Functions	Automated metric checks against ratchet thresholds
Project Memory	Decisions, patterns, and findings persist across cycles
Pre-commit Hooks	Secrets scan, lint, tests, dependency audit — zero-dep bash
Deep Dependency Analysis	Full audit table per spec: version pins, license compatibility, CVE scan, transitive deps, maintenance risk.
Compliance Gate	Mandatory evaluation: App Store guidelines, GDPR/CCPA/COPPA, OWASP Top 10, license compatibility. PASS/N/A/NEEDS REVIEW per category.
Arsenal Discovery	Dynamic scan of ALL skills, agents, MCPs. Relevance scoring. Best tools auto-assigned to phases — never hardcoded subsets.
Ignite Phase	Pre-spec intent clarification. Understand the real problem before defining any solution.
Productize Phase	Post-ratchet packaging, distribution prep, and go-to-market readiness.
Competitor Research	Built-in competitor landscape scanning before spec. Know the field before you build.
AI-Agnostic Core	One framework, six tool adapters, works with anything

Comparison

	SPEAR	BMAD	GSD	Bare Prompting
Structured spec phase	✅	✅	❌	❌
Execution engine	✅	❌	✅	❌
Independent audit gate	✅	❌	❌	❌
Learning ratchet	✅	❌	❌	❌
Fitness functions	✅	❌	✅	❌
Project memory	✅	❌	❌	❌
Multi-tool support	6 tools	Claude only	Claude only	Tool-specific
Browser visual audit	✅	❌	❌	❌
Pre-commit hooks	✅	❌	❌	❌
No package manager	✅	✅	❌	✅

Quick Start Example

# 1. Install SPEAR in your project
cd my-project
curl -fsSL https://raw.githubusercontent.com/migueljnew-droid/spear-framework/main/install.sh | sh

# 2. Start a cycle — write a spec
cp .spear/templates/spec/prd.md docs/specs/auth-feature.md

# 3. Plan the implementation
cp .spear/templates/plan/phase-plan.md docs/plans/auth-phase-1.md

# 4. Execute with SPEAR discipline
# Atomic commits, checkpoints at 25/50/75%, deviation logging
git commit -m "feat(auth): add JWT token generation"

# 5. Audit passes automatically via pre-commit hooks

# 6. Ratchet tightens automatically
cat .spear/ratchet/ratchet.json

Project Structure

.spear/                    <- The distribution unit (copy this to any project)
├── SPEAR.md               <- Framework brain (v2.0 — 13 state machine rules)
├── config.json            <- Project configuration
├── templates/             <- Output templates for each phase
│   ├── spec/              <- PRD, architecture, epic shard
│   ├── plan/              <- Phase plan, fitness function, research brief
│   ├── execute/           <- Task commit, deviation log, checkpoint, TDD cycle
│   ├── audit/             <- Audit report, summary, finding
│   └── ratchet/           <- Ratchet entry, rule proposal, retrospective
├── agents/                <- 15 AI agent role definitions
│   ├── spec-writer.md     <- Socratic questioning + design validation
│   ├── executor.md        <- TDD-enforced + verification gate + worktree
│   ├── subagent-executor  <- Parallel task dispatch + two-stage review
│   ├── debugger.md        <- 4-phase systematic debugging protocol
│   ├── planner.md         <- Phase planning + fitness functions
│   ├── verifier.md        <- Phase + project verification
│   ├── ratchet-engine.md  <- Threshold management + retrospectives
│   ├── competitor-researcher.md <- Competitor landscape + gap identification
│   └── audit-*.md         <- 7 independent audit category agents
├── ratchet/               <- Threshold state + history + rules
├── output/                <- Phase output artifacts
├── memory/                <- Project knowledge base
└── fitness/               <- Automated fitness functions

packages/                  <- Built-in tooling
│   └── browser-cdp-mcp/   <- 31-tool browser automation MCP (Chrome DevTools Protocol)

adapters/                  <- AI tool integrations
hooks/                     <- Git hooks + checker scripts
docs/                      <- Full documentation
install.sh                 <- One-command installer

Documentation

• Philosophy — Design principles behind SPEAR
• Quick Start — Get running in 5 minutes
• Phase Guides: Spec · Plan · Execute · Audit · Ratchet
• Adapter Guides: Claude Code · Cursor · Copilot · Antigravity · Kiro · Generic
• Upgrades: Fitness Functions · Memory Backends · Custom Audits · Monorepo · CI/CD · Teams · Metrics

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

The most impactful contributions:

• Audit rules from real-world findings
• Fitness functions for different ecosystems
• Adapter improvements for your favorite AI tool
• Language-specific hook improvements

License

MIT — use it everywhere. See LICENSE.

---

Created by Miguel Jiminez  ·  Spec-driven. Audit-gated. Self-improving.