diff --git a/AGENTS.md b/AGENTS.md index 8ca932d..72392d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,28 +2,45 @@ ## Purpose -This repository contains the SLDD (Spec Loops Driven Development) skills — structured AI agent prompt files that enforce a gate-based, specs-driven workflow for disciplined AI-assisted development. +This repository contains the SLDD (Spec Loops Driven Development) skill: structured AI agent prompt files that enforce a gate-based, specs-driven workflow for disciplined AI-assisted development. ## Global Agent Behavior ### Do -- Keep all `SKILL.md` files in their designated directories under `skills/`, following the naming pattern `sldd-NN-/`. -- Preserve YAML frontmatter structure (`name`, `description`, `metadata.step`, `metadata.type`) when editing skills. -- Write skill content in plain, actionable Markdown. Document behavior, not implementation. -- Maintain consistency across all skill files (tone, structure, gate enforcement patterns). -- Ensure every skill has: a clear objective, gate enforcement rules, approval protocol, and output format. + +- Keep `skills/sldd/SKILL.md` as the only executable SLDD skill entrypoint. +- Keep step behavior under `skills/sldd/steps/`. +- Keep artifact formats under `skills/sldd/templates/`. +- Keep journal schema files under `skills/sldd/schema/`. +- Preserve YAML frontmatter structure in `skills/sldd/SKILL.md` (`name`, `description`, `metadata.type`). +- Write skill and step content in plain, actionable Markdown. Document behavior, not implementation. +- Maintain consistency across all step files: tone, structure, gate enforcement patterns, approval protocol, and output format. +- Ensure every step has a clear objective, gate enforcement rules, approval protocol when applicable, save/progress behavior, and response format. +- Preserve progressive disclosure: `SKILL.md` routes and loads exactly the step file needed; templates are loaded only for produced Markdown artifacts. +- Preserve `.sldd/specs//_spec-journal.json` as the canonical journal for new workflows. +- Preserve legacy resume compatibility for `docs/specs//SPEC.md` unless explicitly removed. +- Preserve `/sldd help` as an informational command that explains the skill and does not mutate journals, artifacts, or workflow state. - Preserve the Step 04/Step 05 Red-Green contract: Step 04 writes tests first only; Step 05 makes minimal production changes, does not modify Step 04 tests, and follows applicable repository or context-provided agent instructions. -- Update `README.md` when changing user-visible process behavior, sequencing, gates, approval semantics, or skill responsibilities. +- Update `README.md` when changing user-visible process behavior, sequencing, gates, approval semantics, commands, journal fields, storage, templates, installer options, or step responsibilities. - Use Conventional Commits for commit messages, following the `(optional-scope): ` format. ### Don't -- Do not add runtime code, build scripts, or package configuration — this repo is Markdown-only. -- Do not introduce conventions, frameworks, or patterns not already present in the existing skills. -- Do not create new skill files without explicit user instruction. -- Do not modify `README.md` or `LICENSE` unless explicitly asked. + +- Do not add runtime application code, build scripts, package configuration, or CI/CD changes. +- Do not introduce conventions, frameworks, or patterns not already present in the SLDD skill architecture. +- Do not create additional executable SLDD skill entrypoints without explicit user instruction. +- Do not store numbered artifact body content, command logs, or implementation reports in `_spec-journal.json`. +- Do not modify `LICENSE` unless explicitly asked. + +## Repository Content Policy + +- This repository is documentation- and skill-oriented. +- Markdown files are allowed for skill instructions, steps, templates, repository documentation, and evaluations. +- JSON schema files are allowed under `skills/sldd/schema/`. +- Shell scripts already present for local skill installation may be maintained, but do not add new runtime scripts without explicit instruction. ## Agent Limits -- Scope is limited to authoring, editing, and reviewing `SKILL.md` files and repository documentation. -- No code execution, no external API calls, no CI/CD changes. -- All changes must be consistent with the SLDD methodology and the existing skill set. +- Scope is limited to authoring, editing, and reviewing skill instructions, step files, templates, JSON schema files, repository documentation, and existing installation documentation/scripts. +- No external API calls, no CI/CD changes, and no runtime application code. +- All changes must be consistent with the SLDD methodology and the current single-skill architecture. diff --git a/README.md b/README.md index a27f40c..aac2544 100644 --- a/README.md +++ b/README.md @@ -1,152 +1,187 @@ -# SLDD Skills - Spec Loops Driven Development +# SLDD Skill - Spec Loops Driven Development -A collection of AI skills for implementing **Spec Loops Driven Development (SLDD)**, a specs-driven feedback loop for AI-assisted development. +A runtime skill for implementing **Spec Loops Driven Development (SLDD)**, a specs-driven feedback loop for disciplined AI-assisted development. -## Overview +SLDD adds engineering control around AI-assisted coding so teams can keep speed without sacrificing quality. -SLDD (Spec Loops Driven Development) is a methodology that adds engineering control around AI-assisted coding, enabling teams to maintain speed without sacrificing quality. This repository contains ready-to-use runtime skills that implement the SLDD process. - -### Based On +## Based On This work is based on the article **["Vibe Coding, But Production-Ready: A Specs-Driven Feedback Loop for AI-Assisted Development"](https://loiane.com/2026/03/vibe-coding-with-specs-driven-feedback-loops/)** by [Loiane Groner](https://loiane.com/). > **The goal is not to stop vibe coding. The goal is to add engineering control around vibe coding so we can keep speed without sacrificing quality.** > -> — Loiane Groner +> - Loiane Groner ## What Problem Does SLDD Solve? When using AI for code generation, teams often face: -- **Version drift**: AI selects framework versions that don't align with team policy -- **Missing non-functional requirements**: Security, observability, maintainability -- **Diluted product intent**: Implementation starts before design is clear -- **Architecture confusion**: Plausible codebase mistaken for valid architecture +- **Version drift**: AI selects framework versions that do not align with team policy. +- **Missing non-functional requirements**: Security, observability, and maintainability are discovered too late. +- **Diluted product intent**: Implementation starts before design is clear. +- **Architecture confusion**: Plausible code is mistaken for valid architecture. SLDD provides a structured feedback loop that prevents these issues while maintaining development velocity. ## Installation -### Using Skills CLI (Recommended) +### Using Skills CLI -Install all SLDD runtime skills with a single command: +Install the SLDD runtime skill with: ```bash npx skills add soujava/sldd-skills ``` -This will automatically download and configure the executable SLDD skills for your AI agent. - ### Manual Installation -#### For Claude Code - -Copy the skill directories to your Claude skills folder: +#### Claude Code ```bash -# Clone the repository git clone https://github.com/soujava/sldd-skills.git - -# Copy to Claude skills directory -cp -r sldd-skills/skills/sldd-* ~/.claude/skills/ +cp -r sldd-skills/skills/sldd ~/.claude/skills/ ``` -#### For OpenCode - -Copy the skill directories to your OpenCode skills folder: +#### OpenCode ```bash -# Clone the repository git clone https://github.com/soujava/sldd-skills.git - -# Copy to OpenCode skills directory -cp -r sldd-skills/skills/sldd-* ~/.agents/skills/ +cp -r sldd-skills/skills/sldd ~/.agents/skills/ ``` -#### Development Symlink Installation +### Development Installation -During development, use the repository script to install SLDD skills as symbolic links instead of copying them: +During local development, install the `sldd` skill as a symbolic link: ```bash ./install-sldd-skills.sh ``` -This is useful when editing the skills locally because changes made under `skills/` are immediately visible to tools that read from `$HOME/.agents/skills`. +To install the symlink into a different skills directory, pass `--target`: + +```bash +./install-sldd-skills.sh --target ~/.claude/skills +``` -After changing a skill, reload or restart the CLI/tool that consumes the skills so it refreshes the loaded skill instructions. The symbolic link updates the file location, but the tool may cache skill content for the current session. +To install a copy instead of a symbolic link, pass `--copy`: + +```bash +./install-sldd-skills.sh --copy +``` + +Copied files do not reflect later repository edits until the script is run again. The script: -- uses `skills/` in this repository as the source directory; -- creates `$HOME/.agents/skills` if it does not exist; -- removes previous `sldd-*` symbolic links from `$HOME/.agents/skills`; -- removes previous real `sldd-*` directories from `$HOME/.agents/skills`; -- skips non-directory files that match `sldd-*`; -- creates one symbolic link per `skills/sldd-*` directory; -- prints a summary with removed links, removed directories, skipped files, and created links. +- uses `skills/sldd` as the source skill; +- uses `$HOME/.agents/skills` as the default target; +- accepts `--target ` for a custom target directory; +- accepts `--copy` to copy skill files instead of creating a symbolic link; +- creates the selected target directory if it does not exist; +- removes previous `sldd` and legacy `sldd-*` entries from the selected target directory; +- creates one symbolic link or copied directory at `/sldd`; +- prints a summary of removed entries and created links or copies. -Symbolic links are removed as links only. The script does not delete the files or directories that those links point to. +After changing the skill, reload or restart the CLI/tool that consumes skills so it refreshes loaded instructions. -Use this only for local development. For published or end-user installation, prefer the Skills CLI or the manual copy instructions above. +## Skill Architecture -#### For Other AI Tools +SLDD is distributed as one executable skill: -These skills are plain Markdown files with YAML frontmatter. They can be adapted to any AI tool that supports: -- System prompts or instructions -- Reusable prompt templates -- Agent/skill workflows +```text +skills/sldd/ + SKILL.md + steps/ + templates/ + schema/ +``` -## The Process Flow +`SKILL.md` is the workflow router. It resolves the current SLDD workflow, validates gates, interprets natural language or slash-style commands, and loads only the step file needed for the next action. + +The skill uses progressive disclosure: -Run one skill at a time. Review and approve the output before moving to the next step. +- `SKILL.md` contains global routing, storage, journal, and gate rules. +- `steps/` contains step-specific behavior, gates, approval protocol, save flow, and response format. +- `templates/` contains Markdown artifact formats. +- `schema/` contains the `_spec-journal.json` contract. -All executable skills are standalone at runtime. They do not depend on shared helper skills or a separate Step 88 protocol being loaded for gates, approvals, save behavior, or artifact headings. +## Managed Spec Storage + +New SLDD workflows store versioned artifacts under: + +```text +.sldd/specs// + _spec-journal.json + 00-exploration-summary.md + 01-product-intent-specification.md + 02-high-level-technical-design.md + 03-low-level-design-and-version-policy.md + 06-verification-and-feedback-report.md + existing-codebase-understanding.md +``` + +`.sldd/specs` is intended to be committed to Git and reviewed with the code changes it governs. + +`_spec-journal.json` is the canonical progress journal for new workflows. It records only workflow state, artifact links, evidence, and rerun notes. It must not contain step body content, command logs, or implementation reports. + +Allowed journal statuses: + +- `pending` +- `complete` +- `requires_rerun` + +Step 04 uses `status: "complete"` with `evidence: "red_confirmed"`. +Step 05 uses `status: "complete"` with `evidence: "green_confirmed"`. +When Step 04 or Step 05 is not complete, `evidence` must be omitted or `null`. +Step 99 uses `status: "complete"` only when `existing-codebase-understanding.md` is approved and saved. + +Legacy workflows using `docs/specs//SPEC.md` remain readable for resume compatibility. When the skill resumes a legacy workflow, it keeps writing in that legacy directory unless the user explicitly asks to migrate. + +## The Process Flow + +Use `/sldd` to start, inspect, or resume the workflow. The skill routes to the next valid step after checking the journal and prerequisites. ```text +----------------------------------------------------------------+ | SLDD Process Flow | +----------------------------------------------------------------+ | | -| Optional: sldd-88-spec-exploration-and-clarification | +| Optional Step 88: Exploration | | Clarify a rough idea before formal Step 01 | -| For brownfield work, may route to Step 99 when codebase | -| context is needed for exploration | | | | v | -| Start: sldd-00-process-overview-and-navigation-guide | -| Understand the process and choose the right skill | +| Step 00: Navigation | +| Resolve journal, validate state, and route | | | | v | -| Step 01: sldd-01-product-intent-specification | +| Step 01: Product Intent | | Define problem, users, metrics, risks, and acceptance criteria | | | | v | | Optional Step 99: Existing Codebase Understanding | -| Required for existing codebases before Step 02; may run during | -| exploration and be reused after resume validation | +| Required for existing codebases before Step 02 | | | | v | -| Step 02: sldd-02-high-level-technical-design | +| Step 02: High-Level Technical Design | | Architecture, system boundaries, and data flow | | | | v | -| Step 03: sldd-03-low-level-design-and-version-policy | -| API contracts, data models, and version policy | +| Step 03: Low-Level Design and Version Policy | +| API contracts, data models, tests, dependencies, and versions | | | | v | | GATE: Design Review | | | | v | -| Step 04: sldd-04-tests-first-driven-by-acceptance-criteria | -| Write tests only in Red phase; no production code | +| Step 04: Tests-First Red Phase | +| Write tests only and prove expected failure | | | | v | -| Step 05: sldd-05-minimal-implementation-to-pass-existing-tests | -| Minimal production changes to pass tests while preserving | -| repository rules | +| Step 05: Minimal Green Implementation | +| Minimal production changes to pass Step 04 tests | | | | v | -| Step 06: sldd-06-verification-and-feedback-report | +| Step 06: Verification | | Audit implementation and make Go/No-Go decision | | | | v | @@ -157,128 +192,174 @@ All executable skills are standalone at runtime. They do not depend on shared he ### Gate Rule -**No implementation prompts (steps 04-05) before intent and design (steps 01-03) are reviewed and approved.** - -For brownfield projects, `sldd-99-existing-codebase-understanding-and-context-summary` is required before Step 02. It may run during Step 88 exploration when understanding the current codebase is necessary to clarify scope, constraints, risks, or alternatives. A Step 99 completed during exploration can be reused later only after the agent validates that it still reflects the current codebase and remains relevant to the approved Step 01 scope. +**No implementation before intent and design are reviewed and approved.** -Step 04 and Step 05 may execute directly when the approved artifacts make the scope clear. Step 04 must stay Red-only. Step 05 must implement only the minimum production changes required to pass Step 04 tests, must not modify tests, and must inspect and follow applicable repository instructions and agentic instructions present in context. +Step 04 must stay Red-only. Step 05 must implement only the minimum production changes required to pass Step 04 tests, must not modify Step 04 tests, and must inspect and follow applicable repository or context-provided agent instructions. If a gap appears at any step, loop back to the earlier step and revise. -## Skills Included +## Steps Included + +| Step | File | Description | +|---|---|---| +| 88 | `steps/88-exploration.md` | Clarify rough ideas before formal Step 01 | +| 00 | `steps/00-navigation.md` | Resolve journal state and route to the next valid step | +| 01 | `steps/01-product-intent.md` | Define product intent and acceptance criteria | +| 99 | `steps/99-codebase-context.md` | Capture existing-codebase context for brownfield work | +| 02 | `steps/02-high-level-design.md` | Define architecture, responsibilities, data flow, and test map | +| 03 | `steps/03-low-level-design.md` | Define contracts, models, error model, tests, dependencies, and version policy | +| 04 | `steps/04-tests-red.md` | Write tests first and confirm Red | +| 05 | `steps/05-implementation-green.md` | Implement minimal production changes and confirm Green | +| 06 | `steps/06-verification.md` | Audit compliance and produce Go/No-Go decision | + +## Commands -The `skills/` directory contains executable runtime skills only. Non-runtime shared helper/reference skills are intentionally not kept under `skills/`. +When slash-style commands are passed to the skill as text, the `sldd` skill interprets them as workflow commands: -| Step | Skill | Description | -|------|-------|-------------| -| 88 | `sldd-88-spec-exploration-and-clarification` | Clarify rough ideas before formal Step 01 | -| 00 | `sldd-00-process-overview-and-navigation-guide` | Navigate the SLDD process and choose the correct skill | -| 01 | `sldd-01-product-intent-specification` | Define problem, users, metrics, risks, acceptance criteria | -| 02 | `sldd-02-high-level-technical-design` | Architecture diagram, component responsibilities, data flow | -| 03 | `sldd-03-low-level-design-and-version-policy` | API contracts, data models, error handling, version policy | -| 04 | `sldd-04-tests-first-driven-by-acceptance-criteria` | Write tests first in strict TDD mode | -| 05 | `sldd-05-minimal-implementation-to-pass-existing-tests` | Minimal code to make tests pass while preserving repository and agent instructions | -| 06 | `sldd-06-verification-and-feedback-report` | Audit implementation, compliance matrix, go/no-go decision | -| 99 | `sldd-99-existing-codebase-understanding-and-context-summary` | Read and summarize existing codebase for brownfield exploration and Step 02 readiness | +```text +/sldd +/sldd help +/sldd status +/sldd start +/sldd resume +/sldd resume +/sldd continue +/sldd run step +/sldd run step +/sldd step +/sldd explore [idea] +``` + +Slash commands are convenience syntax only. They do not bypass gates. For example, `/sldd run step 05 user-auth`, `/sldd run step 05`, and `/sldd step 05` still require Step 01, Step 02, Step 03, and Step 04 Red confirmation. + +`/sldd explore [idea]` starts Step 88 exploration. When idea text is provided inline, the skill treats it as the initial exploration seed, establishes lightweight project context, inspects the repository instead of asking questions the codebase can answer, then asks one focused clarification question at a time with a recommended answer or default assumption. Exploration stays pre-Step-01 until the user explicitly chooses to formalize, save an optional summary, route to Step 99, or stop without saving. + +`/sldd run step ` requests a specific step for a specific workflow. `/sldd run step ` is allowed when the workflow can be resolved unambiguously. `/sldd step ` is an alias for the same behavior. + +When the requested step is already complete, the skill stops before loading the step and asks whether to run it again only, run it again and mark later completed steps as `requires_rerun`, or do nothing. The run-again-only option is an explicit user override and records a journal-only note if the target step changes without downstream invalidation. + +All choices still enforce the target step's gates, approval protocol, save flow, and Red/Green contracts. + +`/sldd help` is informational only. It explains the skill, the gated flow, `.sldd/specs` storage, `_spec-journal.json`, legacy `SPEC.md` resume compatibility, and available commands without creating or changing workflow state. ## Usage -### Starting a New Feature +### Exploring an Idea -1. If the idea is still rough, use `sldd-88-spec-exploration-and-clarification`. -2. Begin or resume with `sldd-00-process-overview-and-navigation-guide` to choose the correct next skill. -3. Run `sldd-01-product-intent-specification` to define product intent. -4. For existing codebases: run `sldd-99-existing-codebase-understanding-and-context-summary` before Step 02, or earlier during exploration if codebase context is needed to clarify the feature. -5. Follow steps 02-06 in sequence. -6. Review each step output before proceeding. Artifact-producing steps require explicit approval before persistence; execution steps 04-05 may run directly only when their approved inputs, commands, and scope are clear. +```text +/sldd explore Add a lightweight onboarding checklist for new project contributors. +``` -### For Existing Codebases +The skill starts an interview from the inline idea, establishes project context first, and asks targeted questions one at a time to clarify the target outcome. Each question includes a recommended answer or default assumption. If the current repository can answer a question, the skill inspects it instead of asking. The skill offers explicit exits: continue exploring, formalize Step 01, save an optional `00-exploration-summary.md` after approval, route to Step 99 when reusable codebase context is needed, or stop without saving. + +### Starting a New Feature -Run `sldd-99-existing-codebase-understanding-and-context-summary` to ground exploration and design decisions in the current architecture. If exploration depends on codebase details, Step 99 may be run before formalizing Step 01. If Step 99 was completed during exploration, `sldd-00-process-overview-and-navigation-guide` should validate freshness and relevance before reusing it for Step 02. +```text +/sldd start user-auth -If the saved Step 99 context is stale, incomplete, scoped to a rejected exploration direction, or marked as requiring rerun on resume, update or rerun Step 99 before proceeding to `sldd-02-high-level-technical-design`. +Feature idea: Build a user authentication system with email/password and OAuth providers. +``` -### For Greenfield Projects +The skill creates or resolves `.sldd/specs/user-auth/_spec-journal.json`, loads the next required step, and asks for the approvals required by that step. -Skip sldd-99 and proceed directly from sldd-01 to sldd-02. +### Getting Help -### Example Invocation +```text +/sldd help +``` -When using an AI tool that supports skills: +The skill explains the SLDD workflow and command interface without loading a step or mutating any journal. +### Resuming Work + +```text +/sldd resume user-auth ``` -/sldd-01-product-intent-specification -Feature idea: Build a user authentication system with email/password and OAuth providers (Google, GitHub) +The skill reads `_spec-journal.json`, verifies referenced artifacts, re-checks Step 04/05 operational state when relevant, and loads only the next valid step file. + +### Requesting a Specific Step + +```text +/sldd run step 04 user-auth ``` -The skill will guide the AI to produce a structured product intent specification. +The skill validates all prerequisites before loading Step 04. If prerequisites are missing, it blocks and routes to the required earlier step. `/sldd run step 04` and `/sldd step 04` are accepted when the workflow can be resolved unambiguously. + +If Step 04 is already complete, the skill asks whether to run it again only, run it again and invalidate later completed steps, or do nothing. + +### Existing Codebases + +For brownfield work, Step 99 is required before Step 02. Step 99 may run during exploration when codebase understanding is needed to clarify scope, constraints, risks, or alternatives. + +A Step 99 completed during exploration can be reused later only after the skill validates that its saved artifact still reflects the current codebase and remains relevant to the approved Step 01 scope. + +Conversational or unsaved codebase context does not satisfy the Step 99 brownfield gate. To proceed to Step 02+, Step 99 must be approved, saved as `existing-codebase-understanding.md`, and marked `complete` in `_spec-journal.json`. + +### Greenfield Projects + +Skip Step 99 and proceed from Step 01 to Step 02. ## Key Principles ### 1. Vibe Coding + Specs-Driven = Production Ready -- **Vibe coding**: Excellent for discovery and fast prototypes -- **Specs-driven**: Essential for production decisions -- **The winning model**: Both, in sequence +- **Vibe coding**: useful for discovery and fast prototypes. +- **Specs-driven**: essential for production decisions. +- **The winning model**: both, in sequence. ### 2. Decision Framework | Context | Approach | -|---------|----------| +|---|---| | Early discovery | Vibe coding first | | User-facing in production | Specs-driven loop first | | Migration or platform work | Include explicit version checks | ### 3. The Engineer's Role -The role shifts from writing every line to **orchestrating and validating**: -- Define intent and constraints -- Review architecture decisions -- Verify correctness -- Own what gets committed +The role shifts from writing every line to orchestrating and validating: + +- Define intent and constraints. +- Review architecture decisions. +- Verify correctness. +- Own what gets committed. ### 4. TDD Throughout -Tests are written **before** implementation: -- Unit tests for logic -- Integration tests for data boundaries -- E2E tests for user-visible flows +Tests are written before implementation: + +- Unit tests for logic. +- Integration tests for data boundaries. +- E2E tests for user-visible flows. ## Benefits | Before SLDD | After SLDD | -|-------------|------------| +|---|---| | Version drift discovered late | Version policy enforced upfront | -| Missing non-functional requirements | Security, observability designed in | +| Missing non-functional requirements | Security and observability designed in | | Scope creep from unclear acceptance criteria | Explicit Given/When/Then criteria | | Expensive rework after release | Gaps caught during design | | Unreliable estimates | Structured decomposition enables accurate estimates | ## Team Working Agreement -A lightweight process to adopt: - -1. No implementation prompts before intent + design are approved -2. Every AI-generated project includes a version validation step -3. Architecture changes during coding require a design delta note -4. PRs include a spec compliance checklist -5. Release readiness requires explicit support-lifecycle verification - -## Skill Architecture and Maintenance +1. No implementation prompts before intent and design are approved. +2. Every AI-generated project includes a version validation step. +3. Architecture changes during coding require a design delta note. +4. PRs include a spec compliance checklist. +5. Release readiness requires explicit support-lifecycle verification. -This repository keeps the runtime model simple: +## Maintenance Rules -- `skills/` contains only executable skills. -- Each executable `SKILL.md` is self-sufficient at runtime. -- Do not add shared runtime helper skills for gates, approvals, save decisions, or artifact headings. -- If a rule is needed at execution time, include it directly in the executable skill that needs it. -- If the SLDD process changes, update the affected executable skills and this README in the same change. -- Preserve YAML frontmatter with `name`, `description`, `metadata.step`, and `metadata.type`. -- Preserve gate enforcement, explicit approval before persistence, and `SPEC.md` journal-only behavior. -- Keep `00-exploration-summary.md` contextual only; approved numbered artifacts define binding decisions. -- Keep Step 04 tests-first and Red-only before Step 05. -- Keep Step 05 implementation minimal, do not modify Step 04 tests, and preserve repository or context-provided agent instructions during implementation. +- Keep `skills/sldd/SKILL.md` as the only executable SLDD skill entrypoint. +- Keep step behavior in `skills/sldd/steps/`. +- Keep artifact formats in `skills/sldd/templates/`. +- Keep `_spec-journal.json` structure in `skills/sldd/schema/`. +- If SLDD process behavior, sequencing, gates, approval semantics, commands, journal fields, storage, templates, installer options, or step responsibilities change, update this README in the same change. +- Preserve Step 04 Red-only and Step 05 Green-only contracts. +- Preserve legacy `docs/specs//SPEC.md` resume compatibility until explicitly removed. ## Further Reading @@ -299,9 +380,9 @@ This skills implementation is provided for community use. ## Contributing -Contributions are welcome! Please feel free to submit issues or pull requests to improve the skills, add examples, or enhance documentation. +Contributions are welcome. Please submit issues or pull requests to improve the skill, templates, schema, examples, or documentation. ## Acknowledgments -- **Loiane Groner** for creating and sharing the SLDD methodology -- The broader AI-assisted development community for advancing responsible AI coding practices +- Loiane Groner for creating and sharing the SLDD methodology. +- The broader AI-assisted development community for advancing responsible AI coding practices. diff --git a/install-sldd-skills.sh b/install-sldd-skills.sh index aa7be4b..1e11236 100755 --- a/install-sldd-skills.sh +++ b/install-sldd-skills.sh @@ -2,11 +2,55 @@ set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -SOURCE_DIR="$REPO_ROOT/skills" -TARGET_DIR="$HOME/.agents/skills" +SOURCE_SKILL="$REPO_ROOT/skills/sldd" +DEFAULT_TARGET_DIR="$HOME/.agents/skills" +TARGET_DIR="$DEFAULT_TARGET_DIR" +INSTALL_MODE="symlink" + +usage() { + cat <&2 + echo >&2 + usage >&2 + exit 2 + fi + TARGET_DIR="$2" + shift 2 + ;; + --help|-h) + usage + exit 0 + ;; + *) + echo "Error: unknown option or argument: $1" >&2 + echo >&2 + usage >&2 + exit 2 + ;; + esac +done -if [ ! -d "$SOURCE_DIR" ]; then - echo "Error: skills source directory not found: $SOURCE_DIR" >&2 +if [ ! -d "$SOURCE_SKILL" ]; then + echo "Error: SLDD skill source directory not found: $SOURCE_SKILL" >&2 echo "Place this script in the repository root before running it." >&2 exit 1 fi @@ -15,8 +59,9 @@ mkdir -p "$TARGET_DIR" echo echo "SLDD skills development install" -echo "Source: $SOURCE_DIR" +echo "Source: $SOURCE_SKILL" echo "Target: $TARGET_DIR" +echo "Mode: $INSTALL_MODE" echo echo "Cleaning previous SLDD entries" @@ -25,7 +70,7 @@ removed_links=0 removed_dirs=0 skipped_files=0 -for entry in "$TARGET_DIR"/sldd-*; do +for entry in "$TARGET_DIR"/sldd "$TARGET_DIR"/sldd-*; do [ -e "$entry" ] || [ -L "$entry" ] || continue entry_name="$(basename "$entry")" @@ -49,27 +94,32 @@ if [ "$removed_links" -eq 0 ] && [ "$removed_dirs" -eq 0 ] && [ "$skipped_files" fi echo -echo "Creating symbolic links" - -created=0 - -for skill_dir in "$SOURCE_DIR"/sldd-*; do - [ -d "$skill_dir" ] || continue - - skill_name="$(basename "$skill_dir")" - target_link="$TARGET_DIR/$skill_name" - - ln -s "$skill_dir" "$target_link" - echo " link $skill_name" - - created=$((created + 1)) -done +links_created=0 +copies_created=0 + +case "$INSTALL_MODE" in + symlink) + echo "Creating symbolic links" + target_link="$TARGET_DIR/sldd" + ln -s "$SOURCE_SKILL" "$target_link" + echo " link sldd" + links_created=1 + ;; + copy) + echo "Copying skill files" + target_copy="$TARGET_DIR/sldd" + cp -R "$SOURCE_SKILL" "$target_copy" + echo " copy sldd" + copies_created=1 + ;; +esac echo echo "Summary" echo " symlinks removed: $removed_links" echo " directories removed: $removed_dirs" echo " files skipped: $skipped_files" -echo " links created: $created" +echo " links created: $links_created" +echo " copies created: $copies_created" echo echo "Done." diff --git a/skills/sldd-00-process-overview-and-navigation-guide/SKILL.md b/skills/sldd-00-process-overview-and-navigation-guide/SKILL.md deleted file mode 100644 index f217d16..0000000 --- a/skills/sldd-00-process-overview-and-navigation-guide/SKILL.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -name: sldd-00-process-overview-and-navigation-guide -description: Start/resume SLDD, validate checklist consistency, and route to exploration or the next valid step. -metadata: - step: "00" - type: navigation ---- - -# Skill: SLDD Process Overview and Navigation Guide - -## Objective - -Determine current state, block invalid jumps, and route to the correct next step. - -## Gate Order - -Exploration -> Step 01 + Step 99 (existing codebases only; Step 99 may occur during exploration when needed) -> Step 02 -> Step 03 -> Step 04 -> Step 05 -> Step 06 - -## Artifact and Resume Rules - -- Use user-provided paths when available; otherwise default to `docs/specs//SPEC.md`. -- Treat `docs/specs//SPEC.md` as journal-only: checklist plus links or save-status notes; never write numbered step body content into it. -- Expected artifacts: - - `00-exploration-summary.md` (optional contextual memory; not a progress artifact) - - `01-product-intent-specification.md` - - `99-existing-codebase-understanding.md` (optional persisted snapshot) - - `02-high-level-technical-design.md` - - `03-low-level-design-and-version-policy.md` - - Step 04 completion marked in `docs/specs//SPEC.md` (no mandatory report artifact) - - Step 05 completion marked in `docs/specs//SPEC.md` (no mandatory report artifact) - - `06-verification-and-feedback-report.md` -- Approved numbered artifacts take precedence over `00-exploration-summary.md`. -- A Step 99 artifact approved during exploration can satisfy the existing-codebase gate if resume validation confirms it is still current and relevant to the approved Step 01 scope. -- If Step 99 was approved without a persisted artifact and `docs/specs//SPEC.md` records a rerun-on-resume note, route to Step 99 again before Step 02. -- Steps 04 and 05 change the codebase; re-evaluate their state from `docs/specs//SPEC.md`, file changes, and relevant test results. - -## Start/Resume Flow - -1. Detect jump-ahead requests and stop if prerequisites are missing. -2. Resolve target `docs/specs//SPEC.md`: - - user-provided path, or - - selected file under provided specs root, or - - default `docs/specs//SPEC.md`. -3. Read checklist and detect out-of-order completions. -4. If the spec is still being clarified, route to `sldd-88-spec-exploration-and-clarification`. -5. For existing codebases, check whether Step 99 is required, approved, and still valid: - - if missing, route to Step 99 before Step 02; - - if approved during exploration, validate freshness and relevance before reusing it; - - if stale, incomplete, or marked rerun-on-resume, route to Step 99 again. -6. If violation exists, stop and route to the missing step. -7. Route only to the next valid step skill. - -## Interrupted Execution Resume - -When resuming at Step 04 or Step 05: - -1. Inspect `docs/specs//SPEC.md` checklist. -2. Inspect current test and production file state. -3. Run or request the relevant test commands when the current Red/Green state cannot be trusted from files alone. -4. Re-evaluate Step 04 and Step 05 even if `docs/specs//SPEC.md` marks them complete. -5. Treat Step 04 as complete only when Red is confirmed or when later passing tests prove Step 05 has already advanced the workflow. -6. Treat Step 05 as complete only when relevant tests pass and Step 04 test integrity is preserved. -7. If checklist, files, and test results conflict, stop and ask for direction instead of updating progress. - -## Response Format - -1. Completed steps -2. Violations (if any) -3. Next required step + reason -4. Prompt for confirmation to continue - -## Approval Protocol - -- This navigation step does not persist numbered artifacts. -- Before routing forward, ask for explicit confirmation to continue. -- On pause or ambiguous confirmation, hold position and clarify instead of routing. - -## Credit - -Based on Loiane Groner's article: https://loiane.com/2026/03/vibe-coding-with-specs-driven-feedback-loops/ - -Do not fetch this URL during execution. All necessary content is embedded in each skill. diff --git a/skills/sldd-01-product-intent-specification/SKILL.md b/skills/sldd-01-product-intent-specification/SKILL.md deleted file mode 100644 index 095a142..0000000 --- a/skills/sldd-01-product-intent-specification/SKILL.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: sldd-01-product-intent-specification -description: Produce Step 01 intent spec with strict gate/resume checks and artifact-first save flow. -metadata: - step: "01" - type: specification ---- - -# Skill: Product Intent Specification - -## Objective - -Define and validate Step 01 product intent for downstream steps. - -## Gate + Resume Checks - -- Reject jump-ahead requests to design/tests/implementation. -- If resuming from `docs/specs//SPEC.md`, reject invalid state where later steps are complete but Step 01 is not. - -## Draft Output - -Create a draft with these required Step 01 headings: - -- Problem Statement -- Target Users -- Formalized Exploration Decisions -- Success Metrics -- Out of Scope -- Risks and Assumptions -- Acceptance Criteria (Given/When/Then) - -Use `00-exploration-summary.md` only as non-binding context for product intent, behavior, scope, risks, assumptions, and success metrics; approved numbered artifacts override it. -Use an approved Step 99 from brownfield exploration only as context for risks, assumptions, constraints, dependencies, and out-of-scope boundaries; do not import architecture or implementation observations as product requirements unless explicitly approved as Step 01 decisions. -Wait for approval. - -## Approval Protocol - -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. -- If writes are unavailable, stop and report the limitation. - -## Save Flow (after approval) - -1. Save only Step 01 content to `docs/specs//01-product-intent-specification.md`. -2. Mark Step 01 complete in journal-only `docs/specs//SPEC.md` with the artifact link. -3. Ask whether to continue to the next step or hold. - -## Response Format - -1. Gate and resume check result -2. Draft summary with required Step 01 headings -3. Approval request -4. Continue/hold prompt diff --git a/skills/sldd-02-high-level-technical-design/SKILL.md b/skills/sldd-02-high-level-technical-design/SKILL.md deleted file mode 100644 index d6a5460..0000000 --- a/skills/sldd-02-high-level-technical-design/SKILL.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -name: sldd-02-high-level-technical-design -description: Produce Step 02 high-level design after prerequisite validation and save as a numbered artifact. -metadata: - step: "02" - type: specification ---- - -# Skill: High-Level Technical Design - -## Objective - -Produce approved Step 02 high-level design aligned to Step 01, including exploration outcomes formalized into Step 01, and Step 99 when required. - -## Gate + Resume Checks - -- Require Step 01 approved. -- For existing codebases, require Step 99 approved. -- Accept a Step 99 approved during exploration only after validating that it still reflects the current codebase and applies to the approved Step 01 scope. -- Reject skip-ahead to implementation/tests. -- Reject inconsistent checklist states. - -## Draft Output - -Create a draft with these required Step 02 headings: - -- Requirements Traceability -- Architecture Diagram -- Component Responsibilities -- Data Flow -- Security and Observability Requirements -- Trade-Offs and Alternatives -- High-Level Test Scenario Map - -Use `00-exploration-summary.md` only as non-binding context for rationale, alternatives, assumptions, and candidate technical ideas; approved numbered artifacts override it. -If Step 99 was completed before Step 01, verify that its context still fits the approved Step 01 scope before drafting Step 02. If it does not, stop and route back to Step 99 for update or rerun. -Trace approved Step 01 requirements, including formalized exploration outcomes, into architecture, responsibilities, data flow, security/observability, trade-offs, and high-level test scenarios. -Wait for approval. - -## Approval Protocol - -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. -- If writes are unavailable, stop and report the limitation. - -## Save Flow (after approval) - -1. Save only Step 02 content to `docs/specs//02-high-level-technical-design.md`. -2. Mark Step 02 complete in journal-only `docs/specs//SPEC.md` with the artifact link. -3. Ask whether to continue to the next step or hold. - -## Response Format - -1. Gate and resume check result -2. Draft summary with required Step 02 headings -3. Approval request -4. Continue/hold prompt diff --git a/skills/sldd-06-verification-and-feedback-report/SKILL.md b/skills/sldd-06-verification-and-feedback-report/SKILL.md deleted file mode 100644 index 58a920a..0000000 --- a/skills/sldd-06-verification-and-feedback-report/SKILL.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -name: sldd-06-verification-and-feedback-report -description: Audit implementation against approved specs and produce final Go/No-Go decision. -metadata: - step: "06" - type: verification ---- - -# Skill: Verification and Feedback Report - -## Objective - -Produce approved Step 06 verification with explicit Go/No-Go decision. - -## Gate + Resume Checks - -- Require Steps 01-05 approved. -- For existing codebases, require Step 99 approved. -- Reject premature verification before implementation completion. -- Reject inconsistent checklist states. - -## Draft Output - -Create a draft with these required Step 06 headings: - -- Compliance Matrix -- Version and Dependency Validation -- Test Convention Compliance -- Risks by Severity -- Remediation Steps -- Go/No-Go Decision and Rationale - -Wait for approval. - -## Approval Protocol - -- Save or update artifacts only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. -- If writes are unavailable, stop and report the limitation. - -## Save Flow (after approval) - -1. Save only Step 06 report content to `docs/specs//06-verification-and-feedback-report.md`. -2. Mark Step 06 complete in journal-only `docs/specs//SPEC.md` with the artifact link. -3. Ask whether to continue to the next step or hold. - -## Response Format - -1. Gate and resume check result -2. Draft summary with required Step 06 headings -3. Approval request -4. Continue/hold prompt diff --git a/skills/sldd-88-spec-exploration-and-clarification/SKILL.md b/skills/sldd-88-spec-exploration-and-clarification/SKILL.md deleted file mode 100644 index 56a9fdc..0000000 --- a/skills/sldd-88-spec-exploration-and-clarification/SKILL.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -name: sldd-88-spec-exploration-and-clarification -description: Explore and clarify a new SLDD spec with the user before Step 01. Use when the user has a fresh idea, wants to shape requirements, scope, risks, success criteria, or wants to think through a new SLDD workflow before writing the product intent spec. -metadata: - step: "88" - type: navigation ---- - -# Skill: Spec Exploration and Clarification - -## Objective - -Help the user turn a rough idea into a clear, testable spec direction before formal SLDD Step 01 starts. - -## Gate/Route Rules - -- Keep exploration pre-Step-01 unless the user explicitly asks to formalize. -- Route to Step 01 when the idea is sufficiently clear. -- For existing codebases, inspect the current codebase when codebase understanding is needed to explore scope, constraints, risks, or alternatives. -- If brownfield exploration depends on reusable codebase context, route to `sldd-99-existing-codebase-understanding-and-context-summary` before formalizing Step 01. -- A Step 99 completed during exploration may satisfy the later brownfield gate only after resume validation confirms it still matches the current codebase and approved Step 01 scope. -- Optional summaries default to `docs/specs//00-exploration-summary.md` unless the user provides a path. -- `00-exploration-summary.md` is contextual memory only: it does not update `docs/specs//SPEC.md`, mark progress, or replace numbered artifacts. - -## Exploration Stance - -- Explore first, formalize later. -- Ask questions that clarify the problem, users, constraints, outcomes, risks, unknowns, and non-goals. -- Keep the conversation grounded in the actual repo and workflow when relevant. -- Use ASCII diagrams, comparison tables, and simple flow sketches when they make the shape of the problem easier to see. - -## When to Use - -Use this skill when the user: - -- Has a new feature idea and is not ready to write Step 01 yet. -- Wants help clarifying requirements, boundaries, constraints, or success criteria. -- Wants to compare possible spec directions before committing. -- Wants to explore how a new SLDD workflow should begin. -- Wants to reason about a spec in relation to an existing codebase and may need Step 99 later. - -## Exploration Flow - -1. Restate the idea in your own words. -2. Identify what is known, what is assumed, and what is missing. -3. Ask a small number of high-value questions. -4. Map the important constraints, users, and outcomes. -5. Compare candidate directions if more than one exists. -6. Call out risks, edge cases, and likely follow-up questions. -7. Decide whether the idea is ready for `sldd-01-product-intent-specification` or needs more exploration. -8. Proactively offer `00-exploration-summary.md` before Step 01 when technical design ideas, complex alternatives, or refined constraints should be preserved for Step 02/03. - -## Ground Rules - -- Do not implement features. -- Do not write code. -- Do not jump into numbered SLDD artifacts unless the user explicitly asks to formalize a decision or begin Step 01. -- Downstream Steps 02-05 may follow only exploration details incorporated into the approved numbered artifact for that decision type; approved numbered artifacts override exploration notes. -- If the discussion reveals the work depends on an existing codebase, determine whether codebase understanding is needed now for exploration or later before Step 02. -- For brownfield work, ground exploration in the current codebase when relevant, but treat codebase observations as approved Step 99 context only if Step 99 is explicitly run and approved. -- If the user wants to start the formal workflow, route them to `sldd-01-product-intent-specification`. - -## Conversation Shape - -Prefer concise but meaningful turns: - -- Current understanding -- Open questions -- Candidate directions -- Key risks -- Suggested next step - -If the shape of the problem is still unclear, keep exploring. If it is clear enough, say so and hand off to Step 01. - -## Approval Protocol - -- Exploration outputs are conversational and are not saved as numbered SLDD artifacts by default. -- Proactively offer `00-exploration-summary.md` whenever exploration produces technical design ideas, architectural choices, complex alternatives, or non-obvious constraints. -- Save `docs/specs//00-exploration-summary.md` only after explicit approval. -- If the user asks to formalize outcomes, present the proposed formalization and wait for explicit approval before persisting any artifact. -- On rejection, requested changes, hold, or ambiguous approval, do not save or route forward; clarify or wait. -- If writes are unavailable, stop and report the limitation. -- Exploration decisions are not binding requirements until explicitly formalized and approved in Step 01 as product intent, acceptance criteria, scope boundaries, risks, assumptions, or success metrics. -- Technical design ideas are non-binding; carry them forward only as context, candidate options, assumptions to validate, or alternatives for Step 02/03. -- Do not treat unresolved exploration notes, rejected alternatives, or open questions as downstream requirements. - -## Optional Exploration Summary - -When useful for resume continuity, offer a concise `00-exploration-summary.md` with: -- Current understanding -- Candidate product decisions -- Candidate technical ideas (non-binding) -- Alternatives discussed -- Open questions -- Risks and assumptions -- Suggested next SLDD step - -Use the summary only as contextual memory. Approved numbered artifacts define binding decisions: -- Step 01 defines product intent, accepted behavior, scope, risks, and success metrics. -- Step 02 defines high-level technical design. -- Step 03 defines low-level design, contracts, dependencies, and version policy. -- Step 04 defines tests derived from approved acceptance criteria and Step 03 scenarios. - -## Output Format - -1. Current understanding -2. Open questions -3. Candidate directions -4. Key risks -5. Suggested next step and routing decision, including whether Step 99 is needed now, later, or not applicable -6. **Summary Recommendation**: Explicitly state if an `00-exploration-summary.md` is recommended to preserve technical memory. diff --git a/skills/sldd-99-existing-codebase-understanding-and-context-summary/SKILL.md b/skills/sldd-99-existing-codebase-understanding-and-context-summary/SKILL.md deleted file mode 100644 index 49bd804..0000000 --- a/skills/sldd-99-existing-codebase-understanding-and-context-summary/SKILL.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: sldd-99-existing-codebase-understanding-and-context-summary -description: Capture existing-codebase context for brownfield exploration and before Step 02. -metadata: - step: "99" - type: appendix ---- - -# Skill: Existing Codebase Understanding and Context Summary - -## Objective - -Capture and approve existing-codebase context for brownfield exploration and safe Step 02+ work. - -## Gate + Resume Checks - -- Required before Step 02 for existing codebases. -- May be run during Step 88 exploration when codebase understanding is needed to clarify scope, constraints, risks, or alternatives. -- Optional for greenfield projects. -- Do not mark Step 99 complete without explicit approval. -- If resuming later, re-evaluate the current codebase before relying on any previous Step 99 summary. -- Reuse a previous Step 99 only if it still reflects the current codebase and approved Step 01 scope; update or rerun it if stale, incomplete, or scoped to a rejected exploration direction. -- Reject inconsistent checklist states where Step 02+ is complete while Step 99 is required and incomplete. - -## Draft Output - -Create a draft with these required Step 99 headings: - -- Repository Structure Overview -- Architecture Summary -- Conventions to Preserve -- Integration Points -- Risks and Unknowns -- Context to Carry Into Steps 02-06 - -Wait for approval. - -## Approval Protocol - -- Mark complete, save, or update `docs/specs//SPEC.md` only after explicit approval. -- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. -- If writes are unavailable, stop and report the limitation. - -## Save Flow (after approval) - -1. Ask whether to persist `docs/specs//99-existing-codebase-understanding.md`; saving this snapshot is optional. -2. If persistence is approved, save `docs/specs//99-existing-codebase-understanding.md`. -3. Mark Step 99 complete in journal-only `docs/specs//SPEC.md` with the saved link or a not-saved note requiring re-run on resume. -4. Ask whether to continue to the next step or hold. - -## Response Format - -1. Gate and resume check result -2. Draft summary with required Step 99 headings -3. Persistence choice (save artifact vs. approved-not-saved journal note) -4. Approval request and continue/hold prompt diff --git a/skills/sldd/SKILL.md b/skills/sldd/SKILL.md new file mode 100644 index 0000000..86fa3e0 --- /dev/null +++ b/skills/sldd/SKILL.md @@ -0,0 +1,176 @@ +--- +name: sldd +description: Start, resume, inspect, or continue SLDD spec-driven development workflows, including /sldd slash-style commands, gated intent/design/test/implementation steps, structured journals, and legacy SPEC.md compatibility. +metadata: + type: workflow +--- + +# Skill: SLDD Workflow Router + +## Objective + +Route SLDD work safely through exploration, intent, design, Red tests, Green implementation, and verification. + +## Runtime Model + +Use progressive disclosure: + +- Load this `SKILL.md` first. +- Before executing any SLDD step, read exactly one matching file from `steps/`. +- If that step produces a Markdown artifact, also read the matching file from `templates/`. +- If creating or validating a new journal, use `schema/_spec-journal.schema.json`. +- Do not execute a step from memory when its step file is available. + +## Default Storage + +New SLDD workflows use: + +`.sldd/specs//` + +The canonical journal for new workflows is: + +`.sldd/specs//_spec-journal.json` + +Markdown artifacts are stored beside the journal. + +Legacy workflows using `docs/specs//SPEC.md` remain readable for resume only. When resuming a legacy workflow, keep writing in the legacy directory unless the user explicitly requests migration. + +## Journal Contract + +Use `_spec-journal.json` as journal-only state. It records progress, artifact links, evidence, and rerun notes. It must not contain numbered artifact body content, command logs, or implementation reports. + +Allowed step statuses: + +- `pending` +- `complete` +- `requires_rerun` + +Step 04 completion requires `evidence: "red_confirmed"`. +Step 05 completion requires `evidence: "green_confirmed"`. +For Step 04 and Step 05, non-complete statuses must omit `evidence` or set it to `null`. + +## Command Interface + +If slash-style commands reach this skill as text, interpret them as SLDD commands: + +- `/sldd help`: explain the SLDD skill, gated workflow, managed storage, journal, legacy compatibility, and available commands. +- `/sldd` or `/sldd status`: inspect available specs and route to the next valid step. +- `/sldd start `: start a new workflow under `.sldd/specs//`. +- `/sldd resume `: resume a specific workflow. +- `/sldd resume`: resume the only active workflow, or ask the user to choose when there are multiple. +- `/sldd continue`: continue the last clear workflow if it can be identified. +- `/sldd run step `: request a specific step for a specific workflow after gate validation. +- `/sldd run step `: request a specific step in the resolved workflow when the workflow is unambiguous. +- `/sldd step `: alias for `/sldd run step `. +- `/sldd explore [idea]`: load Step 88 exploration. If idea text follows the command, use it as the initial exploration seed. + +Slash commands are convenience syntax only. Always enforce the same gates, journal checks, approvals, and resume rules as natural-language requests. + +For `/sldd explore [idea]`: + +1. Load Step 88 without creating or mutating journals, workflow state, or artifacts by default. +2. If an inline idea is provided, treat the text after `/sldd explore` as the initial exploration seed. +3. If no idea is provided, ask the user for the rough idea before continuing. +4. Establish lightweight project context before asking idea-specific clarification questions. +5. If a context or clarification question can be answered by read-only repository inspection, inspect the repository instead of asking the user. +6. Ask one focused clarification question at a time, provide a recommended answer or default assumption, and ask the user to accept, revise, or reject it. +7. Keep exploration conversational until the user explicitly chooses to formalize, save an optional exploration summary, route to Step 99, or stop. +8. Do not route to Step 01, route to Step 99, or save `00-exploration-summary.md` without explicit user approval. + +For `/sldd run step `, `/sldd run step `, and the `/sldd step ` alias: + +1. Require a valid step id. If it is missing or invalid, stop and ask for correction. +2. Resolve the workflow from the feature argument, user input, current context, or the only active workflow. If the workflow is ambiguous, ask the user to choose. +3. Validate prerequisites, referenced artifacts, Step 99 freshness when applicable, and Step 04/Step 05 evidence before loading the target step. +4. If prerequisites are missing or stale, stop and route to the missing prerequisite instead of loading the requested step. +5. If the target step is `pending`, load the requested step file only when its gates are satisfied. +6. If the target step is `requires_rerun`, load the requested step file only when its gates are satisfied. After it completes through its normal approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. +7. If the target step is `complete`, stop before loading the step and ask the user to choose: + - `1. Run it again only.` Warn that later completed steps will not be marked `requires_rerun`; use only when the user accepts downstream consistency risk. + - `2. Run it again and mark later completed steps as requires_rerun.` + - `3. Do nothing.` +8. For option 1, run the step only after explicit confirmation. Do not automatically invalidate later steps. If the target step artifact, files, or journal entry changes, add a journal-only note that Step `` was run again without downstream invalidation by explicit user choice. +9. For option 2, run the step only after explicit confirmation. After the target step completes through its normal approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. +10. For each invalidated later step, set `reason` to `Step was run again; this later step must be reviewed again.` +11. When invalidating Step 04 or Step 05, clear its `evidence`; keep any existing `artifact` link as a historical reference. + +All completed-step choices remain subject to the target step's gate checks, approval protocol, save flow, and hard Red/Green contracts. + +`/sldd help` is informational only. It must not load a step file, create or mutate `_spec-journal.json`, route workflow state, inspect repositories, or write artifacts unless the user separately asks for status, resume, or a specific step. + +When responding to `/sldd help`, summarize: + +- what SLDD is for +- the gated step flow from exploration through verification +- `.sldd/specs//` managed storage +- `_spec-journal.json` as the canonical journal for new workflows +- legacy `docs/specs//SPEC.md` resume compatibility +- available slash-style commands +- the fact that commands do not bypass gates + +## Gate Order + +Exploration -> Step 01 + Step 99 when needed -> Step 02 -> Step 03 -> Step 04 -> Step 05 -> Step 06 + +Step 99 is required before Step 02 for existing codebases. It may run during exploration when codebase context is needed. +Step 99 completion requires an approved and saved `existing-codebase-understanding.md` artifact. + +## Resume Rules + +When resuming: + +1. Resolve the feature and journal path from user input, current context, or available specs. +2. Prefer `.sldd/specs//_spec-journal.json`. +3. If no new journal exists, allow legacy resume from `docs/specs//SPEC.md`. +4. Validate that referenced Markdown artifacts exist. +5. Detect out-of-order completions or missing prerequisites. +6. For Step 99, validate freshness and relevance before reuse. +7. For Step 04 and Step 05, re-evaluate repository state and relevant test results before trusting the journal. +8. Load only the required step file. + +If journal, artifacts, repository state, or test results conflict, stop and ask for direction before writing or routing forward. + +## Step File Map + +| Step | File | Purpose | +|---|---|---| +| 88 | `steps/88-exploration.md` | Explore rough ideas before Step 01 | +| 00 | `steps/00-navigation.md` | Inspect state and route | +| 01 | `steps/01-product-intent.md` | Product intent and acceptance criteria | +| 99 | `steps/99-codebase-context.md` | Existing-codebase context | +| 02 | `steps/02-high-level-design.md` | High-level technical design | +| 03 | `steps/03-low-level-design.md` | Low-level design and version policy | +| 04 | `steps/04-tests-red.md` | Tests-first Red phase | +| 05 | `steps/05-implementation-green.md` | Minimal Green implementation | +| 06 | `steps/06-verification.md` | Verification and Go/No-Go | + +## Template Map + +| Artifact | Template | +|---|---| +| `00-exploration-summary.md` | `templates/00-exploration-summary.md` | +| `01-product-intent-specification.md` | `templates/01-product-intent-specification.md` | +| `existing-codebase-understanding.md` | `templates/existing-codebase-understanding.md` | +| `02-high-level-technical-design.md` | `templates/02-high-level-technical-design.md` | +| `03-low-level-design-and-version-policy.md` | `templates/03-low-level-design-and-version-policy.md` | +| `06-verification-and-feedback-report.md` | `templates/06-verification-and-feedback-report.md` | + +## Global Gate Rule + +No implementation prompts or code changes before Step 01, Step 02, and Step 03 are approved. For existing codebases, Step 99 must also be complete and current before Step 02. + +Step 04 must stay Red-only. Step 05 must make the minimum production changes needed to pass Step 04 tests, must not modify Step 04 tests, and must follow applicable repository or context-provided agent instructions. + +## Response Format + +1. Resolved workflow and journal +2. Completed steps and validation result +3. Violations or conflicts, if any +4. Loaded step file and reason +5. Next action or approval request + +## Credit + +Based on Loiane Groner's article: https://loiane.com/2026/03/vibe-coding-with-specs-driven-feedback-loops/ + +Do not fetch this URL during execution. All necessary SLDD workflow behavior is embedded in this skill package. diff --git a/skills/sldd/schema/_spec-journal.schema.json b/skills/sldd/schema/_spec-journal.schema.json new file mode 100644 index 0000000..731a451 --- /dev/null +++ b/skills/sldd/schema/_spec-journal.schema.json @@ -0,0 +1,140 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://soujava.github.io/sldd-skills/_spec-journal.schema.json", + "title": "SLDD Spec Journal", + "type": "object", + "additionalProperties": false, + "required": ["schema_version", "feature", "workflow", "steps"], + "properties": { + "schema_version": { + "type": "integer", + "const": 1 + }, + "feature": { + "type": "string", + "minLength": 1 + }, + "workflow": { + "type": "string", + "const": "sldd" + }, + "current_step": { + "type": "string", + "pattern": "^(00|01|02|03|04|05|06|88|99)$" + }, + "steps": { + "type": "object", + "additionalProperties": false, + "properties": { + "04": { + "$ref": "#/$defs/red_step" + }, + "05": { + "$ref": "#/$defs/green_step" + } + }, + "patternProperties": { + "^(00|01|02|03|06|88|99)$": { + "$ref": "#/$defs/step" + } + } + }, + "notes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "$defs": { + "step": { + "type": "object", + "additionalProperties": false, + "required": ["status"], + "properties": { + "status": { + "type": "string", + "enum": ["pending", "complete", "requires_rerun"] + }, + "artifact": { + "type": ["string", "null"] + }, + "evidence": { + "type": ["string", "null"], + "enum": ["red_confirmed", "green_confirmed", null] + }, + "reason": { + "type": ["string", "null"] + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "red_step": { + "allOf": [ + { + "$ref": "#/$defs/step" + }, + { + "if": { + "required": ["status"], + "properties": { + "status": { + "const": "complete" + } + } + }, + "then": { + "required": ["evidence"], + "properties": { + "evidence": { + "const": "red_confirmed" + } + } + }, + "else": { + "properties": { + "evidence": { + "type": "null" + } + } + } + } + ] + }, + "green_step": { + "allOf": [ + { + "$ref": "#/$defs/step" + }, + { + "if": { + "required": ["status"], + "properties": { + "status": { + "const": "complete" + } + } + }, + "then": { + "required": ["evidence"], + "properties": { + "evidence": { + "const": "green_confirmed" + } + } + }, + "else": { + "properties": { + "evidence": { + "type": "null" + } + } + } + } + ] + } + } +} diff --git a/skills/sldd/steps/00-navigation.md b/skills/sldd/steps/00-navigation.md new file mode 100644 index 0000000..650ef85 --- /dev/null +++ b/skills/sldd/steps/00-navigation.md @@ -0,0 +1,107 @@ +# Step 00: Process Overview and Navigation + +## Objective + +Determine current state, block invalid jumps, and route to the correct next step. + +## Artifact and Resume Rules + +- Use user-provided paths when available. +- For new workflows, default to `.sldd/specs//_spec-journal.json`. +- Treat `_spec-journal.json` as journal-only: progress, artifact links, evidence, and rerun notes only. +- Never write numbered step body content, logs, or reports into `_spec-journal.json`. +- Legacy `docs/specs//SPEC.md` is readable for resume compatibility only. +- When resuming a legacy `SPEC.md`, continue in the legacy directory unless migration is explicitly requested. + +Expected new-workflow artifacts: + +- `00-exploration-summary.md` (optional contextual memory; not a progress artifact) +- `01-product-intent-specification.md` +- `existing-codebase-understanding.md` (required persisted snapshot for brownfield Step 02+ gates) +- `02-high-level-technical-design.md` +- `03-low-level-design-and-version-policy.md` +- Step 04 completion in `_spec-journal.json` with `evidence: "red_confirmed"` +- Step 05 completion in `_spec-journal.json` with `evidence: "green_confirmed"` +- `06-verification-and-feedback-report.md` + +Approved numbered artifacts take precedence over `00-exploration-summary.md`. + +## Start/Resume Flow + +1. Parse natural-language intent or slash-style command. +2. Detect jump-ahead requests and stop if prerequisites are missing. +3. Resolve target journal: + - user-provided path, or + - `.sldd/specs//_spec-journal.json`, or + - legacy `docs/specs//SPEC.md`. +4. Read journal state and validate referenced artifacts. +5. Detect out-of-order completions. +6. If the spec is still being clarified, route to Step 88. +7. For existing codebases, check whether Step 99 is required, complete, and still valid. +8. If any violation exists, stop and route to the missing step. +9. Route only to the next valid step file. + +## Specific Step Run Flow + +When the command is `/sldd run step `, `/sldd run step `, or the `/sldd step ` alias: + +1. Treat it as a gated targeted step request. +2. Require ``. If the value is missing, malformed, or does not resolve to a supported step, stop and ask for correction. +3. Resolve the target workflow from the feature argument, user input, current context, or the only active workflow. If multiple workflows are possible, stop and ask the user to choose. +4. Read journal state and validate all referenced artifacts before loading the target step. +5. Validate all prerequisites for the requested step exactly as that step requires. +6. For existing codebases and requested steps after Step 99, block the request if Step 99 is required but missing, incomplete, stale, or scoped to a rejected direction. +7. For Step 04 and Step 05 requests, re-evaluate current files and relevant test results before trusting journal evidence. +8. If prerequisite artifacts, journal order, Step 99 freshness, Step 04 evidence, or Step 05 evidence conflict, stop and report the conflict instead of loading the requested step. +9. If prerequisites are missing or stale, route to the missing prerequisite instead of loading the requested step. +10. If the target step is `pending`, load the requested step file only when its gates are satisfied. +11. If the target step is `requires_rerun`, load the requested step file only when its gates are satisfied. After it completes through its normal approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. + +If the target step is already `complete`, stop before loading the step and ask: + +```text +Step is already complete. + +1. Run it again only. + Risk: later completed steps will not be marked requires_rerun. Use this only when you accept downstream consistency risk. + +2. Run it again and mark later completed steps as requires_rerun. + +3. Do nothing. +``` + +After the user chooses: + +1. For option 1, run the step only after explicit confirmation. Do not automatically invalidate later completed steps. If the target step artifact, files, or journal entry changes, add a journal-only note: `Step was run again without downstream invalidation by explicit user choice.` +2. For option 2, run the step only after explicit confirmation. After the target step completes through its normal approval or confirmation flow, mark later completed steps in gate order as `requires_rerun`. +3. For each invalidated later step, set `reason` to `Step was run again; this later step must be reviewed again.` +4. When invalidating Step 04 or Step 05, clear `evidence`; keep any existing `artifact` link as a historical reference. +5. For option 3, do not load the step, write artifacts, run commands, or update the journal. + +All completed-step choices remain subject to the target step's gate checks, approval protocol, save flow, and hard Red/Green contracts. + +## Interrupted Execution Resume + +When resuming at Step 04 or Step 05: + +1. Inspect `_spec-journal.json` or legacy `SPEC.md`. +2. Inspect current test and production file state. +3. Run or request the relevant test commands when the current Red/Green state cannot be trusted from files alone. +4. Re-evaluate Step 04 and Step 05 even if the journal marks them complete. +5. Treat Step 04 as complete only when Red is confirmed or later passing tests prove Step 05 has already advanced the workflow. +6. Treat Step 05 as complete only when relevant tests pass and Step 04 test integrity is preserved. +7. If checklist, files, and test results conflict, stop and ask for direction before updating progress. + +## Approval Protocol + +- This navigation step does not persist numbered artifacts. +- Before routing forward, ask for explicit confirmation to continue unless the user requested direct resume, continue, or a targeted step run and the target step can execute without ambiguity. +- On pause or ambiguous confirmation, hold position and clarify instead of routing. + +## Response Format + +1. Resolved workflow and journal +2. Completed steps +3. Violations or conflicts, if any +4. Next required step + reason +5. Prompt for confirmation to continue when needed diff --git a/skills/sldd/steps/01-product-intent.md b/skills/sldd/steps/01-product-intent.md new file mode 100644 index 0000000..17a3e91 --- /dev/null +++ b/skills/sldd/steps/01-product-intent.md @@ -0,0 +1,41 @@ +# Step 01: Product Intent Specification + +## Objective + +Define and validate product intent for downstream steps. + +## Gate + Resume Checks + +- Reject jump-ahead requests to design, tests, or implementation. +- If resuming from `_spec-journal.json` or legacy `SPEC.md`, reject invalid state where later steps are complete but Step 01 is not. + +## Draft Output + +Load `templates/01-product-intent-specification.md` before drafting the artifact. + +Use `00-exploration-summary.md` only as non-binding context for product intent, behavior, scope, risks, assumptions, and success metrics. Approved numbered artifacts override it. + +Use an approved and saved Step 99 from brownfield exploration only as context for risks, assumptions, constraints, dependencies, and out-of-scope boundaries. Do not import architecture or implementation observations as product requirements unless explicitly approved as Step 01 decisions. + +Wait for approval. + +## Approval Protocol + +- Save or update artifacts only after explicit approval. +- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- If writes are unavailable, stop and report the limitation. + +## Save Flow After Approval + +1. Save only Step 01 content to the resolved workflow directory as `01-product-intent-specification.md`; for new workflows, this is `.sldd/specs//01-product-intent-specification.md`. +2. Mark Step 01 as `complete` in journal-only `_spec-journal.json` with the artifact link. +3. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. + +## Response Format + +1. Gate and resume check result +2. Draft summary with required Step 01 headings +3. Approval request +4. Continue/hold prompt diff --git a/skills/sldd/steps/02-high-level-design.md b/skills/sldd/steps/02-high-level-design.md new file mode 100644 index 0000000..5d5d306 --- /dev/null +++ b/skills/sldd/steps/02-high-level-design.md @@ -0,0 +1,46 @@ +# Step 02: High-Level Technical Design + +## Objective + +Produce approved high-level design aligned to Step 01, including exploration outcomes formalized into Step 01 and Step 99 when required. + +## Gate + Resume Checks + +- Require Step 01 complete. +- For existing codebases, require Step 99 complete and current. +- Accept a persisted Step 99 completed during exploration only after validating that it still reflects the current codebase and applies to the approved Step 01 scope. +- Reject skip-ahead to implementation/tests. +- Reject inconsistent journal states. + +## Draft Output + +Load `templates/02-high-level-technical-design.md` before drafting the artifact. + +Use `00-exploration-summary.md` only as non-binding context for rationale, alternatives, assumptions, and candidate technical ideas. Approved numbered artifacts override it. + +If Step 99 was completed before Step 01, verify that its saved context still fits the approved Step 01 scope before drafting Step 02. If it does not, stop and route back to Step 99 for update or rerun. + +Trace approved Step 01 requirements, including formalized exploration outcomes, into architecture, responsibilities, data flow, security/observability, trade-offs, and high-level test scenarios. + +Wait for approval. + +## Approval Protocol + +- Save or update artifacts only after explicit approval. +- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- If writes are unavailable, stop and report the limitation. + +## Save Flow After Approval + +1. Save only Step 02 content to the resolved workflow directory as `02-high-level-technical-design.md`; for new workflows, this is `.sldd/specs//02-high-level-technical-design.md`. +2. Mark Step 02 as `complete` in journal-only `_spec-journal.json` with the artifact link. +3. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. + +## Response Format + +1. Gate and resume check result +2. Draft summary with required Step 02 headings +3. Approval request +4. Continue/hold prompt diff --git a/skills/sldd-03-low-level-design-and-version-policy/SKILL.md b/skills/sldd/steps/03-low-level-design.md similarity index 53% rename from skills/sldd-03-low-level-design-and-version-policy/SKILL.md rename to skills/sldd/steps/03-low-level-design.md index d1bd0a0..fa003ee 100644 --- a/skills/sldd-03-low-level-design-and-version-policy/SKILL.md +++ b/skills/sldd/steps/03-low-level-design.md @@ -1,40 +1,26 @@ ---- -name: sldd-03-low-level-design-and-version-policy -description: Produce Step 03 low-level design with API contracts, data models, error model, test strategy, and version policy. -metadata: - step: "03" - type: specification ---- - -# Skill: Low-Level Design and Version Policy +# Step 03: Low-Level Design and Version Policy ## Objective -Produce approved Step 03 low-level design and version policy aligned to Step 02, tracing Step 01 requirements and Step 02 decisions to contracts, data models, errors, tests, dependencies, and implementation order. +Produce approved low-level design and version policy aligned to Step 02, tracing Step 01 requirements and Step 02 decisions to contracts, data models, errors, tests, dependencies, and implementation order. ## Gate + Resume Checks -- Require Step 01 and Step 02 approved. -- For existing codebases, require Step 99 approved. +- Require Step 01 and Step 02 complete. +- For existing codebases, require Step 99 complete and current. - Reject implementation/test generation at this step. -- Reject inconsistent checklist states. +- Reject inconsistent journal states. ## Draft Output -Create a draft with these required Step 03 headings: +Load `templates/03-low-level-design-and-version-policy.md` before drafting the artifact. -- Requirement-to-Design Traceability -- API Contracts -- Data Models -- Error Model -- Test Strategy -- Test Scenario Catalog -- Dependency and Version Policy -- Ordered Implementation Plan +Use `00-exploration-summary.md` only as non-binding context for rationale, alternatives, assumptions, and candidate technical ideas. Approved numbered artifacts override it. -Use `00-exploration-summary.md` only as non-binding context for rationale, alternatives, assumptions, and candidate technical ideas; approved numbered artifacts override it. Map Step 01 requirements and Step 02 design choices into concrete low-level decisions and an ordered implementation plan. + The draft must explicitly state: + - how each approved requirement is covered by API contracts, data models, error handling, tests, or implementation steps - which Step 02 design decisions constrain Step 04 tests and Step 05 implementation - whether the current dependency set is sufficient @@ -42,6 +28,7 @@ The draft must explicitly state: - why each dependency is needed - version pinning or compatibility constraints for each new dependency - the impact on runtime behavior, tests, and maintenance + Wait for approval. ## Approval Protocol @@ -50,12 +37,14 @@ Wait for approval. - On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. - If writes are unavailable, stop and report the limitation. -## Save Flow (after approval) +## Save Flow After Approval -1. Save only Step 03 content to `docs/specs//03-low-level-design-and-version-policy.md`. -2. Mark Step 03 complete in journal-only `docs/specs//SPEC.md` with the artifact link. +1. Save only Step 03 content to the resolved workflow directory as `03-low-level-design-and-version-policy.md`; for new workflows, this is `.sldd/specs//03-low-level-design-and-version-policy.md`. +2. Mark Step 03 as `complete` in journal-only `_spec-journal.json` with the artifact link. 3. Ask whether to continue to the next step or hold. +For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. + ## Response Format 1. Gate and resume check result diff --git a/skills/sldd-04-tests-first-driven-by-acceptance-criteria/SKILL.md b/skills/sldd/steps/04-tests-red.md similarity index 56% rename from skills/sldd-04-tests-first-driven-by-acceptance-criteria/SKILL.md rename to skills/sldd/steps/04-tests-red.md index 32113fa..85d0150 100644 --- a/skills/sldd-04-tests-first-driven-by-acceptance-criteria/SKILL.md +++ b/skills/sldd/steps/04-tests-red.md @@ -1,42 +1,36 @@ ---- -name: sldd-04-tests-first-driven-by-acceptance-criteria -description: Execute strict TDD Red phase by writing tests first and marking step completion. -metadata: - step: "04" - type: implementation ---- - -# Skill: Tests First Driven by Acceptance Criteria +# Step 04: Tests First Red Phase ## Objective -Execute Step 04 in strict Red phase by creating tests first, proving they fail, and marking Step 04 complete after Red confirmation. +Execute strict Red phase by creating tests first, proving they fail, and marking Step 04 complete after Red confirmation. ## Gate + Resume Checks -- Require Step 01, Step 02, and Step 03 approved. -- For existing codebases, require Step 99 approved. +- Require Step 01, Step 02, and Step 03 complete. +- For existing codebases, require Step 99 complete and current. - Reject skip-ahead requests to implementation. -- Reject inconsistent checklist states. -- On interrupted resume, re-evaluate `docs/specs//SPEC.md`, current files, and relevant test results before deciding whether Step 04 is pending, complete, or superseded. +- Reject inconsistent journal states. +- On interrupted resume, re-evaluate the journal, current files, and relevant test results before deciding whether Step 04 is pending, complete, or superseded. ## Interrupted Workflow Resume Rules -- Always re-evaluate Step 04 on resume, even if `docs/specs//SPEC.md` already marks Step 04 complete. +- Always re-evaluate Step 04 on resume, even if `_spec-journal.json` or legacy `SPEC.md` marks Step 04 complete. - Inspect existing test files and production changes before writing anything. - Run the relevant tests again when the current Red/Green state cannot be determined from files alone. -- If the relevant tests fail for the expected missing behavior, mark Step 04 complete in `docs/specs//SPEC.md`. -- If the relevant tests already pass, infer that Step 05 may have been partially or fully executed; route to Step 05 or Step 06 based on checklist state and current verification. -- If test changes, production changes, or checklist state are ambiguous, stop and ask for direction before modifying files or progress. +- If the relevant tests fail for the expected missing behavior, mark Step 04 complete with `status: "complete"` and `evidence: "red_confirmed"`. +- If the relevant tests already pass, infer that Step 05 may have been partially or fully executed; route to Step 05 or Step 06 based on journal state and current verification. +- If test changes, production changes, or journal state are ambiguous, stop and ask for direction before modifying files or progress. - Never revert user changes while resuming. Work with the current state. ## Strict Red-Phase Contract -- **Tests first; no production logic.** -- **Minimal Stubbing**: Create only production files and signatures strictly required for the test to compile. Do not implement full DTO or Entity suites if one stub suffices. -- **Allowed stubs**: method or function signatures and class structure only. Every stub method must immediately raise a runtime error or equivalent. No business logic, no validation logic, no placeholder return values, no delegating calls to other stubs. -- **Every Step 04 test run must fail.** -- **No Intermediate Implementation**: Do not perform any production logic changes. Production file creation is limited to the minimal stubs strictly required for tests to compile. +- Tests first; no production logic. +- Minimal stubbing: create only production files and signatures strictly required for the test to compile. +- Allowed stubs: method or function signatures and class structure only. +- Every stub method must immediately raise a runtime error or equivalent. +- No business logic, validation logic, placeholder return values, or delegating calls to other stubs. +- Every Step 04 test run must fail. +- Production file creation is limited to minimal stubs strictly required for tests to compile. ## Execution Protocol @@ -59,37 +53,43 @@ Use these required Step 04 snapshot headings: - Acceptance criteria and Step 03 test scenarios -> tests mapping - Coverage of the Step 03 Test Scenario Catalog - Traceability from approved Step 01 behavior and Step 03 test scenarios into concrete tests -- Use `00-exploration-summary.md` only as non-binding context; do not create tests from summary-only decisions. -- At least one approved or directly implied edge case per criterion; if an edge case requires new behavior or assumptions, stop and route back to Step 01 or Step 03. +- Use `00-exploration-summary.md` only as non-binding context; do not create tests from summary-only decisions +- At least one approved or directly implied edge case per criterion - Exact test commands - Failing output summary - Explicit Red confirmation +If an edge case requires new behavior or assumptions, stop and route back to Step 01 or Step 03. + ## Approval Protocol - Do not require a separate Step 04 execution approval when approved Step 01, Step 02, and Step 03 artifacts clearly define the acceptance criteria, constraints, and test scenarios. - Ask for explicit approval before writing tests or running commands only when Step 04 detects ambiguity, scope expansion, missing test scenarios, unclear commands, or non-obvious minimal stubbing needs. -- If the user requested continuous execution from Step 04 to Step 05, route directly to `sldd-05-minimal-implementation-to-pass-existing-tests` after Red confirmation without asking for another approval between the steps. +- If the user requested continuous execution from Step 04 to Step 05, route directly to Step 05 after Red confirmation without asking for another approval between the steps. - On rejection, requested changes, hold, or ambiguous approval, do not write, run, save, or route forward; clarify or wait. - If writes are unavailable, stop and report the limitation. -## Save Flow (after Red confirmation) +## Save Flow After Red Confirmation 1. Do not create a mandatory Step 04 report artifact. -2. Update `docs/specs//SPEC.md` Step 04 `[x]` only. -3. Keep `docs/specs//SPEC.md` journal-only; do not include logs, report body, or numbered artifact content. +2. Update `_spec-journal.json` Step 04 to `status: "complete"` and `evidence: "red_confirmed"`. +3. Keep `_spec-journal.json` journal-only; do not include logs, report body, or numbered artifact content. 4. If continuous Step 04 -> Step 05 execution was requested, route directly to Step 05. 5. Otherwise, ask whether to continue to the next step or hold. +For legacy or user-provided workflow paths, update progress in the resolved journal instead. + ## Response Format ### Execution Response + 1. Gate and resume check result 2. Red-phase execution snapshot -3. `docs/specs//SPEC.md` update summary +3. Journal update summary 4. Continue/hold prompt, unless continuous Step 04 -> Step 05 execution was already requested ### Blocked Response + 1. Gate and resume check result 2. Reason Step 04 cannot execute directly 3. Required clarification, approval, or route back to Step 01 or Step 03 diff --git a/skills/sldd-05-minimal-implementation-to-pass-existing-tests/SKILL.md b/skills/sldd/steps/05-implementation-green.md similarity index 72% rename from skills/sldd-05-minimal-implementation-to-pass-existing-tests/SKILL.md rename to skills/sldd/steps/05-implementation-green.md index be37916..d8c7272 100644 --- a/skills/sldd-05-minimal-implementation-to-pass-existing-tests/SKILL.md +++ b/skills/sldd/steps/05-implementation-green.md @@ -1,37 +1,29 @@ ---- -name: sldd-05-minimal-implementation-to-pass-existing-tests -description: Implement minimal production changes to pass Step 04 tests and mark step completion. -metadata: - step: "05" - type: implementation ---- - -# Skill: Minimal Implementation to Pass Existing Tests +# Step 05: Minimal Green Implementation ## Objective -Implement the minimum production changes required to pass Step 04 tests without modifying tests, respecting approved Step 03 constraints, Step 01 requirements, repository instructions, and agentic instructions present in context, then mark Step 05 complete after Green confirmation. +Implement the minimum production changes required to pass Step 04 tests without modifying tests, respecting approved Step 03 constraints, Step 01 requirements, repository instructions, and agentic instructions present in context. Mark Step 05 complete after Green confirmation. ## Gate + Resume Checks -- Require Steps 01-04 approved. -- Require Step 04 completion from `docs/specs//SPEC.md`, current failing test results, or continuous handoff from Step 04. -- For existing codebases, require Step 99 approved. +- Require Steps 01-04 complete. +- Require Step 04 completion from `_spec-journal.json`, current failing test results, or continuous handoff from Step 04. +- For existing codebases, require Step 99 complete and current. - Require repository instructions and agentic instructions present in context to be inspected and followed before implementation. - Reject requests to modify tests or bypass Red/Green order. -- Reject inconsistent checklist states. -- On interrupted resume, re-evaluate `docs/specs//SPEC.md`, current files, and relevant test results before deciding whether Step 05 is pending or complete. +- Reject inconsistent journal states. +- On interrupted resume, re-evaluate the journal, current files, and relevant test results before deciding whether Step 05 is pending or complete. ## Interrupted Workflow Resume Rules -- Always re-evaluate Step 04 and Step 05 on resume, even if `docs/specs//SPEC.md` already marks one or both complete. +- Always re-evaluate Step 04 and Step 05 on resume, even if `_spec-journal.json` or legacy `SPEC.md` marks one or both complete. - Run the relevant Step 04 tests before modifying production code when the current state is not already clear. - If the tests still fail, continue with the minimal implementation required to make them pass. -- If the tests already pass and test files were not modified after Step 04 completion, mark Step 05 complete in `docs/specs//SPEC.md`. +- If the tests already pass and test files were not modified after Step 04 completion, mark Step 05 complete with `status: "complete"` and `evidence: "green_confirmed"`. - If Step 04 state is stale or ambiguous, re-run the relevant tests before implementation. - If Step 04 tests appear to have been modified after Red confirmation, stop because test integrity may be compromised. - If production implementation is partial, continue from the current state without reverting user changes. -- If checklist state, file state, or test results conflict, stop and ask for direction before modifying files or progress. +- If journal state, file state, or test results conflict, stop and ask for direction before modifying files or progress. ## Execution Protocol @@ -46,6 +38,7 @@ The execution snapshot must identify which Step 03 contracts, constraints, imple ## Execution Output Present: + - green-phase execution snapshot - confirmation that tests were not modified @@ -63,7 +56,7 @@ Use these required Step 05 snapshot headings: - Do not require a separate Step 05 execution approval when approved Step 01, Step 02, Step 03, and Step 04 artifacts clearly define the requirements, constraints, test failures, and implementation scope. - Ask for explicit approval before modifying production code or running commands only when Step 05 detects ambiguity, scope expansion, missing applicable repository or agentic instructions, unclear commands, dependency changes, or convention exceptions. -- Do not require a separate approval after Green confirmation before updating `docs/specs//SPEC.md`. +- Do not require a separate approval after Green confirmation before updating `_spec-journal.json`. - On rejection, requested changes, hold, or ambiguous approval, do not modify code, run, save, or route forward; clarify or wait. - If writes are unavailable, stop and report the limitation. @@ -72,23 +65,27 @@ Use these required Step 05 snapshot headings: - Run tests and confirm previously failing tests pass. - Record commands and results. -## Save Flow (after Green confirmation) +## Save Flow After Green Confirmation 1. Do not create a mandatory Step 05 report artifact. -2. Update `docs/specs//SPEC.md` Step 05 `[x]` only. -3. Keep `docs/specs//SPEC.md` journal-only; do not include logs, report body, or numbered artifact content. +2. Update `_spec-journal.json` Step 05 to `status: "complete"` and `evidence: "green_confirmed"`. +3. Keep `_spec-journal.json` journal-only; do not include logs, report body, or numbered artifact content. 4. Ask whether to continue to the next step or hold. +For legacy or user-provided workflow paths, update progress in the resolved journal instead. + ## Response Format ### Execution Response + 1. Gate and resume check result 2. Green-phase execution snapshot 3. Test integrity confirmation -4. `docs/specs//SPEC.md` update summary +4. Journal update summary 5. Continue/hold prompt ### Blocked Response + 1. Gate and resume check result 2. Reason Step 05 cannot execute directly 3. Required clarification, approval, or route back to Step 03 diff --git a/skills/sldd/steps/06-verification.md b/skills/sldd/steps/06-verification.md new file mode 100644 index 0000000..d6efd09 --- /dev/null +++ b/skills/sldd/steps/06-verification.md @@ -0,0 +1,41 @@ +# Step 06: Verification and Feedback Report + +## Objective + +Produce approved verification with explicit Go/No-Go decision. + +## Gate + Resume Checks + +- Require Steps 01-05 complete. +- Require Step 04 evidence `red_confirmed`. +- Require Step 05 evidence `green_confirmed`. +- For existing codebases, require Step 99 complete and current. +- Reject premature verification before implementation completion. +- Reject inconsistent journal states. + +## Draft Output + +Load `templates/06-verification-and-feedback-report.md` before drafting the artifact. + +Wait for approval. + +## Approval Protocol + +- Save or update artifacts only after explicit approval. +- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- If writes are unavailable, stop and report the limitation. + +## Save Flow After Approval + +1. Save only Step 06 report content to the resolved workflow directory as `06-verification-and-feedback-report.md`; for new workflows, this is `.sldd/specs//06-verification-and-feedback-report.md`. +2. Mark Step 06 as `complete` in journal-only `_spec-journal.json` with the artifact link. +3. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. + +## Response Format + +1. Gate and resume check result +2. Draft summary with required Step 06 headings +3. Approval request +4. Continue/hold prompt diff --git a/skills/sldd/steps/88-exploration.md b/skills/sldd/steps/88-exploration.md new file mode 100644 index 0000000..ef25264 --- /dev/null +++ b/skills/sldd/steps/88-exploration.md @@ -0,0 +1,142 @@ +# Step 88: Spec Exploration and Clarification + +## Objective + +Help the user turn a rough idea into a clear, testable spec direction before formal SLDD Step 01 starts. + +## Gate/Route Rules + +- Keep exploration pre-Step-01 unless the user explicitly asks to formalize. +- Route to Step 01 when the idea is sufficiently clear. +- When invoked as `/sldd explore `, treat `` as the initial exploration seed and begin project-context intake plus clarification immediately. +- When invoked without an idea, ask for the rough idea first. +- Establish lightweight project context before asking idea-specific clarification questions. +- For existing codebases, inspect the current codebase when codebase understanding is needed to explore scope, constraints, risks, or alternatives. +- If brownfield exploration depends on reusable codebase context, route to Step 99 before formalizing Step 01. +- A persisted Step 99 completed during exploration may satisfy the later brownfield gate only after resume validation confirms it still matches the current codebase and approved Step 01 scope. +- Optional summaries default to `.sldd/specs//00-exploration-summary.md` unless the user provides a path. +- `00-exploration-summary.md` is contextual memory only: it does not update `_spec-journal.json`, mark progress, or replace numbered artifacts. + +## Exploration Stance + +- Explore first, formalize later. +- Ask questions that clarify the problem, users, constraints, outcomes, risks, unknowns, and non-goals. +- Keep the conversation grounded in the actual repo and workflow when relevant. +- Use ASCII diagrams, comparison tables, and simple flow sketches when they make the shape of the problem easier to see. + +## Project Context Intake + +Before the clarification interview, establish enough project context to keep exploration grounded: + +- Identify the target project, workflow, or repository context when it is known. +- Determine whether the work is greenfield, brownfield, or unclear. +- Check for an existing SLDD workflow, active spec, relevant README, local instructions, or obvious project conventions when available. +- Capture the domain, users, operational constraints, non-goals, and success signals that are already known from the user's request or project materials. +- If context is missing and cannot be inferred from the current workspace, ask one focused context question before continuing. +- If a context question can be answered by read-only inspection of the repository, inspect the repository instead of asking the user. +- Treat this intake as conversational context only. It does not create a journal, satisfy Step 99, or make binding requirements. +- When reusable brownfield context is needed for later design work, offer to route to Step 99 before formalizing Step 01. + +## Inline Idea Handling + +When the user provides idea text with `/sldd explore ` or an equivalent natural-language exploration request: + +- Use the provided text as the target idea to clarify. +- Do not ask the user to repeat the same idea unless it is empty or too ambiguous to start. +- Start by combining the idea with project context, then restate the target direction in clearer terms. +- End each meaningful turn with explicit choices: continue exploring, formalize into Step 01, save an optional `00-exploration-summary.md` after approval, route to Step 99 when codebase context is needed, or stop without saving. +- Treat "stop", "pause", "exit exploration", "do not continue", or equivalent language as a request to leave exploration without saving or routing unless the user also explicitly approves persistence. + +## Clarification Interview Protocol + +Drive exploration toward shared understanding that is ready for formal SLDD Step 01: + +- Ask one focused question at a time unless the user explicitly asks for a batch. +- Follow the decision tree one dependency at a time: clarify prerequisite decisions before dependent decisions. +- For each question, provide a recommended answer or default assumption with brief rationale, then ask the user to accept, revise, or reject it. +- Prefer high-signal questions that improve Step 01 readiness over exhaustive questioning. +- If a question can be answered by read-only inspection of the current repository, inspect the repository instead of asking the user. +- Treat repository observations during Step 88 as conversational context only unless Step 99 is explicitly run, approved, and saved. +- Do not turn exploration into Step 02 or Step 03 design work; keep technical options as non-binding context until the formal workflow reaches those steps. +- Continue until the idea is clear enough to formalize, the user chooses to keep exploring, or the user exits without saving. + +## When to Use + +Use this step when the user: + +- Has a new feature idea and is not ready to write Step 01 yet. +- Wants help clarifying requirements, boundaries, constraints, or success criteria. +- Wants to compare possible spec directions before committing. +- Wants to explore how a new SLDD workflow should begin. +- Wants to reason about a spec in relation to an existing codebase and may need Step 99 later. + +## Exploration Flow + +1. Capture the inline idea seed or ask for a rough idea if none was provided. +2. Establish lightweight project context from the workspace, existing specs, repo materials, and the user's request. +3. Inspect the repository before asking any context or clarification question that the codebase can answer. +4. Restate the idea in your own words, grounded in the project context. +5. Identify what is known, what is assumed, and what is missing. +6. Ask one high-value question at a time, with a recommended answer or default assumption. +7. Map the important constraints, users, and outcomes as answers accumulate. +8. Compare candidate directions if more than one exists. +9. Call out risks, edge cases, and likely follow-up questions. +10. Decide whether the idea is ready for Step 01 or needs more exploration. +11. Proactively offer `00-exploration-summary.md` before Step 01 when technical design ideas, complex alternatives, or refined constraints should be preserved for Step 02/03. + +## Ground Rules + +- Do not implement features. +- Do not write code. +- Do not jump into numbered SLDD artifacts unless the user explicitly asks to formalize a decision or begin Step 01. +- Downstream Steps 02-05 may follow only exploration details incorporated into the approved numbered artifact for that decision type; approved numbered artifacts override exploration notes. +- If the discussion reveals the work depends on an existing codebase, determine whether codebase understanding is needed now for exploration or later before Step 02. +- For brownfield work, ground exploration in the current codebase when relevant, but treat codebase observations as approved Step 99 context only if Step 99 is explicitly run, approved, and saved. +- If the user wants to start the formal workflow, route them to Step 01. + +## Conversation Shape + +Prefer concise but meaningful turns: + +- Current understanding +- Project context +- Next question +- Candidate directions +- Key risks +- Suggested next step and exit choices + +If the shape of the problem is still unclear, keep exploring. If it is clear enough, say so and hand off to Step 01. + +## Approval Protocol + +- Exploration outputs are conversational and are not saved as numbered SLDD artifacts by default. +- Proactively offer `00-exploration-summary.md` whenever exploration produces technical design ideas, architectural choices, complex alternatives, or non-obvious constraints. +- Load `templates/00-exploration-summary.md` before drafting a persisted summary. +- Save `00-exploration-summary.md` to the resolved workflow directory only after explicit approval; for new workflows, this is `.sldd/specs//00-exploration-summary.md`. +- If the user asks to formalize outcomes, present the proposed formalization and wait for explicit approval before persisting any artifact. +- On rejection, requested changes, hold, or ambiguous approval, do not save or route forward; clarify or wait. +- When the user chooses to stop exploration, leave without saving, writing a journal, or routing forward unless a separate explicit approval says otherwise. +- If writes are unavailable, stop and report the limitation. +- Exploration decisions are not binding requirements until explicitly formalized and approved in Step 01 as product intent, acceptance criteria, scope boundaries, risks, assumptions, or success metrics. +- Technical design ideas are non-binding; carry them forward only as context, candidate options, assumptions to validate, or alternatives for Step 02/03. +- Do not treat unresolved exploration notes, rejected alternatives, or open questions as downstream requirements. + +## Optional Exploration Summary + +Use the summary only as contextual memory. Approved numbered artifacts define binding decisions: + +- Step 01 defines product intent, accepted behavior, scope, risks, and success metrics. +- Step 02 defines high-level technical design. +- Step 03 defines low-level design, contracts, dependencies, and version policy. +- Step 04 defines tests derived from approved acceptance criteria and Step 03 scenarios. + +## Output Format + +1. Current understanding +2. Project context +3. Next question, including recommended answer or default assumption +4. Candidate directions +5. Key risks +6. Suggested next step and routing decision, including whether Step 99 is needed now, later, or not applicable +7. Summary recommendation: explicitly state if an `00-exploration-summary.md` is recommended to preserve technical memory +8. Exit choices: continue exploring, formalize Step 01, save summary after approval, route to Step 99 when needed, or stop without saving diff --git a/skills/sldd/steps/99-codebase-context.md b/skills/sldd/steps/99-codebase-context.md new file mode 100644 index 0000000..6eac269 --- /dev/null +++ b/skills/sldd/steps/99-codebase-context.md @@ -0,0 +1,45 @@ +# Step 99: Existing Codebase Understanding and Context Summary + +## Objective + +Capture and approve existing-codebase context for brownfield exploration and safe Step 02+ work. + +## Gate + Resume Checks + +- Required before Step 02 for existing codebases. +- May be run during Step 88 exploration when codebase understanding is needed to clarify scope, constraints, risks, or alternatives. +- Optional for greenfield projects. +- Do not mark Step 99 complete without explicit approval and a saved `existing-codebase-understanding.md` artifact. +- Conversational or unsaved Step 99 context is non-gating context only; it does not satisfy Step 02+ brownfield prerequisites. +- If resuming later, re-evaluate the current codebase before relying on any previous Step 99 summary. +- Reuse a previous Step 99 only if it still reflects the current codebase and approved Step 01 scope; update or rerun it if stale, incomplete, or scoped to a rejected exploration direction. +- Reject inconsistent journal states where Step 02+ is complete while Step 99 is required and incomplete. + +## Draft Output + +Load `templates/existing-codebase-understanding.md` before drafting the artifact. + +Wait for approval. + +## Approval Protocol + +- Save the artifact and mark Step 99 complete in `_spec-journal.json` only after explicit approval. +- On rejection, requested changes, hold, or ambiguous approval, do not persist progress; clarify or wait. +- If writes are unavailable, stop and report the limitation. + +## Save Flow After Approval + +1. Confirm that approval includes saving `existing-codebase-understanding.md` in the resolved workflow directory. +2. If persistence is approved, save `existing-codebase-understanding.md`. +3. Mark Step 99 in journal-only `_spec-journal.json` with `status: "complete"` and the saved artifact link. +4. If persistence is not approved, do not save, do not mark Step 99 complete, and do not route to Step 02+; state that Step 99 remains incomplete until the artifact is saved and approved. +5. Ask whether to continue to the next step or hold. + +For legacy or user-provided workflow paths, save and update progress in the resolved directory instead. + +## Response Format + +1. Gate and resume check result +2. Draft summary with required Step 99 headings +3. Persistence requirement for Step 99 completion +4. Approval request and continue/hold prompt diff --git a/skills/sldd/templates/00-exploration-summary.md b/skills/sldd/templates/00-exploration-summary.md new file mode 100644 index 0000000..388991e --- /dev/null +++ b/skills/sldd/templates/00-exploration-summary.md @@ -0,0 +1,13 @@ +# Current Understanding + +# Candidate Product Decisions + +# Candidate Technical Ideas (Non-Binding) + +# Alternatives Discussed + +# Open Questions + +# Risks and Assumptions + +# Suggested Next SLDD Step diff --git a/skills/sldd/templates/01-product-intent-specification.md b/skills/sldd/templates/01-product-intent-specification.md new file mode 100644 index 0000000..514088a --- /dev/null +++ b/skills/sldd/templates/01-product-intent-specification.md @@ -0,0 +1,13 @@ +# Problem Statement + +# Target Users + +# Formalized Exploration Decisions + +# Success Metrics + +# Out of Scope + +# Risks and Assumptions + +# Acceptance Criteria (Given/When/Then) diff --git a/skills/sldd/templates/02-high-level-technical-design.md b/skills/sldd/templates/02-high-level-technical-design.md new file mode 100644 index 0000000..e94d17f --- /dev/null +++ b/skills/sldd/templates/02-high-level-technical-design.md @@ -0,0 +1,13 @@ +# Requirements Traceability + +# Architecture Diagram + +# Component Responsibilities + +# Data Flow + +# Security and Observability Requirements + +# Trade-Offs and Alternatives + +# High-Level Test Scenario Map diff --git a/skills/sldd/templates/03-low-level-design-and-version-policy.md b/skills/sldd/templates/03-low-level-design-and-version-policy.md new file mode 100644 index 0000000..a14333d --- /dev/null +++ b/skills/sldd/templates/03-low-level-design-and-version-policy.md @@ -0,0 +1,15 @@ +# Requirement-to-Design Traceability + +# API Contracts + +# Data Models + +# Error Model + +# Test Strategy + +# Test Scenario Catalog + +# Dependency and Version Policy + +# Ordered Implementation Plan diff --git a/skills/sldd/templates/06-verification-and-feedback-report.md b/skills/sldd/templates/06-verification-and-feedback-report.md new file mode 100644 index 0000000..e33d274 --- /dev/null +++ b/skills/sldd/templates/06-verification-and-feedback-report.md @@ -0,0 +1,11 @@ +# Compliance Matrix + +# Version and Dependency Validation + +# Test Convention Compliance + +# Risks by Severity + +# Remediation Steps + +# Go/No-Go Decision and Rationale diff --git a/skills/sldd/templates/existing-codebase-understanding.md b/skills/sldd/templates/existing-codebase-understanding.md new file mode 100644 index 0000000..60dbfcf --- /dev/null +++ b/skills/sldd/templates/existing-codebase-understanding.md @@ -0,0 +1,11 @@ +# Repository Structure Overview + +# Architecture Summary + +# Conventions to Preserve + +# Integration Points + +# Risks and Unknowns + +# Context to Carry Into Steps 02-06