Stop AI coding agents from over-engineering, losing architectural context, or breaking working features in endless fix loops.

Why SPIDER? • How It Works • Quickstart • The 8 Agent Roles • Architecture & Docs

Single-prompt coding agents and vibe-coding tools excel at version one—and routinely collapse on iteration fifteen:

1. Silent Over-Engineering: Ask for a small feature and the agent invents three new wrapper classes, a service layer, and an unrequested dependency.
2. Context Amnesia: Architectural decisions live in transient chat history. Two sessions later, a new agent session violates invariants from last week.
3. Self-Grading Homework: The same agent that wrote the code declares "All done!" after skipping edge cases or weakening tests.
4. Destructive Fix Loops: When a bug appears, the agent patches symptoms blindly, introducing regressions in previously working modules.

SPIDER turns your repository into a governed engineering organization. Work is split across 8 specialized role contracts, coordinated through shared, append-only Markdown/YAML state files, and gated by an independent validator that audits git diffs, upstream architecture contracts, and full-suite regression tests before any task can be marked Done.

SPIDER combines 6 engineering phases (S.P.I.D.E.R.), 8 specialist roles ("8 legs") so no single agent grades its own homework, and 1 web-structured repository memory (docs/terminology.md):

• The Hub (project.md & requirements.md): Center of the web where agents Sense current project state before acting.
• Radials (features/<slug>/tasks/tN-*.md): Task spokes branching from the Hub, with Spirals (## LOG) tracking each iteration.
• The Dragline (decisions.md + Git history): The safety silk thread trailed behind every change so the team can Retreat or Repair cleanly without destructive fix loops.

First-generation Spec-Driven Development (SDD) tools proved that written specs beat unstructured "vibe coding," but introduced new failure modes in real-world brownfield repositories: heavy ceremony on small fixes, blindly trusting AI-generated architectural bloat, and letting execution loops grade their own homework.

SPIDER is a Generation-2 SDD protocol built to solve those exact trade-offs:

flowchart TB
    User(["👤 User Request"]) --> Preflight["🎯 Orchestrator Preflight<br/>Clarify intent & confirm Minimum-Change Baseline"]
    Preflight --> Req["📋 Record Ready REQ-N in requirements.md<br/>Coarse Triage"]
    Req -- "Localized tested change<br/>inside 1 existing component" --> FastPlan["📐 Planner (Fast Path)"]
    Req -- "All other changes" --> Arch["🏛️ Architect<br/>Impact Sweep + Plan Freshness + UI Need"]
    Arch -- "ui_design_needed: true" --> UI["🎨 UI Designer<br/>features/<slug>/design.html"]
    UI --> ArchReady["🏛️ Architect<br/>Design Readiness Reconciliation"]
    Arch -- "ui_design_needed: false" --> Plan["📐 Planner<br/>KISS Design + Fewest Cohesive Tasks + Typed STEPS"]
    ArchReady --> Plan
    FastPlan --> Exec["⚙️ Task Executor<br/>Exact task_id: Pending → Active → Ready for validation"]
    Plan -- "KISS peer challenge<br/>(if boundary over-engineered)" --> Arch
    Plan --> Exec
    Exec --> Val{"🛡️ Task Validator<br/>REQ + STEPS + Diff + Regression Gate"}
    Val -- "PASS" --> Done(["✅ Task Done → User Checkpoint"])
    Val -- "FAIL: mechanical step" --> Exec
    Val -- "FAIL: defect / regression" --> Debug["🔍 Debugger<br/>Root-Cause Isolation & Authorized Fix"]
    Val -- "FAIL: task/plan gap" --> Plan
    Val -- "FAIL: boundary gap" --> Arch
    Debug --> Exec

SPIDER requires Python 3.10+ (standard library only, zero external packages) for its installer and SHA-256 bundle verifier.

git clone https://github.com/Algoza-Solutions/spider-protocol.git
cd spider-protocol

Install into Codex (~/.codex/skills), Claude Code (~/.claude/agents), OpenCode (~/.config/opencode/skills), Gemini / Antigravity (~/.gemini/config/skills), or all at once:

# Install into all supported environments (Codex, OpenCode, Gemini/Antigravity, Claude Code)
python scripts/install.py --target all

# Or install into a specific environment:
python scripts/install.py --target codex
python scripts/install.py --target claude
python scripts/install.py --target opencode
python scripts/install.py --target gemini

Bootstrap the lightweight Markdown/YAML state stores (project.md, requirements.md, decisions.md, task-index.yaml, architecture/, features/) in any existing or new repository:

python scripts/install.py --init-project /path/to/your/project

Open your project in your coding agent and invoke spider-orchestrator (or @orchestrator in Claude Code) with your feature request or bug report:

"Use spider-orchestrator: Add rate limiting to the /api/login endpoint using our existing Redis client."

The orchestrator will:

1. Inspect your codebase read-only and propose the minimum direct baseline (disclosing if any new file or structure is needed).
2. Wait for your confirmation before recording REQ-1 in requirements.md.
3. Route through the fast path (or Architect → Planner for cross-cutting changes), execute the exact task, and run task-validator to verify the diff and test suite.

SPIDER keeps all project memory in human-readable files committed alongside your code—never trapped in proprietary cloud state or ephemeral chat logs:

your-project/
├── project.md                              # Hub: project overview, current state, and active/completed task table
├── requirements.md                         # Orchestrator-owned REQ/AC registry and validation evidence trail
├── decisions.md                            # Append-only architectural decision log (D1, D2, ...)
├── task-index.yaml                         # Machine-readable task state, REQ trace, and monotonic high-water mark
├── architecture/
│   ├── architecture.md                     # Living system architecture reference
│   └── flows.md                            # Key runtime and protocol flows
└── features/
    └── <feature-slug>/
        ├── requirements.md                 # Detailed requirement contract + confirmed minimum baseline
        ├── blast-radius-summary.md         # Architect impact sweep & triage metadata
        ├── build-plan.md                   # Component boundary & integration plan (when architecture changes)
        ├── design.html                     # UI/UX specification (when ui_design_needed is true)
        ├── tasks/
        │   └── t1-<slug>.md                # Planner-authored task contract with GOAL, typed STEPS, NOW, and LOG
        ├── validation/
        │   └── t1-validation.json          # Structured validator audit report
        └── defects/
            └── bug-req-N-<slug>.md         # Debugger root-cause diagnosis report

spider-orchestrator includes a zero-dependency cryptographic verifier that checks manifest version, role directory structure, frontmatter, and line-ending-normalized SHA-256 digests across all 7 specialist skills:

# Verify the repository skill bundle
python skills/spider-orchestrator/scripts/verify_specialist_skills.py --codex-home .

# Run the 22-test behavioral regression suite
python -m unittest discover -s skills/spider-orchestrator/scripts -v

• Protocol Architecture (docs/architecture.md) — System layers, role boundaries, and core invariants.
• Routing & Repair Flows (docs/flows.md) — Fast path vs. deep triage, closed repair loops, taskless defect intake, and Done revalidation audits.
• Evolving Spider Terminology (docs/terminology.md) — Mental model mapping protocol concepts (Hub, Radials, Dragline, Sense → Spin → Wrap → Anchor).
• Contributing Guide (CONTRIBUTING.md) — How to update role contracts and regenerate manifest hashes.

SPIDER was created and battle-tested by Algoza Solutions to run disciplined, regression-checked AI software engineering across production codebases.

Have an AI-built or vibe-coded app (Lovable, Bolt, Replit, Cursor, v0) that keeps breaking as you add features, or want managed SPIDER engineering for your project? Drop us an email at [email protected] — we harden fragile codebases, fix security gaps, and manage ongoing development with SPIDER's regression-gated workflow so new changes never break existing features.

Released under the MIT License. Copyright © 2026 Algoza Solutions (OPC) Private Limited.