{"slug": "show-hn-spider-protocol-the-safety-tether-for-vibe-coding", "title": "Show HN: Spider Protocol – The safety tether for vibe coding", "summary": "Algoza Solutions released Spider Protocol, an open-source framework that splits AI coding-agent work 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 a task can be marked Done. The protocol organizes work into 6 phases (Specify, Plan, Implement, Document, Evaluate, Review) with roles including spider-orchestrator, architect, planner, task-executor, task-validator and debugger, and targets failures the project attributes to single-prompt coding agents: silent over-engineering, context amnesia, self-grading and destructive fix loops.", "body_md": "*Stop AI coding agents from over-engineering, losing architectural context, or breaking working features in endless fix loops.*\n\n[Why SPIDER?](#why-spider) • [How It Works](#how-it-works) • [Quickstart](#quickstart) • [The 8 Agent Roles](#the-8-agent-roles) • [Architecture & Docs](https://github.com/Algoza-Solutions/spider-protocol/blob/main/docs/architecture.md)\n\nSingle-prompt coding agents and vibe-coding tools excel at version one—and routinely collapse on iteration fifteen:\n\n1. **Silent Over-Engineering:** Ask for a small feature and the agent invents three new wrapper classes, a service layer, and an unrequested dependency.\n2. **Context Amnesia:** Architectural decisions live in transient chat history. Two sessions later, a new agent session violates invariants from last week.\n3. **Self-Grading Homework:** The same agent that wrote the code declares*\"All done!\"* after skipping edge cases or weakening tests.\n4. **Destructive Fix Loops:** When a bug appears, the agent patches symptoms blindly, introducing regressions in previously working modules.\n\n**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`.\n\nSPIDER 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`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/docs/terminology.md)):\n\n| Letter | Phase | Role Owner(s) | Repository Artifact(s) | \n|---|---|---|---|\n| **S** | **Specify** | [`spider-orchestrator`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/spider-orchestrator/SKILL.md) ,[`architect`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/architect/SKILL.md) ,[`ui-designer`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/ui-designer/SKILL.md) | Preflight minimum-change baseline, `requirements.md` (`REQ-N` ),`blast-radius-summary.md` ,`build-plan.md` ,`design.html` | \n| **P** | **Plan** | [`planner`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/planner/SKILL.md) | Peer KISS challenge, `task-index.yaml` , and`features/<slug>/tasks/tN-*.md` with typed resumable`STEPS` | \n| **I** | **Implement** | [`task-executor`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/task-executor/SKILL.md) | Code changes strictly inside authorized `STEPS` (`Pending → Active → Ready for validation` ) | \n| **D** | **Document** | All writers + [`doc-cleanup`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/doc-cleanup/SKILL.md) | Newest-first append-only `decisions.md` , living`architecture.md` , task`## LOG` /`## DEBUG LOG` , and tombstoned compaction | \n| **E** | **Evaluate** | [`task-validator`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/task-validator/SKILL.md) ,[`debugger`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/debugger/SKILL.md) | `validation/tN-validation.json` (contract chain + diff + regression suite gate) and`defects/bug-req-N-*.md` | \n| **R** | **Review** | [`spider-orchestrator`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/spider-orchestrator/SKILL.md) +**Human** | Closed repair-loop routing, **Decision Checkpoints** , and**Iteration Checkpoints** before`REQ` closure | \n\n- **The Hub (`project.md` & `requirements.md`):** Center of the web where agents**Sense** current project state before acting.\n- **Radials (`features/<slug>/tasks/tN-*.md`):** Task spokes branching from the Hub, with**Spirals** (`## LOG` ) tracking each iteration.\n- **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.\n\nFirst-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**.\n\n**SPIDER is a Generation-2 SDD protocol** built to solve those exact trade-offs:\n\n| Capability | Gen-1 Spec / Prompt Packs | 🕷️ SPIDER Protocol (Gen-2 SDD) | \n|---|---|---|\n| **Scope & Bloat Control** | Agents freely invent helpers, layers, and abstractions | **Minimum-Change Baseline:** Preflight establishes the smallest direct change; any new file, class, or dependency requires explicit user approval | \n| **Architecture vs. KISS** | Planner blindly implements whatever Architect writes | **Peer KISS Challenge:** Planner is a peer Tech Lead that halts planning and challenges over-engineered Architect boundaries | \n| **Execution Discipline** | Free-form task checklists | **Typed Resumable `STEPS`:** Exact`[create]` ,`[modify]` ,`[delete]` ,`[reference]` (read-only), and`[run]` contracts; only**one** task can be`Active` at a time | \n| **Quality Gate** | Executor marks its own task complete | **Independent `task-validator`:** Executor can only mark` Ready for validation` . Validator audits the full contract chain, git diff, and regression suite before marking`Done` | \n| **Bug Handling** | Ad-hoc patching mid-task | **Dedicated `debugger` Role:** Hypothesis-driven root-cause isolation with durable defect records (`features/<slug>/defects/` ) | \n| **Contract Integrity** | Unverified markdown prompts | **SHA-256 Manifest Verification:**`verify_specialist_skills.py` cryptographically verifies all specialist contracts before role handoffs | \n\n| Tool | Sweet Spot | Trade-off | How SPIDER Differs | \n|---|---|---|---|\n| **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 | \n| **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 | \n| **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 | \n| **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** | \n\n``` php\nflowchart TB\n    User([\"👤 User Request\"]) --> Preflight[\"🎯 Orchestrator Preflight<br/>Clarify intent & confirm Minimum-Change Baseline\"]\n    Preflight --> Req[\"📋 Record Ready REQ-N in requirements.md<br/>Coarse Triage\"]\n    Req -- \"Localized tested change<br/>inside 1 existing component\" --> FastPlan[\"📐 Planner (Fast Path)\"]\n    Req -- \"All other changes\" --> Arch[\"🏛️ Architect<br/>Impact Sweep + Plan Freshness + UI Need\"]\n    Arch -- \"ui_design_needed: true\" --> UI[\"🎨 UI Designer<br/>features/<slug>/design.html\"]\n    UI --> ArchReady[\"🏛️ Architect<br/>Design Readiness Reconciliation\"]\n    Arch -- \"ui_design_needed: false\" --> Plan[\"📐 Planner<br/>KISS Design + Fewest Cohesive Tasks + Typed STEPS\"]\n    ArchReady --> Plan\n    FastPlan --> Exec[\"⚙️ Task Executor<br/>Exact task_id: Pending → Active → Ready for validation\"]\n    Plan -- \"KISS peer challenge<br/>(if boundary over-engineered)\" --> Arch\n    Plan --> Exec\n    Exec --> Val{\"🛡️ Task Validator<br/>REQ + STEPS + Diff + Regression Gate\"}\n    Val -- \"PASS\" --> Done([\"✅ Task Done → User Checkpoint\"])\n    Val -- \"FAIL: mechanical step\" --> Exec\n    Val -- \"FAIL: defect / regression\" --> Debug[\"🔍 Debugger<br/>Root-Cause Isolation & Authorized Fix\"]\n    Val -- \"FAIL: task/plan gap\" --> Plan\n    Val -- \"FAIL: boundary gap\" --> Arch\n    Debug --> Exec\n```\n\nSPIDER requires **Python 3.10+** (standard library only, zero external packages) for its installer and SHA-256 bundle verifier.\n\n```\ngit clone https://github.com/Algoza-Solutions/spider-protocol.git\ncd spider-protocol\n```\n\nInstall into **Codex** (`~/.codex/skills`), **Claude Code** (`~/.claude/agents`), **OpenCode** (`~/.config/opencode/skills`), **Gemini / Antigravity** (`~/.gemini/config/skills`), or all at once:\n\n```\n# Install into all supported environments (Codex, OpenCode, Gemini/Antigravity, Claude Code)\npython scripts/install.py --target all\n\n# Or install into a specific environment:\npython scripts/install.py --target codex\npython scripts/install.py --target claude\npython scripts/install.py --target opencode\npython scripts/install.py --target gemini\n```\n\nBootstrap the lightweight Markdown/YAML state stores (`project.md`, `requirements.md`, `decisions.md`, `task-index.yaml`, `architecture/`, `features/`) in any existing or new repository:\n\n```\npython scripts/install.py --init-project /path/to/your/project\n```\n\nOpen your project in your coding agent and invoke **`spider-orchestrator`** (or `@orchestrator` in Claude Code) with your feature request or bug report:\n\n*\"Use spider-orchestrator: Add rate limiting to the `/api/login` endpoint using our existing Redis client.\"*\n\nThe orchestrator will:\n\n1. Inspect your codebase read-only and propose the **minimum direct baseline** (disclosing if any new file or structure is needed).\n2. Wait for your confirmation before recording `REQ-1` in`requirements.md` .\n3. 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.\n\n| Role ( `skills/` &`agents/` ) | Responsibility | \n|---|---|\n| **[`spider-orchestrator`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/spider-orchestrator/SKILL.md)** (`orchestrator.md` ) | Owns conversational preflight discovery, minimum-baseline confirmation, `REQ-N` lifecycle, coarse triage, exact task pointer routing, repair loops, and user checkpoints. | \n| **[`architect`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/architect/SKILL.md)** (`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` . | \n| **[`ui-designer`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/ui-designer/SKILL.md)** (`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. | \n| **[`planner`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/planner/SKILL.md)** (`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` . | \n| **[`task-executor`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/task-executor/SKILL.md)** (`task-executor.md` ) | Implements one exact dispatched task inside its authorized shape ( `Pending → Active → Ready for validation` ). Never marks its own work`Done` . | \n| **[`task-validator`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/task-validator/SKILL.md)** (`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` . | \n| **[`debugger`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/debugger/SKILL.md)** (`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. | \n| **[`doc-cleanup`](https://github.com/Algoza-Solutions/spider-protocol/blob/main/skills/doc-cleanup/SKILL.md)** (`doc-cleanup.md` ) | Compacts completed task files and stale artifacts while preserving `REQ` acceptance evidence, monotonic`task-index.yaml` tombstones, and immutable decisions. | \n\nSPIDER keeps all project memory in human-readable files committed alongside your code—never trapped in proprietary cloud state or ephemeral chat logs:\n\n```\nyour-project/\n├── project.md                              # Hub: project overview, current state, and active/completed task table\n├── requirements.md                         # Orchestrator-owned REQ/AC registry and validation evidence trail\n├── decisions.md                            # Append-only architectural decision log (D1, D2, ...)\n├── task-index.yaml                         # Machine-readable task state, REQ trace, and monotonic high-water mark\n├── architecture/\n│   ├── architecture.md                     # Living system architecture reference\n│   └── flows.md                            # Key runtime and protocol flows\n└── features/\n    └── <feature-slug>/\n        ├── requirements.md                 # Detailed requirement contract + confirmed minimum baseline\n        ├── blast-radius-summary.md         # Architect impact sweep & triage metadata\n        ├── build-plan.md                   # Component boundary & integration plan (when architecture changes)\n        ├── design.html                     # UI/UX specification (when ui_design_needed is true)\n        ├── tasks/\n        │   └── t1-<slug>.md                # Planner-authored task contract with GOAL, typed STEPS, NOW, and LOG\n        ├── validation/\n        │   └── t1-validation.json          # Structured validator audit report\n        └── defects/\n            └── bug-req-N-<slug>.md         # Debugger root-cause diagnosis report\n```\n\n`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:\n\n```\n# Verify the repository skill bundle\npython skills/spider-orchestrator/scripts/verify_specialist_skills.py --codex-home .\n\n# Run the 22-test behavioral regression suite\npython -m unittest discover -s skills/spider-orchestrator/scripts -v\n```\n\n- [**Protocol Architecture (`docs/architecture.md`)**](https://github.com/Algoza-Solutions/spider-protocol/blob/main/docs/architecture.md) — System layers, role boundaries, and core invariants.\n- [**Routing & Repair Flows (`docs/flows.md`)**](https://github.com/Algoza-Solutions/spider-protocol/blob/main/docs/flows.md) — Fast path vs. deep triage, closed repair loops, taskless defect intake, and Done revalidation audits.\n- [**Evolving Spider Terminology (`docs/terminology.md`)**](https://github.com/Algoza-Solutions/spider-protocol/blob/main/docs/terminology.md) — Mental model mapping protocol concepts (`Hub` ,`Radials` ,`Dragline` ,`Sense → Spin → Wrap → Anchor` ).\n- [**Contributing Guide (`CONTRIBUTING.md`)**](https://github.com/Algoza-Solutions/spider-protocol/blob/main/CONTRIBUTING.md) — How to update role contracts and regenerate manifest hashes.\n\nSPIDER was created and battle-tested by [**Algoza Solutions**](https://algozasolutions.com/) to run disciplined, regression-checked AI software engineering across production codebases.\n\n**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?**\nDrop us an email at [**info@algozasolutions.com**](mailto: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.\n\nReleased under the [MIT License](https://github.com/Algoza-Solutions/spider-protocol/blob/main/LICENSE). Copyright © 2026 [Algoza Solutions (OPC) Private Limited](https://algozasolutions.com/).", "url": "https://wpnews.pro/news/show-hn-spider-protocol-the-safety-tether-for-vibe-coding", "canonical_source": "https://github.com/Algoza-Solutions/spider-protocol", "published_at": "2026-10-27 11:18:16+00:00", "updated_at": "2026-10-27 11:41:40.440374+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["Algoza Solutions", "Spider Protocol", "spider-orchestrator", "task-validator", "task-executor", "architect", "planner", "debugger"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-spider-protocol-the-safety-tether-for-vibe-coding", "markdown": "https://wpnews.pro/news/show-hn-spider-protocol-the-safety-tether-for-vibe-coding.md", "text": "https://wpnews.pro/news/show-hn-spider-protocol-the-safety-tether-for-vibe-coding.txt", "jsonld": "https://wpnews.pro/news/show-hn-spider-protocol-the-safety-tether-for-vibe-coding.jsonld"}}