# Sdd

> Spec-Driven Development. High-performance modular workflow with Explore-Plan-Act Loop and Safety-Valve protocols. Orchestrates specialized sub-skills. [TLC Spec Driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven)

- Skill: `klebersoncollab/sdd` (Agent Skill, multi-file: 23 files)
- Install (CLI): `npx skillmds@latest add klebersoncollab/sdd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/klebersoncollab/sdd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: KlebersonCollab (https://skillmd.com/u/klebersoncollab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/klebersoncollab/sdd

---


## 🔒 Prerequisites (Mandatory)
This skill operates as the central brain for the **SDD** framework. Before any technical execution:
0. **Mode Check**: Verify `.hub-mode` and apply `token-distiller` guidelines.
1. **Context Check**: Rehydrate state by reading `STATE.md`, `MEMORY.md`, and `LEARNINGS.md`.
2. **Knowledge Check**: Follow the **Knowledge Verification Chain** (see below).

---

# SDD: Modular & Adaptive Workflow (v2.3.0)

> Precision at scale. Rigor when needed, speed when possible.

---

## 🧩 Delegation Matrix
The SDD workflow delegates heavy lifting to specialized sub-skills to maintain a clean context window:

| Phase | Sub-Skill | Primary Artifact | Purpose |
|---|---|---|---|
| **DISCOVERY** | `sdd-explorer` | `TECHNICAL-MAP.md` | Read-only mapping of stack, architecture, and risks. |
| **SPECIFY** | `sdd-orchestrator`, `grill-with-docs` | `spec.md`, `plan.md`, `CONTEXT.md`, `ADRs` | Domain glossary alignment (Sabatina/Grilling), requirement analysis, and architectural decisions. |
| **IMPLEMENT** | `sdd-implementer` | Tested Code | Surgical implementation with TDD and atomic commits. |
| **VERIFY** | `sdd-reviewer` | `validation-report.md` | Evidence-based audit against Acceptance Criteria. |

---

## 🔄 4-Phase Workflow

The SDD follows a rigorous cycle to ensure integrity and traceability:

### 1. DISCOVERY
*   **Goal**: Understand the terrain and align with the project vision.
*   **Action**: Use `sdd-planner` to read `PROJECT.md` and `ROADMAP.md`. Use `sdd-explorer` to map stack and architecture.
*   **Output**: Updated `TECHNICAL-MAP.md` and "rehydrated" context via `STATE.md`.
*   **Handoff**: Follow [Handoff Protocol](references/handoff-protocol.md) Section 1.
*   **Trigger**: Session start or new complex feature.

### 2. SPECIFY
*   **Goal**: Define "what", "how", refine terminology and record technical decisions.
*   **Action**: 
    1. **Grilling Session**: Challenge the plan relentlessly against the existing domain model. Sharpen vague language and update `CONTEXT.md` (Domain Glossary) inline.
    2. **Specification & Plan**: Use `sdd-orchestrator` to generate `spec.md`, `plan.md`, `tasks.md`, and `contract.md`. Use adversarial review (GAN concept) for critical architectures.
    3. **ADRs Logging**: Create Architectural Decision Records (ADRs) under `.specs/architecture/` (or `docs/adr/`) only for hard-to-reverse, surprising, or trade-off-heavy decisions.
*   **Outputs**: `spec.md`, `plan.md`, `tasks.md`, `contract.md`, `CONTEXT.md` + new ADRs (if applicable).
*   **Handoff**: Follow [Handoff Protocol](references/handoff-protocol.md) Section 2.
*   **Trigger**: Before any implementation (**Small+**).

### 3. IMPLEMENT
*   **Goal**: Technical execution. If resolving an issue, **reproduce the bug first** before coding.
*   **Action**: **Create a feature branch** (refer to `git-workflow`). Use `sdd-implementer` for code/tests. Update `STATE.md` continuously.
*   **Output**: Verified code on a dedicated branch and updated `tasks.md`.
*   **Handoff**: Follow [Handoff Protocol](references/handoff-protocol.md) Section 3.
*   **Trigger**: After Phase 2 is approved.

### 4. VERIFY
*   **Goal**: Validate delivery and capture learnings.
*   **Action**: **Drive app to verify** (boot application and test functionality/UI). Use `sdd-reviewer` for audit, **open a Pull Request**, and use `sdd-planner` to capture discovered patterns.
*   **Output**: PR created, `validation-report.md`, `LEARNINGS.md`, and `MEMORY.md` updated. State finalization in `STATE.md` and PR opened and submitted for human review.
*   **Handoff**: Follow [Handoff Protocol](references/handoff-protocol.md) Section 4.
*   **Trigger**: Technical completion of Phase 3 tasks.

---

## 🛠️ Operational Protocols

### 1. The Gated Workflow Mandate (Gated Transition)
Progress between phases is strictly sequential and permission-gated:
- **Rule**: You CANNOT set `phase: [NEXT_PHASE]` in `STATE.md` if the current `tasks.md` does not have 100% test coverage and status and verifiable evidence for the current phase.
- **Initial State**: New feature artifacts (`spec.md`, `plan.md`, `tasks.md`) MUST start with `status: IN_PROGRESS`.
- **Completion Hook**: An artifact only moves to `status: COMPLETED` when its specific content is frozen and approved for the next phase.

### 2. State Machine Integrity
Every agent interaction must validate the "State Triad":
1. **STATE.md** `phase` must match the current focus.
2. **tasks.md** must have at least one open task for the current phase.
3. **Artifact Metadata** must show `status: IN_PROGRESS` for files currently being edited.

### 3. The Safety Valve (Automatic Escalation)
Every implementation task must be continuously monitored for complexity drift.
- **Trigger**: If a task reveals unexpected structural changes, touches >3 files, or modifies components.
- **Action**: **STOP** execution. Notify the user: *"Task complexity has escalated beyond initial sizing. Re-evaluating the plan."*
- **Outcome**: Re-invoke `sdd-orchestrator` to update `plan.md` or `tasks.md`.

### 2. Knowledge Verification Chain
To prevent hallucinations and pattern drift, follow this strict hierarchy:
1. **Existing Code**: Scan for established patterns. **Managing Entropy**: Do not blindly replicate technical debt. If existing code violates `CONVENTIONS.md`, initiate a "Garbage Collection" refactor instead of perpetuating bad patterns.
2. **Internal Specs**: Consult `TECHNICAL-MAP.md`, `CONVENTIONS.md`, and `STATE.md`.
3. **Project Documentation**: Check READMEs and official internal docs.
4. **MCP/External Tools**: Query `context-graph` or perform targeted web searches.
5. **Flag Uncertainty**: If Steps 1-4 yield no proof, flag as "Uncertain" to the user. **Never assume.**

### 3. Context Budget Management
- **Base Context**: Always load `STATE.md` (current progress) and `MEMORY.md` (preferences).
- **On-Demand**: Only load sub-skill definitions and specific feature specs when active in that phase.
- **Limit**: Target <30k tokens for the base environment to leave maximum room for reasoning.

### 4. Manual Progress Tracking
- **Atomicity**: Every task must be mapped to a specific commit.
- **State Check**: Update `tasks.md` and `STATE.md` immediately after every significant milestone.
- **Traceability**: If it's not in the Markdown logs, it didn't happen.

### 5. Swarm & Multi-Agent Execution
When working with multiple parallel agents or personas:
- **Infrastructure**: Utilize Tmux or iTerm2 for session persistence and visual tracking.
- **Security**: Propagate `DANGEROUS_BASH_PATTERNS` to all swarm members.
- **GAN Pattern**: Implement **Generative Adversarial** loops where agents alternate between creating (Generator) and auditing (Discriminator) to maximize quality.
- **Protocol**: Follow the [Swarm Execution Guide](references/swarm-execution.md).

---

## 🏗️ Production Patterns

### Explore-Plan-Act Loop
Strict permission-gated flow:
- **EXPLORE**: No code modifications allowed.
- **PLAN**: Design validation via **Plan-Validate-Execute (PVE)**.
- **ACT**: Atomic execution on feature branches.

### Agent-First Legibility & Observability
- **Bootable Environments**: The project must offer standardized, agent-friendly commands to easily boot and test the application per worktree.
- **Legible Failures**: Expose structured logs, metrics, and traces so the agent can query and reason about isolated test/execution failures autonomously.

### The Autonomy PR Loop (Mandatory)
- **Branch First**: Before writing any code in `IMPLEMENT`, you MUST create a branch following the `git-workflow` skill (e.g., `feat/FEAT-ID-...`). **Never commit directly to `main` or `master`.**
- **Verify then PR**: After successful `VERIFY` ("Drive app to verify" + sensors passed), you MUST open a Pull Request. The PR description must link to the `validation-report.md` as evidence.

### Visual-First Mandate
All technical plans (`plan.md`) MUST include **Mermaid** diagrams to visualize data flow and component relationships.

---

## 🚫 Prohibited

- NEVER skip the **DISCOVERY** phase for unknown codebases.
- NEVER mark a task as complete without an atomic Git commit AND explicit proof that the application builds, passes linting, and passes tests.
- NEVER use placeholders in `spec.md` or `plan.md`.
- NEVER ignore "Fragile" warnings in `TECHNICAL-MAP.md`.
- NEVER force a phase transition if the current `tasks.md` does not have 100% status coverage and verifiable evidence for the current phase.
- NEVER exit the implementation cycle without pushing to the branch.
- NEVER submit a PR without tests.
- NEVER ignore the modification of 3 or more files without going through an adversarial review.
- NEVER modify a file without assessing the impact.
- NEVER ignore adversarial critique.
- NEVER ignore the safety valve.

---

## 5. State & Memory Management

### Persistence Protocol (via `sdd-planner`)
Always update `STATE.md` at the end of every session or after major decisions.
1.  **Operational Memory (`STATE.md`)**: Tasks, session status, and blockers.
2.  **Persistent Knowledge (`MEMORY.md`)**: Enduring facts, style guides, and preferences.
3.  **Incremental Wisdom (`LEARNINGS.md`)**: Bug solutions and discovered patterns.

---

## 6. Directory Structure (Mandatory)

### Feature-Specific (`spec/` or `.specs/features/[name]/`)
- `spec.md`: Traceable requirements (FR-X) and Acceptance Criteria (ACs).
- `plan.md`: Technical design and schemas.
- `tasks.md`: Atomic task list with status.
- `contract.md`: Delivery agreement and validation sensors.

### Project-Wide (`.specs/project/` or Root)
- `PROJECT.md`: Core vision and "North Star".
- `ROADMAP.md`: Milestones and feature status.
- `STATE.md`: Operational memory (current status, blockers).
- `MEMORY.md`: Persistent knowledge (patterns, preferences).
- `LEARNINGS.md`: Incremental wisdom (solved bugs, tricks).
- `DECISIONS.md`: Log of architectural and design decisions.
- `CONTEXT.md`: **Domain Glossary**: Centralized list of precise terms and vocabulary unique to this domain (totally devoid of implementation details).

### Codebase Mapping & Architecture (`.specs/codebase/` and `.specs/architecture/`)
- `TECHNICAL-MAP.md`: Mapping of stack and dependencies.
- `CONVENTIONS.md`: Coding patterns and linting.
- `ARCHITECTURE.md`: High-level structural view.
- `.specs/architecture/[0001-slug].md` (or `docs/adr/`): **Architectural Decision Records (ADRs)**: Concise records of critical design choices and their trade-offs.

### 7. Observable Governance (Mandatory v2.3.0)
To enable real-time monitoring and automated auditing, every artifact generated MUST include a structured metadata block.

#### Metadata Protocol
At the end of every `.md` artifact, append the following block:
```markdown
<!-- @sdd-state -->
```yaml
version: "2.3.0"
feature_id: "FEAT-ID"
phase: "DISCOVERY | SPECIFY | IMPLEMENT | VERIFY"
status: "IN_PROGRESS | COMPLETED | BLOCKED"
last_update: "ISO-TIMESTAMP"
evidence_checksum: "GIT-HASH | LOG-PATH | NONE"
```
```

#### Evidence Mandate
Tasks in `tasks.md` MUST NOT be marked as complete without a valid entry in the `Evidence` column (e.g., a commit hash or a link to a test log). Furthermore, a task CANNOT be marked as completed unless the application builds successfully, passes the linting, and passes all tests. This is a mandatory requirement.

---


> **Law of SDD**: If it's not in the spec, it doesn't exist. If it's not verified, it's not done.

---

## References
- [Brownfield Mapping Guide](references/brownfield-mapping.md)
- [Coding Principles](references/coding-principles.md)
- [Operational Guidelines](references/operational-guidelines.md)
- [BDD Standard](references/bdd-guide.md)
- [Handoff Protocol](references/handoff-protocol.md)
- [Swarm Execution Guide](references/swarm-execution.md)
- [Grilling Session Guide](references/grilling-session.md)

---

<!-- @sdd-state -->
```yaml
version: "2.3.0"
feature_id: "SDD-CORE-ALIGNMENT"
phase: "VERIFY"
status: "COMPLETED"
last_update: "2026-05-22T14:23:00Z"
evidence_checksum: "8e52f6a"
```