Hoofy

Decision: "Switched to JWT"  →(caused_by)→  Discovery: "Session storage doesn't scale"
    ↑(implements)                               ↑(relates_to)
Bugfix: "Fixed token expiry"              Pattern: "Retry with backoff"

flowchart TB
    explore["sdd_explore\n(goals, constraints, unknowns)"]

    subgraph project ["New Project (greenfield)"]
        direction LR
        P1[Init] --> P1b[Principles] --> P2[Charter] --> P3[Requirements] --> P3b["Business\nRules"]
        P3b --> P4{Clarity Gate}
        P4 -->|Ambiguous| P3
        P4 -->|Clear| P5[Design] --> P6[Tasks] --> P7[Validate]
    end

    subgraph bootstrap ["Existing Project (no specs)"]
        direction LR
        B1["sdd_reverse_engineer\n(scan codebase)"] --> B2["AI analyzes\nreport"] --> B3["sdd_bootstrap\n(write artifacts)"]
    end

    subgraph change ["Existing Project (changes)"]
        direction LR
        C1["sdd_change\n(type × size)"] --> C1b["Context\nCheck"]
        C1b --> C2["Opening Stage\n(describe/charter/scope)"]
        C2 --> C3["Spec + Design\n(if needed)"]
        C3 --> C4[Tasks] --> C5[Verify]
    end

    subgraph memory ["Memory (always active)"]
        direction LR
        M1["mem_session(action=start)"] --> M2["Work + mem_save"]
        M2 --> M3["Connect with Relations"]
        M3 --> M4["mem_session(action=end, summary)"]
    end

    explore -.->|"captures context before"| project
    explore -.->|"captures context before"| change
    bootstrap -.->|"enables"| change

    style explore fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style P4 fill:#f59e0b,stroke:#d97706,color:#000
    style P1b fill:#e879f9,stroke:#c026d3,color:#000
    style P3b fill:#e879f9,stroke:#c026d3,color:#000
    style C1b fill:#e879f9,stroke:#c026d3,color:#000
    style B1 fill:#06b6d4,stroke:#0891b2,color:#fff
    style B3 fill:#06b6d4,stroke:#0891b2,color:#fff
    style P7 fill:#10b981,stroke:#059669,color:#fff
    style C5 fill:#10b981,stroke:#059669,color:#fff

---

## Best Practices

### 1. Specs before code — always

The AI will try to jump straight to coding. Don't let it. For any non-trivial work:
- **New project?** → `sdd_init_project` and walk through the full 9-stage pipeline
- **New feature?** → `sdd_change(type: "feature", size: "medium")` at minimum
- **Bug fix?** → Even `sdd_change(type: "fix", size: "small")` gives you context-check → describe → tasks → verify

The cheapest stages (context-check + describe + tasks + verify) take under 2 minutes and save hours of debugging hallucinated code.

### 2. Explore before you plan

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

### 3. Bootstrap existing projects

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

### 4. Right-size your changes

Don't use a large pipeline for a one-line fix. Don't use a small pipeline for a new authentication system.

| If the change... | It's probably... |
|---|---|
| Touches 1-2 files, clear fix | **small** (4 stages — context-check + describe + tasks + verify) |
| Needs requirements or design thought | **medium** (5 stages) |
| Affects architecture, multiple systems | **large** (6-7 stages) |

### 5. Let memory work for you

You 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:
- **Start sessions by greeting the AI** — it triggers `mem_context` to load recent history
- **Mention past decisions** — "remember when we chose SQLite?" triggers `mem_search`
- **Confirm session summaries** — the AI writes them at session end, review them for accuracy

### 6. Connect knowledge with relations

Hoofy'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_get(id=..., depth=...)` to explore the full graph around any observation.

### 7. Use topic keys for evolving knowledge

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

### 8. One change at a time

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

### 9. Trust the Clarity Gate

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

### 10. Hoofy is the architect, Plan mode is the contractor

If your AI tool has a plan/implementation mode, use it **after** Hoofy specs are done. Hoofy answers WHO and WHAT. Plan mode answers HOW.

---

## The Research Behind SDD

Hoofy'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](https://github.com/HendryAvila/Hoofy/blob/HEAD/docs/research-foundations.md)** for the complete mapping.

**Anthropic Engineering:**
- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) — ACI design, tool patterns, orchestrator-worker architecture
- [Effective Context Engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Persistent memory, progressive disclosure, context as finite resource
- [Writing Effective Tools](https://www.anthropic.com/engineering/writing-tools-for-agents) — Tool namespacing, response design, token efficiency
- [Multi-Agent Research System](https://www.anthropic.com/engineering/multi-agent-research-system) — Session summaries, filesystem output, token budget awareness
- [Long-Running Agent Harnesses](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Progress tracking, incremental delivery, JSON over Markdown for state
- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) — CLAUDE.md scanning, structured workflows

**Industry Research:**
- **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.
- **DORA 2025**: [7.2% delivery instability increase](https://dora.dev/research/2025/dora-report/) for every 25% AI adoption — without foundational systems and practices.
- **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.
- **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.
- **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.
- **IREB & IEEE 29148**: Structured elicitation, traceability, ambiguity detection — Hoofy's Clarity Gate implements these frameworks.
- **Business Rules Group**: The [Business Rules Manifesto](https://www.businessrulesgroup.org/brmanifesto.htm) — rules as first-class citizens. Hoofy uses BRG taxonomy.
- **EARS**: [Research-backed sentence templates](https://alistairmavin.com/ears/) that eliminate requirements ambiguity.
- **DDD Ubiquitous Language**: [Shared language](https://martinfowler.com/bliki/UbiquitousLanguage.html) eliminates translation errors — Hoofy's business-rules glossary.
- **Harness Engineering (OpenAI 2026)**: [Structured wrapping of AI](https://cdn.openai.com/papers/harness-engineering-designing-effective-ai-development-tools.pdf) improves output quality by constraining context, enforcing workflows, and making state explicit. Hoofy v1.0's identity redesign was directly inspired by this paper's philosophy of "user brings content, AI complements/organizes/validates."

**Structure beats speed.**

---

## Contributing

```bash
git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build        # Build binary
make test         # Tests with race detector
make lint         # golangci-lint
./bin/hoofy serve # Run the MCP server

brew install HendryAvila/hoofy/hoofy

curl -sSL https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.sh | bash

irm https://raw.githubusercontent.com/HendryAvila/Hoofy/main/install.ps1 | iex

# Go install (requires Go 1.25+)
go install github.com/HendryAvila/Hoofy/cmd/hoofy@latest

# Or build from source
git clone https://github.com/HendryAvila/Hoofy.git
cd Hoofy
make build

claude mcp add --scope user hoofy hoofy serve

/plugin marketplace add HendryAvila/hoofy-plugins
/plugin install hoofy@hoofy-plugins

{
  "mcpServers": {
    "hoofy": {
      "command": "hoofy",
      "args": ["serve"]
    }
  }
}

{
  "servers": {
    "hoofy": {
      "type": "stdio",
      "command": "hoofy",
      "args": ["serve"]
    }
  }
}

{
  "mcp": {
    "hoofy": {
      "type": "local",
      "command": ["hoofy", "serve"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "hoofy": {
      "command": "hoofy",
      "args": ["serve"]
    }
  }
}

hoofy update