Workflow Guide

March 12, 2026 · View on GitHub

This guide walks you through real workflows using Hoofy's systems: Memory, Change Pipeline, Project Pipeline, Bootstrap, and Standalone tools. Each section shows what happens step by step, so you know what to expect.

Which System Do I Use?
Workflow 0: Explore Before You Plan
Workflow 1: New Project (Greenfield)
Workflow 2: Changes in an Existing Project
Workflow 3: Ad-Hoc Sessions (No Pipeline)
Workflow 4: Memory Best Practices
The Adaptive Flow Matrix

Which System Do I Use?

I want to...	Use this	First command
Think through an idea before committing	Explore	`sdd_explore`
Build something from scratch	Project Pipeline	`sdd_init_project`
Add a feature to existing code	Change Pipeline	`sdd_change(type: "feature", size: "medium")`
Fix a bug	Change Pipeline	`sdd_change(type: "fix", size: "small")`
Refactor code	Change Pipeline	`sdd_change(type: "refactor", size: "medium")`
Quick task without starting a pipeline	Standalone	`sdd_suggest_context`
Review code against specs	Standalone	`sdd_review`
Audit specs against actual code	Standalone	`sdd_audit`
Add specs to existing project with no specs	Bootstrap	`sdd_reverse_engineer`
Remember a decision or discovery	Memory	`mem_save`
Pick up where I left off	Memory	`mem_context`

Facade-first note:

Prefer mem_save (save_type) for observation/prompt/passive capture.
Use mem_session(action: "start"|"end") for session lifecycle.

Workflow 0: Explore Before You Plan

Before jumping into a pipeline, use sdd_explore to capture unstructured thinking. This is especially useful when you're discussing an idea with the AI and haven't decided on scope or approach yet.

When to use it

You're brainstorming with the AI and want to capture the discussion
You know the problem but aren't sure about the solution
You have constraints or preferences the AI should know before planning
You want the AI to suggest whether this is a small fix or a large feature

How it works

You: "I want to add search to the app. Maybe full-text? Not sure if I need fuzzy matching. It has to be fast — under 100ms."

AI: Calls sdd_explore with:

Goals: Add search functionality to the app

Constraints: Response time under 100ms

Unknowns: Full-text vs. fuzzy matching, search scope (all fields or specific ones?)

Preferences: Performance is a priority

The context is saved to memory with a topic key. If the discussion evolves:

You: "Actually, let's do full-text with SQLite FTS5 — no external dependencies."

AI: Calls sdd_explore again — upserts the same observation with updated decisions

What you get

Structured context in memory that the AI references when you start a pipeline
A suggested change type and size based on keywords (e.g., "new feature, medium complexity")
No duplicates — repeated calls update the same observation via topic key

Then what?

After exploring, start the right pipeline:

sdd_explore → sdd_change(type: "feature", size: "medium")
sdd_explore → sdd_init_project  (if it's greenfield)

The AI already has your goals, constraints, and decisions in memory — the pipeline starts with clarity.

Workflow 1: New Project (Greenfield)

For building something from scratch. The 9-stage pipeline forces you to think through principles, requirements, and architecture before writing a single line of code.

The Pipeline

flowchart LR
    A[Init] --> A2[Principles]
    A2 --> B[Charter]
    B --> C[Requirements]
    C --> BR["Business\nRules"]
    BR --> D{Clarity Gate}
    D -->|Score < threshold| C
    D -->|Score >= threshold| E[Design]
    E --> F[Tasks]
    F --> G[Validate]

    style A2 fill:#e879f9,stroke:#c026d3,color:#000
    style BR fill:#e879f9,stroke:#c026d3,color:#000
    style D fill:#f59e0b,stroke:#d97706,color:#000
    style G fill:#10b981,stroke:#059669,color:#fff

Step by Step

Stage 1 — Init (sdd_init_project)

You tell the AI what you want to build. It creates the docs/ directory with hoofy.json and auto-generates an SDD section in your project's agent file (CLAUDE.md, AGENTS.md, or creates AGENTS.md if none exists).

You: "I want to build a CLI tool that tracks daily habits"

AI: Creates docs/hoofy.json with project name and mode (guided/expert)

Stage 2 — Principles (sdd_create_principles)

Before writing any requirements, the pipeline captures golden invariants — project principles, coding standards, and domain truths that remain constant throughout the project lifecycle. These anchor every subsequent stage.

You: "It should be CLI-first, zero external dependencies, UNIX philosophy — do one thing well. Test coverage above 80%."

AI: Writes principles to docs/principles.md

Principles inform every downstream artifact — requirements must respect them, designs must implement them, and the Clarity Gate evaluates against them.

Stage 3 — Charter (sdd_create_charter)

The AI asks you questions to understand the problem, domain, and scope. Then it writes an enterprise-grade charter with:

Problem statement — what pain are you solving?
Domain context — what domain is this in?
Target users / stakeholders — who is this for?
Vision — what does it do?
Boundaries — what it does NOT do (prevents scope creep)
Success criteria — how do we know it works?
Existing systems — what's already in place?
Constraints — technical, business, or regulatory limitations

Four fields are required (problem, users, vision, boundaries); six are optional for smaller projects.

You: "It's for developers who forget to exercise, drink water, etc."

AI: Writes charter to docs/charter.md

Stage 4 — Requirements (sdd_generate_requirements)

The AI reads the charter and extracts formal requirements with MoSCoW prioritization:

Must Have (FR-001, FR-002...) — launch blockers
Should Have — important but not blocking
Could Have — nice-to-have for the future
Won't Have — explicitly excluded
Non-Functional (NFR-001...) — performance, security, usability

AI: "FR-001: Users can add a new habit with name and daily goal" AI: "NFR-001: CLI response time must be under 200ms" AI: Writes requirements to docs/requirements.md

Stage 5 — Business Rules (sdd_create_business_rules)

The AI reads the requirements and extracts declarative business rules using the BRG (Business Rules Group) taxonomy and DDD Ubiquitous Language:

Definitions — What terms mean in this domain (glossary)
Facts — Structural truths about entities and relationships
Constraints — Conditions that must always be true (invariants)
Derivations — Values computed from other values

AI: "RULE-001 (Constraint): A habit's daily goal must be a positive integer >= 1" AI: "RULE-002 (Fact): A user has zero or more habits. Each habit belongs to exactly one user." AI: Writes rules to docs/business-rules.md

Rules are extracted FROM requirements and inform the Clarity Gate — the gate evaluates WITH the rules, not before them.

Stage 6 — Clarity Gate (sdd_clarify)

This is the core innovation. The AI analyzes your requirements across 8 dimensions:

Dimension	What it checks
Target users	Are personas specific enough?
Core functionality	Is each feature clearly defined?
Data model	Are entities and relationships clear?
Integrations	Are external dependencies identified?
Edge cases	Are error scenarios handled?
Security	Are auth/data-protection needs clear?
Scale & performance	Are load expectations defined?
Scope boundaries	Is the line between in/out of scope sharp?

Each dimension gets a score (0-100). The pipeline blocks until the overall score meets the threshold:

Guided mode: 70/100
Expert mode: 50/100

If ambiguities are found, the AI asks you specific questions. You answer, it rescores. This loop continues until the gate passes.

AI: "Your data model is unclear — does a habit have categories? Can habits repeat on specific days or is it daily only?"

You: "Daily only, no categories in v1"

AI: Score jumps from 55 to 78 — gate passes

Stage 7 — Design (sdd_create_design)

Now the AI writes the technical architecture:

Architecture overview and patterns
Tech stack with rationale
Component breakdown (mapped to requirements)
Data model with schema
API contracts (if applicable)
Security measures
Infrastructure and deployment
Structural quality analysis (SOLID compliance, code smell detection, coupling & cohesion)

Architecture Decision Records (ADRs) are captured separately with sdd_adr and stored in docs/adrs/ — not inline in the design document.

AI: Writes design to docs/design.md

Stage 8 — Tasks (sdd_create_tasks)

The AI breaks the design into atomic, implementable tasks. Each task has:

Unique ID (TASK-001)
Requirements it covers (FR-001, NFR-002)
Components affected
Dependencies on other tasks
Acceptance criteria (checkboxes)
A dependency graph showing parallelization opportunities
Optional wave assignments — tasks grouped into parallel execution waves (see Wave Assignments below)

AI: "TASK-001: Set up project scaffolding -> TASK-002: Implement habit storage -> TASK-003: Add CLI commands..." AI: Writes tasks to docs/tasks.md

Stage 9 — Validate (sdd_validate)

Cross-artifact consistency check. The AI verifies:

Every requirement has at least one task covering it
Every component in the design has tasks assigned
No tasks reference non-existent requirements
No scope creep (tasks stay within charter boundaries)
Structural quality analysis from design is verified against the task breakdown

Verdict: PASS, PASS_WITH_WARNINGS, or FAIL (sends you back to fix gaps).

What you get

docs/
├── hoofy.json          # Pipeline state and config
├── principles.md       # Golden invariants and coding standards
├── charter.md          # Problem, domain, users, vision, boundaries
├── requirements.md     # Formal requirements (MoSCoW)
├── business-rules.md   # Declarative rules (BRG taxonomy + DDD)
├── clarifications.md   # Clarity Gate Q&A
├── design.md           # Technical architecture
├── tasks.md            # Implementation breakdown
├── validation.md       # Cross-check results
└── adrs/               # Architecture Decision Records
    └── 001-slug.md     # Individual ADR files

Every artifact is a markdown file you can read, edit, and version control. The AI references these specs while coding — no more hallucinated features.

Workflow 2: Changes in an Existing Project

For ongoing development. The pipeline adapts — a small bug fix gets 4 stages, a large feature gets 7.

The Pipeline

flowchart LR
    A[Create Change] --> B[Opening Stage]
    B --> CC["Context\nCheck"]
    CC --> C{More stages?}
    C -->|Yes| D[Next Stage]
    D --> C
    C -->|No| E[Tasks]
    E --> F[Verify]

    style A fill:#6366f1,stroke:#4f46e5,color:#fff
    style CC fill:#e879f9,stroke:#c026d3,color:#000
    style F fill:#10b981,stroke:#059669,color:#fff

Every change — regardless of type or size — includes a context-check stage. The tool scans existing specs, completed changes, memory observations, and convention files to detect conflicts before you proceed.

The opening stage and intermediate stages change based on type x size:

Example: Small Fix (4 stages)

You: "The search crashes when the query is empty"

describe → context-check → tasks → verify

The AI describes the bug, scans for conflicts, breaks the fix into tasks, and verifies. Quick, minimal ceremony — but safe.

Example: Medium Feature (5 stages)

You: "I want to add CSV export to the reports"

charter → context-check → spec → tasks → verify

The AI writes a brief charter, checks for conflicts, extracts requirements, creates tasks, and verifies coverage.

Example: Large Feature (7 stages)

You: "I want to add a plugin system with hooks and lifecycle management"

charter → context-check → spec → clarify → design → tasks → verify

Full ceremony — charter, context check, requirements, Clarity Gate, architecture, tasks, validation. The same rigor as a greenfield project, scoped to the change.

Change Artifacts

Each change lives in its own directory:

docs/changes/
└── fix-empty-query-crash/
    ├── change.json       # Metadata (type, size, stages, status)
    ├── context-check.md  # Conflict scan results
    ├── describe.md       # What's the problem?
    ├── tasks.md          # Implementation breakdown
    └── verify.md         # Verification results

Completed changes are archived to docs/history/<slug>/.

ADRs (Architecture Decision Records)

At any point during a change, you can capture a decision:

You: "We decided to use SQLite instead of PostgreSQL for the local store"

AI: Records ADR with context, decision, rationale, and rejected alternatives

ADRs are stored in docs/adrs/ with sequential NNN-slug.md naming. They are also saved to persistent memory — they survive archival and are searchable across sessions.

Wave Assignments

When the AI creates the task breakdown (in either pipeline), it can optionally group tasks into parallel execution waves:

**Wave 1** (parallel — no dependencies):
- TASK-001: Project scaffolding
- TASK-002: Database schema

**Wave 2** (parallel — depends on Wave 1):
- TASK-003: API endpoints
- TASK-004: Auth module

**Wave 3** (sequential — depends on Wave 2):
- TASK-005: Integration tests

The algorithm is simple: tasks with no dependencies go in Wave 1, tasks depending only on Wave 1 go in Wave 2, and so on. This tells you:

Which tasks can run in parallel (same wave)
Which must wait (later wave)
The critical path through the implementation

The AI generates wave assignments automatically when the dependency graph has parallelization opportunities. They appear in the tasks.md artifact alongside the dependency graph.

Workflow 3: Ad-Hoc Sessions (No Pipeline)

Not every task needs a formal pipeline. Sometimes you're debugging, exploring, or doing a quick task. The standalone tools work without hoofy.json, without an active change, and without any ceremony.

Context Suggestion — "What should I read first?"

Before starting ad-hoc work, ask the AI to suggest relevant context:

You: "I need to optimize the search query — it's slow on large datasets"

AI: Calls sdd_suggest_context(task_description: "optimize search query slow large datasets")

The tool scans:

Existing specs — requirements, business rules, design docs in docs/
Completed changes — past changes that touched related areas
Memory observations — past decisions, discoveries, bugs about search/performance
Convention files — CLAUDE.md, AGENTS.md, CONTRIBUTING.md

Returns a prioritized list: "Read these 3 things before you start." No pipeline needed.

Spec-Aware Code Review — "Did I miss anything?"

After implementing, ask the AI to verify against specs:

You: "Review the search optimization I just implemented"

AI: Calls sdd_review(change_description: "optimized search query with index and pagination")

The tool parses:

Requirements — finds matching FR-XXX entries
Business rules — finds matching BRC-XXX constraints
Design decisions — finds relevant architecture sections
ADRs from memory — finds related architectural decisions

Returns a checklist: "Verify FR-012 is still satisfied. Check that BRC-003 constraint on max results is respected. Confirm ADR about SQLite FTS5 is followed."

Spec-vs-Code Audit — "Are my specs still accurate?"

Over time, specs drift from reality. sdd_audit scans your specs against actual source code:

You: "Are our specs still matching the code?"

AI: Calls sdd_audit — scans docs/ specs and compares against source files

The tool produces a structured report:

Missing implementations — specs that exist but have no corresponding code
Stale specs — code that has changed but specs haven't been updated
Inconsistencies — contradictions between spec and implementation

Read-only — it never modifies files. The AI analyzes the report and recommends actions.

When to use standalone vs. pipeline

Situation	Use...
Quick fix, clear what to do	`sdd_suggest_context` -> fix -> `sdd_review`
Bug investigation, not sure of scope	`sdd_suggest_context` -> investigate -> maybe `sdd_change` if bigger
Post-implementation sanity check	`sdd_review`
Spec drift detection	`sdd_audit`
Non-trivial change (new feature, refactor)	`sdd_change` (formal pipeline)

The standalone tools are the "fast path" — they give you spec awareness without pipeline overhead.

Workflow 4: Memory Best Practices

Memory is always running in the background. Here's how to get the most out of it.

Session Lifecycle

flowchart LR
    A[Session Start] --> B[Work]
    B --> C{Discovery?}
    C -->|Yes| D[mem_save]
    D --> B
    C -->|No| B
    B --> E[Session Summary]
    E --> F[Session End]

    style A fill:#6366f1,stroke:#4f46e5,color:#fff
    style D fill:#f59e0b,stroke:#d97706,color:#000
    style F fill:#10b981,stroke:#059669,color:#fff

Start — AI calls mem_session(action: "start") and mem_context to load recent history
Work — As you work, the AI saves observations when something important happens
End — AI writes a session summary capturing what was done, discovered, and what's next

What to Save

Type	Save when...	Example
`decision`	You chose approach A over B	"Chose PostgreSQL over MongoDB for ACID compliance"
`architecture`	You defined a structural pattern	"Event-driven communication between services"
`bugfix`	You found and fixed a bug	"FTS5 crash on special characters — wrapped in quotes"
`pattern`	You established a convention	"All API errors return `{error, code, details}` shape"
`discovery`	You learned something non-obvious	"modernc.org/sqlite doesn't support extensions"
`config`	You changed environment or tooling	"Switched from npm to pnpm for workspace support"

Search Patterns

mem_search("authentication") — find past decisions about auth
mem_context — what happened in the last few sessions?
mem_timeline(observation_id) — what happened before and after a specific event?
mem_search + mem_get — search finds it, get retrieves full content

Topic Keys (Evolving Knowledge)

For knowledge that changes over time, use topic keys. Instead of creating 10 observations about the "database schema", the AI uses topic_key: "architecture/database-schema" — each new save updates the existing observation instead of creating a duplicate.

Knowledge Graph

Observations can be connected with typed, directional relations to form a knowledge graph:

Relation	Meaning	Example
`relates_to`	General association	A pattern relates to a convention
`depends_on`	A requires B	A task depends on a design decision
`caused_by`	A was triggered by B	A bugfix was caused by a discovery
`implements`	A realizes B	Code implements a design decision
`supersedes`	A replaces B	A new decision supersedes an old one
`part_of`	A belongs to B	A component is part of an architecture

The AI creates relations automatically when it recognizes connections between observations. You can also ask it explicitly: "relate the JWT decision to the auth bugfix".

Traversing the graph: Use mem_get with depth to pull in connected observations from the graph. This is powerful for understanding full context around a decision — what caused it, what implements it, what it relates to.

mem_get(id: 42, depth: 2)
-> Returns the observation, its direct relations, and graph context

The Adaptive Flow Matrix

The change pipeline selects stages automatically. Here's every combination:

Type	Small	Medium	Large
Fix	describe -> context-check -> tasks -> verify	describe -> context-check -> spec -> tasks -> verify	describe -> context-check -> spec -> design -> tasks -> verify
Feature	describe -> context-check -> tasks -> verify	charter -> context-check -> spec -> tasks -> verify	charter -> context-check -> spec -> clarify -> design -> tasks -> verify
Refactor	scope -> context-check -> tasks -> verify	scope -> context-check -> design -> tasks -> verify	scope -> context-check -> spec -> design -> tasks -> verify
Enhancement	describe -> context-check -> tasks -> verify	charter -> context-check -> spec -> tasks -> verify	charter -> context-check -> spec -> clarify -> design -> tasks -> verify

12 flows, all deterministic. Every flow includes context-check — the AI scans for conflicts before proceeding. You just say what you want to do and how big it is.

Stage Descriptions

Stage	Purpose	Used by
`context-check`	Scans existing specs, completed changes, memory, and convention files for conflicts	Every change (mandatory)
`describe`	Quick description of the change	Fix (all sizes), Feature (S), Enhancement (S)
`scope`	What changes and what stays the same	Refactor only
`charter`	Full charter with problem/domain/vision/boundaries	Feature (M/L), Enhancement (M/L)
`spec`	Formal requirements (MoSCoW)	Medium and Large changes
`clarify`	Clarity Gate — resolve ambiguities	Large Feature and Enhancement only
`design`	Technical architecture	Large changes + Medium Refactor
`tasks`	Implementation breakdown	Every change
`verify`	Verification checklist	Every change