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:

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

🏗️ 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:

<!-- @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"