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:

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):

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:

Tool Sweet Spot Trade-off How SPIDER Differs

BMAD-METHOD Agile persona simulation (PM, Architect, SM, Dev, QA/TEA) + Quick Flow SM/Dev agents rarely challenge Architect bloat; full-track PRD/story ceremony is heavy Preflight Minimum-Change Baseline + Planner ↔ Architect Peer KISS Challenge block unapproved abstractions; SHA-256 verified skill bundle

GitHub Spec Kit Slash-command pipeline (/speckit.specify → plan → tasks → analyze) Single-agent command sequence; /speckit.analyze checks pre-code markdown consistency 8 separated role contracts, dedicated debugger role (defects/), and a post-code task-validator auditing git diffs against typed STEPS + live test suites

Superpowers (obra) Composable TDD, debugging, and subagent code-review skills Spawns fresh subagents per task; tracks state per plan rather than a permanent repo-wide ledger In-thread role transitions (preserving prompt cache prefixes) + permanent cross-feature REQ → Decision → Task → Validation ledger + Peer KISS Challenge

OpenSpec / GSD Brownfield delta specs (/opsx:verify) & fast execution loops Lighter on role-separated governance and upstream anti-bloat challenges Combines a low-ceremony Fast Path with two-tier anti-bloat governance (Minimum-Change Baseline + KISS Challenge) and hard task-validator Done gating

How It Works

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

Loading

Quickstart

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

2. Install skills / agents into your coding environment

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

3. Initialize SPIDER in your project repository

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

4. Start building with the Orchestrator

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."

Role (skills/ & agents/) Responsibility

spider-orchestrator (orchestrator.md) Owns conversational preflight discovery, minimum-baseline confirmation, REQ-N lifecycle, coarse triage, exact task pointer routing, repair loops, and user checkpoints.

architect (architect.md) Evaluates architectural impact, plan freshness, and UI-design need independently; owns durable boundary decisions (decisions.md), build-plan.md, and blast-radius-summary.md.

ui-designer (ui-designer.md) Produces self-contained, accessible UX/UI specifications (features/<slug>/design.html) covering user flows, screen states, and interaction contracts before task planning.

planner (planner.md) Peer Tech Lead under KISS: challenges unnecessary upstream complexity, creates the fewest cohesive tasks, and writes typed resumable STEPS in features/<slug>/tasks/tN-*.md.

task-executor (task-executor.md) Implements one exact dispatched task inside its authorized shape (Pending → Active → Ready for validation). Never marks its own work Done.

task-validator (task-validator.md) Audits the full upstream contract chain, git diff, and project regression test suite; writes features/<slug>/validation/tN-validation.json; alone marks delivery tasks Done.

debugger (debugger.md) Investigates post-validation failures or user-reported bugs via hypothesis testing; writes durable defect reports (features/<slug>/defects/) and applies only localized authorized fixes.

doc-cleanup (doc-cleanup.md) Compacts completed task files and stale artifacts while preserving REQ acceptance evidence, monotonic task-index.yaml tombstones, and immutable decisions.

Repository State Stores (In Your Project)

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

Verifying Bundle Integrity

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

Documentation

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.

Built in Production by Algoza Solutions

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 info@algozasolutions.com — 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.