{"id":45627242,"url":"https://github.com/hendryavila/hoofy","last_synced_at":"2026-03-01T22:05:17.723Z","repository":{"id":339614975,"uuid":"1162612963","full_name":"HendryAvila/Hoofy","owner":"HendryAvila","description":"Hoofy — AI development companion MCP server. Persistent memory, spec-driven development, adaptive change pipeline, Clarity Gate. 32 tools, single Go binary, zero deps.","archived":false,"fork":false,"pushed_at":"2026-02-26T23:33:46.000Z","size":2234,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T03:24:31.620Z","etag":null,"topics":["ai","ai-assistant","ai-coding","ai-development","ai-tools","code-quality","developer-tools","go","golang","hoofy","knowledge-graph","mcp","mcp-server","model-context-protocol","persistent-memory","requirements-engineering","spec-driven-development","sqlite"],"latest_commit_sha":null,"homepage":"https://hendrycode.xyz/blog/2026/2/25/hoofy-tu-companion-de-desarrollo-con-ia-que-no-te-deja-cortar-camino/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HendryAvila.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T13:35:10.000Z","updated_at":"2026-02-26T23:33:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/HendryAvila/Hoofy","commit_stats":null,"previous_names":["hendryavila/sdd-hoffy","hendryavila/hoofy"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/HendryAvila/Hoofy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HendryAvila%2FHoofy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HendryAvila%2FHoofy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HendryAvila%2FHoofy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HendryAvila%2FHoofy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HendryAvila","download_url":"https://codeload.github.com/HendryAvila/Hoofy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HendryAvila%2FHoofy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29986242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T21:06:37.093Z","status":"ssl_error","status_checked_at":"2026-03-01T21:05:45.052Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-assistant","ai-coding","ai-development","ai-tools","code-quality","developer-tools","go","golang","hoofy","knowledge-graph","mcp","mcp-server","model-context-protocol","persistent-memory","requirements-engineering","spec-driven-development","sqlite"],"created_at":"2026-02-23T21:20:02.376Z","updated_at":"2026-03-01T22:05:17.714Z","avatar_url":"https://github.com/HendryAvila.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"Hoofy — AI development companion MCP server with persistent memory and spec-driven development\" width=\"280\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eHoofy\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe AI coding assistant that remembers everything and never hallucinates specs.\u003c/strong\u003e\u003cbr\u003e\n  An MCP server that gives your AI persistent memory, structured specifications,\u003cbr\u003e\n  and adaptive change management — so it builds what you actually want.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/HendryAvila/Hoofy/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/HendryAvila/Hoofy/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://go.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-purple\" alt=\"MCP\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/HendryAvila/Hoofy/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/HendryAvila/Hoofy?include_prereleases\" alt=\"Release\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hendrycode.xyz/blog/2026/2/25/hoofy-tu-companion-de-desarrollo-con-ia-que-no-te-deja-cortar-camino/\"\u003eBlog Post\u003c/a\u003e ·\n  \u003ca href=\"docs/workflow-guide.md\"\u003eWorkflow Guide\u003c/a\u003e ·\n  \u003ca href=\"docs/tool-reference.md\"\u003eTool Reference\u003c/a\u003e ·\n  \u003ca href=\"docs/research-foundations.md\"\u003eResearch Foundations\u003c/a\u003e ·\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hendryavila.github.io/Hoofy/\"\u003e\u003cstrong\u003e🐴 Explore the Interactive Documentation →\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What Is Hoofy? — AI Development Companion for MCP\n\nHoofy is an AI coding tool that solves the three biggest problems with AI-assisted development: **memory loss between sessions**, **hallucinated implementations**, and **unstructured AI workflows**. It's a single [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server written in Go — one binary, zero dependencies — that works with Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode, and any MCP-compatible AI tool.\n\nHoofy is four systems in one MCP server:\n\n| System | What it does | Tools |\n|---|---|---|\n| **Memory** | Persistent context across sessions using SQLite + FTS5 full-text search. Decisions, bugs, patterns, discoveries — your AI remembers what happened yesterday. | 19 `mem_*` tools |\n| **Change Pipeline** | Adaptive workflow for ongoing dev. Picks the right stages based on change type × size (12 flow variants). Includes mandatory **context-check** and **artifact guard** stages. | 5 `sdd_change*` + `sdd_adr` |\n| **Project Pipeline** | Full greenfield specification — from vague idea to validated architecture with a Clarity Gate and **business rules extraction** that blocks hallucinations. | 11 `sdd_*` tools |\n| **Bootstrap** | Reverse-engineer existing codebases into SDD artifacts. Scans project structure, configs, conventions, schemas, and tests — then generates requirements, business rules, and design docs. | `sdd_reverse_engineer` + `sdd_bootstrap` |\n\nOne binary. Zero external dependencies. SQLite embedded at compile time. Works with **any** MCP-compatible AI coding assistant — Claude Code, Cursor, VS Code Copilot, Gemini CLI, OpenCode. **38 tools + 6 on-demand prompts.**\n\n### Why Hoofy?\n\nAI coding assistants are powerful but forgetful and overconfident. Studies show experienced developers are [19% slower with unstructured AI](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) (METR 2025), and AI adoption without structure causes [7.2% delivery instability](https://dora.dev/research/2025/dora-report/) (DORA 2025). Hoofy fixes this by making your AI assistant remember context, follow specifications, and prove it understood before writing code.\n\n### Key Features\n\n**Hot/Cold Instruction Architecture** — Server instructions are kept minimal (~160 lines of \"constitution\") to reduce token overhead. Detailed guidance for specific workflows is loaded on-demand via 6 MCP prompts (`/sdd-start`, `/sdd-status`, `/sdd-stage-guide`, `/sdd-memory-guide`, `/sdd-change-guide`, `/sdd-bootstrap-guide`). The AI requests the right prompt when it needs it — like loading a manual chapter instead of carrying the entire book. Inspired by research showing that compact constitutions with on-demand retrieval reduce token consumption by ~17%.\n\n**Spec-Aware Code Review** — `sdd_review` runs a code review against your project's specifications, not just generic best practices. It parses requirements (FR-XXX), business rules (BRC-XXX constraints), design decisions, and ADRs from memory to generate a review checklist. Works standalone — no active pipeline needed. Give it a task description and it tells you what to verify.\n\n**Ad-Hoc Context Suggestion** — `sdd_suggest_context` bridges the gap for sessions that don't use a formal pipeline. Give it a task description and it scans your specs, completed changes, memory observations, and project conventions to recommend what context to read before starting. Works without `sdd.json` or an active change.\n\n**Existing Project Bootstrap** — Got an existing codebase with no specs? `sdd_reverse_engineer` scans your project (directory structure, package manifests, configs, entry points, conventions, schemas, API definitions, ADRs, tests) and produces a structured report. Then `sdd_bootstrap` writes the missing SDD artifacts — requirements, business rules, and design docs — so the change pipeline works intelligently from day one. Medium/large changes are **blocked** without artifacts; small changes get a warning.\n\n**Knowledge Graph** — Memory observations aren't flat notes. You can connect them with typed, directional relations (`depends_on`, `caused_by`, `implements`, `supersedes`, `relates_to`, `part_of`) to build a navigable web of project knowledge. Use `mem_build_context` to traverse the graph from any observation and pull in related decisions, bugs, and patterns automatically.\n\n```\nDecision: \"Switched to JWT\"  →(caused_by)→  Discovery: \"Session storage doesn't scale\"\n    ↑(implements)                               ↑(relates_to)\nBugfix: \"Fixed token expiry\"              Pattern: \"Retry with backoff\"\n```\n\n**Context Check** — Every change pipeline flow now starts with a mandatory context-check stage. Before writing a single spec or line of code, Hoofy scans your existing specs, completed changes, memory observations, and convention files (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, etc.) to detect conflicts and ambiguities. Zero issues = green light. Issues found = must resolve before proceeding. Even a one-line fix can break an existing business rule.\n\n**Business Rules** — In the greenfield project pipeline, a dedicated business-rules stage extracts declarative rules from your requirements using BRG taxonomy (Definitions, Facts, Constraints, Derivations) and DDD Ubiquitous Language — before the Clarity Gate evaluates them. Rules inform the gate, not the other way around.\n\n**Pre-pipeline Exploration** — Before committing to a pipeline, use `sdd_explore` to capture unstructured thinking — goals, constraints, tech preferences, unknowns, decisions. It saves structured context to memory via topic key upsert (call it multiple times as your thinking evolves — it updates, never duplicates). It also suggests a change type and size based on keywords, so you start the right pipeline.\n\n**Wave Assignments** — When creating tasks (in either pipeline), the AI can group them into parallel execution waves derived from the dependency graph. Wave 1 has no dependencies, Wave 2 depends only on Wave 1, and so on. This tells you exactly which tasks can run in parallel and which must wait — useful for team coordination or just knowing the critical path.\n\n### How it flows\n\n```mermaid\nflowchart TB\n    explore[\"sdd_explore\\n(goals, constraints, unknowns)\"]\n\n    subgraph project [\"New Project (greenfield)\"]\n        direction LR\n        P1[Init] --\u003e P2[Propose] --\u003e P3[Requirements] --\u003e P3b[\"Business\\nRules\"]\n        P3b --\u003e P4{Clarity Gate}\n        P4 --\u003e|Ambiguous| P3\n        P4 --\u003e|Clear| P5[Design] --\u003e P6[Tasks] --\u003e P7[Validate]\n    end\n\n    subgraph bootstrap [\"Existing Project (no specs)\"]\n        direction LR\n        B1[\"sdd_reverse_engineer\\n(scan codebase)\"] --\u003e B2[\"AI analyzes\\nreport\"] --\u003e B3[\"sdd_bootstrap\\n(write artifacts)\"]\n    end\n\n    subgraph change [\"Existing Project (changes)\"]\n        direction LR\n        C1[\"sdd_change\\n(type × size)\"] --\u003e C1b[\"Context\\nCheck\"]\n        C1b --\u003e C2[\"Opening Stage\\n(describe/propose/scope)\"]\n        C2 --\u003e C3[\"Spec + Design\\n(if needed)\"]\n        C3 --\u003e C4[Tasks] --\u003e C5[Verify]\n    end\n\n    subgraph memory [\"Memory (always active)\"]\n        direction LR\n        M1[Session Start] --\u003e M2[\"Work + Save Discoveries\"]\n        M2 --\u003e M3[\"Connect with Relations\"]\n        M3 --\u003e M4[Session Summary]\n    end\n\n    explore -.-\u003e|\"captures context before\"| project\n    explore -.-\u003e|\"captures context before\"| change\n    bootstrap -.-\u003e|\"enables\"| change\n\n    style explore fill:#8b5cf6,stroke:#7c3aed,color:#fff\n    style P4 fill:#f59e0b,stroke:#d97706,color:#000\n    style P3b fill:#e879f9,stroke:#c026d3,color:#000\n    style C1b fill:#e879f9,stroke:#c026d3,color:#000\n    style B1 fill:#06b6d4,stroke:#0891b2,color:#fff\n    style B3 fill:#06b6d4,stroke:#0891b2,color:#fff\n    style P7 fill:#10b981,stroke:#059669,color:#fff\n    style C5 fill:#10b981,stroke:#059669,color:#fff\n```\n\n\u003e **[Full workflow guide with step-by-step examples](docs/workflow-guide.md)** · **[Complete tool reference (38 tools)](docs/tool-reference.md)**\n\n---\n\n## Quick Start\n\n### 1. Install the binary\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003emacOS\u003c/strong\u003e (Homebrew)\u003c/summary\u003e\n\n```bash\nbrew install HendryAvila/hoofy/hoofy\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003emacOS / Linux\u003c/strong\u003e (script)\u003c/summary\u003e\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.sh | bash\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindows\u003c/strong\u003e (PowerShell)\u003c/summary\u003e\n\n```powershell\nirm https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.ps1 | iex\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGo / Source\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Go install (requires Go 1.25+)\ngo install github.com/HendryAvila/Hoofy/cmd/hoofy@latest\n\n# Or build from source\ngit clone https://github.com/HendryAvila/Hoofy.git\ncd Hoofy\nmake build\n```\n\u003c/details\u003e\n\n### 2. Connect to your AI tool\n\n\u003e **MCP Server vs Plugin — what's the difference?**\n\u003e\n \u003e The **MCP server** is Hoofy itself — the binary you just installed. It provides 38 tools and 6 on-demand prompts (memory, change pipeline, project pipeline, bootstrap, standalone) and works with **any** MCP-compatible AI tool.\n\u003e\n\u003e The **Plugin** is a Claude Code-only enhancement that layers additional capabilities on top of the MCP server:\n\u003e\n\u003e | Component | What it does |\n\u003e |---|---|\n\u003e | **Agent** | A custom personality (Hoofy the horse-architect) that teaches through concepts, not code dumps. Enforces SDD discipline — the AI won't skip specs. |\n\u003e | **Skills** | Loadable instruction sets for specific domains (React 19, Next.js 15, TypeScript, Tailwind 4, Django DRF, Playwright, etc.). The agent auto-detects context and loads the right skill before writing code. |\n\u003e | **Hooks** | Lifecycle automation — `PreToolCall` and `PostToolCall` hooks that trigger memory operations automatically (e.g., saving session context, capturing discoveries after tool use). |\n\u003e\n\u003e The plugin is optional — you get full Hoofy functionality with just the MCP server. The plugin just makes the experience smoother in Claude Code.\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/summary\u003e\n\n**MCP Server** — one command, done:\n\n```bash\nclaude mcp add --scope user hoofy hoofy serve\n```\n\n**Plugin** (optional, Claude Code only) — adds agent + skills + hooks on top of the MCP server:\n\n```\n/plugin marketplace add HendryAvila/hoofy-plugins\n/plugin install hoofy@hoofy-plugins\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCursor\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"hoofy\": {\n      \"command\": \"hoofy\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVS Code Copilot\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"hoofy\": {\n      \"type\": \"stdio\",\n      \"command\": \"hoofy\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenCode\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to `~/.config/opencode/opencode.json` inside the `\"mcp\"` key:\n\n```json\n{\n  \"mcp\": {\n    \"hoofy\": {\n      \"type\": \"local\",\n      \"command\": [\"hoofy\", \"serve\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGemini CLI\u003c/strong\u003e\u003c/summary\u003e\n\nAdd to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"hoofy\": {\n      \"command\": \"hoofy\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n### 3. Use it\n\nJust talk to your AI. Hoofy's built-in instructions tell the AI when and how to use each system.\n\n### 4. Update\n\n```bash\nhoofy update\n```\n\nAuto-checks on startup, updates when you say so.\n\n### 5. Reinforce the behavior (recommended)\n\nHoofy already includes built-in server instructions, but adding a short block to your agent's instructions file reinforces the habit — the AI will think about specs *before* it even sees the tools.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e — \u003ccode\u003eCLAUDE.md\u003c/code\u003e (only needed for MCP-only setup)\u003c/summary\u003e\n\n\u003e **Using the plugin?** Skip this — the plugin's hooks and agent already enforce SDD behavior automatically.\n\n```markdown\n## Hoofy — Spec-Driven Development\n\nBefore coding any new feature or significant change, use Hoofy to create specs first.\n- New projects: use the SDD pipeline (sdd_init_project → sdd_validate)\n- Existing projects without specs: use sdd_reverse_engineer → sdd_bootstrap to generate artifacts\n- Ongoing work: use the change pipeline (sdd_change) — it adapts stages to the size of the change\n- Ad-hoc sessions: use sdd_suggest_context to find relevant specs/memory before starting\n- Code review: use sdd_review to verify implementation against specs, business rules, and ADRs\n- Memory: save decisions, bugs, and discoveries with mem_save so future sessions have context\nDo NOT start coding without specs for any non-trivial change.\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCursor\u003c/strong\u003e — \u003ccode\u003e.cursor/rules/hoofy.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n## Hoofy — Spec-Driven Development\n\nBefore coding any new feature or significant change, use Hoofy to create specs first.\n- New projects: use the SDD pipeline (sdd_init_project → sdd_validate)\n- Existing projects without specs: use sdd_reverse_engineer → sdd_bootstrap to generate artifacts\n- Ongoing work: use the change pipeline (sdd_change) — it adapts stages to the size of the change\n- Ad-hoc sessions: use sdd_suggest_context to find relevant specs/memory before starting\n- Code review: use sdd_review to verify implementation against specs, business rules, and ADRs\n- Memory: save decisions, bugs, and discoveries with mem_save so future sessions have context\nDo NOT start coding without specs for any non-trivial change.\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenCode\u003c/strong\u003e — \u003ccode\u003eAGENTS.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n## Hoofy — Spec-Driven Development\n\nBefore coding any new feature or significant change, use Hoofy to create specs first.\n- New projects: use the SDD pipeline (sdd_init_project → sdd_validate)\n- Existing projects without specs: use sdd_reverse_engineer → sdd_bootstrap to generate artifacts\n- Ongoing work: use the change pipeline (sdd_change) — it adapts stages to the size of the change\n- Ad-hoc sessions: use sdd_suggest_context to find relevant specs/memory before starting\n- Code review: use sdd_review to verify implementation against specs, business rules, and ADRs\n- Memory: save decisions, bugs, and discoveries with mem_save so future sessions have context\nDo NOT start coding without specs for any non-trivial change.\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVS Code Copilot\u003c/strong\u003e — \u003ccode\u003e.github/copilot-instructions.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n## Hoofy — Spec-Driven Development\n\nBefore coding any new feature or significant change, use Hoofy to create specs first.\n- New projects: use the SDD pipeline (sdd_init_project → sdd_validate)\n- Existing projects without specs: use sdd_reverse_engineer → sdd_bootstrap to generate artifacts\n- Ongoing work: use the change pipeline (sdd_change) — it adapts stages to the size of the change\n- Ad-hoc sessions: use sdd_suggest_context to find relevant specs/memory before starting\n- Code review: use sdd_review to verify implementation against specs, business rules, and ADRs\n- Memory: save decisions, bugs, and discoveries with mem_save so future sessions have context\nDo NOT start coding without specs for any non-trivial change.\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGemini CLI\u003c/strong\u003e — \u003ccode\u003eGEMINI.md\u003c/code\u003e\u003c/summary\u003e\n\n```markdown\n## Hoofy — Spec-Driven Development\n\nBefore coding any new feature or significant change, use Hoofy to create specs first.\n- New projects: use the SDD pipeline (sdd_init_project → sdd_validate)\n- Existing projects without specs: use sdd_reverse_engineer → sdd_bootstrap to generate artifacts\n- Ongoing work: use the change pipeline (sdd_change) — it adapts stages to the size of the change\n- Ad-hoc sessions: use sdd_suggest_context to find relevant specs/memory before starting\n- Code review: use sdd_review to verify implementation against specs, business rules, and ADRs\n- Memory: save decisions, bugs, and discoveries with mem_save so future sessions have context\nDo NOT start coding without specs for any non-trivial change.\n```\n\u003c/details\u003e\n\n---\n\n## Best Practices\n\n### 1. Specs before code — always\n\nThe AI will try to jump straight to coding. Don't let it. For any non-trivial work:\n- **New project?** → `sdd_init_project` and walk through the full pipeline\n- **New feature?** → `sdd_change(type: \"feature\", size: \"medium\")` at minimum\n- **Bug fix?** → Even `sdd_change(type: \"fix\", size: \"small\")` gives you context-check → describe → tasks → verify\n\nThe cheapest stages (context-check + describe + tasks + verify) take under 2 minutes and save hours of debugging hallucinated code.\n\n### 2. Explore before you plan\n\nBefore jumping into a pipeline, use `sdd_explore` to capture context from your discussion — goals, constraints, tech preferences, unknowns, decisions. It saves structured context to memory so the pipeline starts with clarity, not guesswork. Call it multiple times as your thinking evolves — it upserts, never duplicates.\n\n### 3. Bootstrap existing projects\n\nWorking on a project that never went through SDD? Don't skip specs — bootstrap them. Run `sdd_reverse_engineer` to scan the codebase, then `sdd_bootstrap` to generate the missing artifacts. This takes under a minute and means the change pipeline works with full context instead of flying blind. Medium/large changes are blocked without specs — and that's intentional.\n\n### 4. Right-size your changes\n\nDon't use a large pipeline for a one-line fix. Don't use a small pipeline for a new authentication system.\n\n| If the change... | It's probably... |\n|---|---|\n| Touches 1-2 files, clear fix | **small** (4 stages — context-check + describe + tasks + verify) |\n| Needs requirements or design thought | **medium** (5 stages) |\n| Affects architecture, multiple systems | **large** (6-7 stages) |\n\n### 5. Let memory work for you\n\nYou don't need to tell the AI to use memory — Hoofy's built-in instructions handle it. But you'll get better results if you:\n- **Start sessions by greeting the AI** — it triggers `mem_context` to load recent history\n- **Mention past decisions** — \"remember when we chose SQLite?\" triggers `mem_search`\n- **Confirm session summaries** — the AI writes them at session end, review them for accuracy\n\n### 6. Connect knowledge with relations\n\nHoofy's knowledge graph lets you connect related observations with typed, directional edges — turning flat memories into a navigable web. The AI creates relations automatically when it recognizes connections. You can also ask it to relate observations manually. Use `mem_build_context` to explore the full graph around any observation.\n\n### 7. Use topic keys for evolving knowledge\n\nWhen a decision might change (database schema, API design, architecture), use `topic_key` in `mem_save`. This **updates** the existing observation instead of creating duplicates. One observation per topic, always current.\n\n### 8. One change at a time\n\nHoofy enforces one active change at a time. This isn't a limitation — it's a feature. Scope creep happens when you try to do three things at once. Finish one change, verify it, then start the next.\n\n### 9. Trust the Clarity Gate\n\nWhen the Clarity Gate asks questions, don't rush past them. Every question it asks represents an ambiguity that would have become a bug, a hallucination, or a \"that's not what I meant\" moment. Two minutes answering questions saves two hours debugging wrong implementations.\n\n### 10. Hoofy is the architect, Plan mode is the contractor\n\nIf your AI tool has a plan/implementation mode, use it **after** Hoofy specs are done. Hoofy answers WHO and WHAT. Plan mode answers HOW.\n\n```\nHoofy (Requirements Layer)  →  \"WHAT are we building? For WHO?\"\nPlan Mode (Implementation)  →  \"HOW do we build it? Which files?\"\n```\n\n---\n\n## The Research Behind SDD\n\nHoofy's specification pipeline isn't built on opinions. It's built on research. Every feature maps to a specific recommendation from Anthropic Engineering or industry research — see the **[full research foundations document](docs/research-foundations.md)** for the complete mapping.\n\n**Anthropic Engineering:**\n- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) — ACI design, tool patterns, orchestrator-worker architecture\n- [Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Persistent memory, progressive disclosure, context as finite resource\n- [Writing Effective Tools](https://www.anthropic.com/engineering/writing-tools-for-agents) — Tool namespacing, response design, token efficiency\n- [Multi-Agent Research System](https://www.anthropic.com/engineering/multi-agent-research-system) — Session summaries, filesystem output, token budget awareness\n- [Long-Running Agent Harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Progress tracking, incremental delivery, JSON over Markdown for state\n- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) — CLAUDE.md scanning, structured workflows\n\n**Industry Research:**\n- **METR 2025**: Experienced developers were [19% slower with AI](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) despite feeling 20% faster — unstructured AI usage introduces debugging overhead and false confidence.\n- **DORA 2025**: [7.2% delivery instability increase](https://dora.dev/research/2025/dora-report/) for every 25% AI adoption — without foundational systems and practices.\n- **McKinsey 2025**: Top performers see [16-30% productivity gains](https://www.mckinsey.com/capabilities/mckinsey-digital/our-insights/superagency-in-the-workplace-empowering-people-to-unlock-ais-full-potential-at-work) only with structured specification and communication.\n- **IEEE 720574**: Fixing a requirement error in production costs [10-100x more](https://ieeexplore.ieee.org/document/720574) than fixing it during requirements — worse with AI-generated code.\n- **Codified Context (Lulla 2026)**: [AGENTS.md infrastructure](https://arxiv.org/abs/2602.20478v1) associated with 29% less runtime and 17% less token consumption. Compact constitutions (~660 lines) with on-demand retrieval outperform monolithic instructions. Hoofy's hot/cold instruction architecture implements this pattern.\n- **IREB \u0026 IEEE 29148**: Structured elicitation, traceability, ambiguity detection — Hoofy's Clarity Gate implements these frameworks.\n- **Business Rules Group**: The [Business Rules Manifesto](https://www.businessrulesgroup.org/brmanifesto.htm) — rules as first-class citizens. Hoofy uses BRG taxonomy.\n- **EARS**: [Research-backed sentence templates](https://alistairmavin.com/ears/) that eliminate requirements ambiguity.\n- **DDD Ubiquitous Language**: [Shared language](https://martinfowler.com/bliki/UbiquitousLanguage.html) eliminates translation errors — Hoofy's business-rules glossary.\n\n**Structure beats speed.**\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/HendryAvila/Hoofy.git\ncd Hoofy\nmake build        # Build binary\nmake test         # Tests with race detector\nmake lint         # golangci-lint\n./bin/hoofy serve # Run the MCP server\n```\n\n### Areas for contribution\n\n- More clarity dimensions (mobile, API, data pipeline)\n- More change types beyond fix/feature/refactor/enhancement\n- Template improvements and customization\n- Streamable HTTP transport for remote deployment\n- Export to Jira, Linear, GitHub Issues\n- i18n for non-English specs\n\n---\n\n## Acknowledgments\n\nHoofy's memory system is inspired by [Engram](https://github.com/Gentleman-Programming/engram) by [Gentleman Programming](https://github.com/Gentleman-Programming) — the original persistent memory MCP server that proved AI assistants need long-term context to be truly useful. Engram laid the foundation; Hoofy built on top of it.\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStop prompting. Start specifying.\u003c/strong\u003e\u003cbr\u003e\n  Built with care by the Hoofy community.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhendryavila%2Fhoofy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhendryavila%2Fhoofy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhendryavila%2Fhoofy/lists"}