diff --git a/.claude/skills/README.md b/.claude/skills/README.md new file mode 100644 index 0000000..fc40e69 --- /dev/null +++ b/.claude/skills/README.md @@ -0,0 +1,57 @@ +# Claude Code Skills for Spec-Driven Development + +This directory contains Agent Skills for Claude Code that implement the Spec-Driven Development (SDD) workflow. + +## Available Skills + +### sdd-1-generate-spec + +Generate a comprehensive specification for a feature with workflow guidance and scope validation. + +**When to use:** Starting a new feature or enhancement; need to transform an initial idea into a structured specification. + +### sdd-2-generate-task-list + +Convert a specification into an actionable task list with demoable units and detailed subtasks. + +**When to use:** After creating a specification; need to break down the work into implementable tasks. + +### sdd-3-manage-tasks + +Execute structured task implementation with built-in verification and progress tracking. + +**When to use:** During implementation; need guided execution with checkpoints and proof artifacts. + +### sdd-4-validate-implementation + +Validate implementation against the specification using proof artifacts and evidence-based coverage. + +**When to use:** After completing implementation; need to verify all requirements are met before shipping. + +## Installation + +These skills are designed for use with Claude Code. To install: + +```bash +# Copy to user skills directory (available in all projects) +mkdir -p ~/.claude/skills +cp -r .claude/skills/* ~/.claude/skills/ + +# Or copy to project-specific location (available only in this project) +# Skills are already in .claude/skills/ for this project +``` + +## How Skills Work + +Claude Code automatically discovers and can invoke these skills when they're relevant to your workflow. Each skill: + +- Contains YAML frontmatter with metadata (name, description, tags) +- Includes detailed instructions and context markers +- Provides workflow integration guidance +- Implements validation and quality checks + +## Learn More + +- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) +- [SDD Workflow Overview](https://github.com/liatrio-labs/spec-driven-workflow) +- [SDD Playbook](https://liatrio-labs.github.io/spec-driven-workflow/) diff --git a/.claude/skills/sdd-1-generate-spec/SKILL.md b/.claude/skills/sdd-1-generate-spec/SKILL.md new file mode 100644 index 0000000..8dabd17 --- /dev/null +++ b/.claude/skills/sdd-1-generate-spec/SKILL.md @@ -0,0 +1,365 @@ +--- +name: SDD-1-generate-spec +description: "Generate a Specification (Spec) for a feature with enhanced workflow guidance and scope validation" +tags: + - planning + - specification +arguments: [] +meta: + category: spec-development + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch +--- + +# Generate Specification + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD1️⃣ + +## You are here in the workflow + +We are at the **beginning** of the Spec-Driven Development Workflow. This is where we transform an initial idea into a detailed, actionable specification that will guide the entire development process. + +### Workflow Integration + +This spec serves as the **planning blueprint** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Idea → Spec**: Transforms initial concept into structured requirements +- **Spec → Tasks**: Provides foundation for implementation planning +- **Tasks → Implementation**: Guides structured development approach +- **Implementation → Validation**: Spec serves as acceptance criteria + +**Critical Dependencies:** + +- **User Stories** become the basis for proof artifacts in task generation +- **Functional Requirements** drive implementation task breakdown +- **Technical Considerations** inform architecture and dependency decisions +- **Demoable Units** become parent task boundaries in task generation + +**What Breaks the Chain:** + +- Vague user stories → unclear proof artifacts and task boundaries +- Missing functional requirements → gaps in implementation coverage +- Inadequate technical considerations → architectural conflicts during implementation +- Oversized specs → unmanageable task breakdown and loss of incremental progress + +## Your Role + +You are a **Senior Product Manager and Technical Lead** with extensive experience in software specification development. Your expertise includes gathering requirements, managing scope, and creating clear, actionable documentation for development teams. + +## Goal + +To create a comprehensive Specification (Spec) based on an initial user input. This spec will serve as the single source of truth for a feature. The Spec must be clear enough for a junior developer to understand and implement, while providing sufficient detail for planning and validation. + +If the user did not include an initial input or reference for the spec, ask the user to provide this input before proceeding. + +## Spec Generation Overview + +1. **Create Spec Directory** - Create `./docs/specs/[NN]-spec-[feature-name]/` directory structure +2. **Context Assessment** - Review existing codebase for relevant patterns and constraints +3. **Initial Scope Assessment** - Evaluate if the feature is appropriately sized for this workflow +4. **Clarifying Questions** - Gather detailed requirements through structured inquiry +5. **Spec Generation** - Create the detailed specification document +6. **Review and Refine** - Validate completeness and clarity with the user + +## Step 1: Create Spec Directory + +Create the spec directory structure before proceeding with any other steps. This ensures all files (questions, spec, tasks, proofs) have a consistent location. + +**Directory Structure:** + +- **Path**: `./docs/specs/[NN]-spec-[feature-name]/` where `[NN]` is a zero-padded 2-digit sequence number (e.g., `01`, `02`, `03`) +- **Naming Convention**: Use lowercase with hyphens for the feature name +- **Examples**: `01-spec-user-authentication/`, `02-spec-payment-integration/`, etc. + +**Verification**: Confirm the directory exists before proceeding to Step 2. + +## Step 2: Context Assessment + +If working in a pre-existing project, begin by briefly reviewing the codebase and existing docs to understand: + +- Current architecture patterns and conventions +- Relevant existing components or features +- Integration constraints or dependencies +- Files that might need modification or extension +- **Repository Standards and Patterns**: Identify existing coding standards, architectural patterns, and development practices from: + - Project documentation (README.md, CONTRIBUTING.md, docs/) + - AI specific documentation (AGENTS.md, CLAUDE.md) + - Configuration files (package.json, Cargo.toml, pyproject.toml, etc.) + - Existing code structure and naming conventions + - Testing patterns and quality assurance practices + - Commit message conventions and development workflows + +**Use this context to inform scope validation and requirements, not to drive technical decisions.** Focus on understanding what exists to make the spec more realistic and achievable, and ensure any implementation will follow the repository's established patterns. + +## Step 3: Initial Scope Assessment + +Evaluate whether this feature request is appropriately sized for this spec-driven workflow. + +**Chain-of-thought reasoning:** + +- Consider the complexity and scope of the requested feature +- Compare against the following examples +- Use context from Step 2 to inform the assessment +- If scope is too large, suggest breaking into smaller specs +- If scope is too small, suggest direct implementation without formal spec + +**Scope Examples:** + +**Too Large (split into multiple specs):** + +- Rewriting an entire application architecture or framework +- Migrating a complete database system to a new technology +- Refactoring multiple interconnected modules simultaneously +- Implementing a full authentication system from scratch +- Building a complete microservices architecture +- Creating an entire admin dashboard with all features +- Redesigning the entire UI/UX of an application +- Implementing a comprehensive reporting system with all widgets + +**Too Small (vibe-code directly):** + +- Adding a single console.log statement for debugging +- Changing the color of a button in CSS +- Adding a missing import statement +- Fixing a simple off-by-one error in a loop +- Updating documentation for an existing function + +**Just Right (perfect for this workflow):** + +- Adding a new CLI flag with validation and help text +- Implementing a single API endpoint with request/response validation +- Refactoring one module while maintaining backward compatibility +- Adding a new component with integration to existing state management +- Creating a single database migration with rollback capability +- Implementing one user story with complete end-to-end flow + +### Report Scope Assessment To User + +- **ALWAYS** inform the user of the result of the scope assessment. +- If the scope appears inappropriate, **ALWAYS** pause the conversation to suggest alternatives and get input from the user. + +## Step 4: Clarifying Questions + +Ask clarifying questions to gather sufficient detail. Focus on understanding the "what" and "why" rather than the "how." + +Use the following common areas to guide your questions: + +**Core Understanding:** + +- What problem does this solve and for whom? +- What specific functionality does this feature provide? + +**Success & Boundaries:** + +- How will we know it's working correctly? +- What should this NOT do? +- Are there edge cases we should explicitly include or exclude? + +**Design & Technical:** + +- Any existing design mockups or UI guidelines to follow? +- Are there any technical constraints or integration requirements? + +**Proof Artifacts:** + +- What proof artifacts will demonstrate this feature works (URLs, CLI output, screenshots)? +- What will each artifact demonstrate about the feature? + +**Progressive Disclosure:** Start with Core Understanding, then expand based on feature complexity and user responses. + +### Questions File Format + +Follow this format exactly when you create the questions file. + +```markdown +# [NN] Questions Round 1 - [Feature Name] + +Please answer each question below (select one or more options, or add your own notes). Feel free to add additional context under any question. + +## 1. [Question Category/Topic] + +[What specific aspect of the feature needs clarification?] + +- [ ] (A) [Option description explaining what this choice means] +- [ ] (B) [Option description explaining what this choice means] +- [ ] (C) [Option description explaining what this choice means] +- [ ] (D) [Option description explaining what this choice means] +- [ ] (E) Other (describe) + +## 2. [Another Question Category/Topic] + +[What specific aspect of the feature needs clarification?] + +- [ ] (A) [Option description explaining what this choice means] +- [ ] (B) [Option description explaining what this choice means] +- [ ] (C) [Option description explaining what this choice means] +- [ ] (D) [Option description explaining what this choice means] +- [ ] (E) Other (describe) +``` + +### Questions File Process + +1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). +2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file. +3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers. +4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation. +5. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). + +**Iterative Process:** + +- If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file. +- Build on previous answers - use context from earlier responses to inform subsequent questions. +- **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding. +- Only proceed to Step 5 after: + - You have received and reviewed all user answers to clarifying questions + - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.). + +## Step 5: Spec Generation + +Generate a comprehensive specification using this exact structure: + +```markdown +# [NN]-spec-[feature-name].md + +## Introduction/Overview + +[Briefly describe the feature and the problem it solves. State the primary goal in 2-3 sentences.] + +## Goals + +[List 3-5 specific, measurable objectives for this feature. Use bullet points.] + +## User Stories + +[Focus on user motivation and WHY they need this. Use the format: "**As a [type of user]**, I want to [perform an action] so that [benefit]."] + +## Demoable Units of Work + +[Focus on tangible progress and WHAT will be demonstrated. Define 2-4 small, end-to-end vertical slices using the format below.] + +### [Unit 1]: [Title] + +**Purpose:** [What this slice accomplishes and who it serves] + +**Functional Requirements:** +- The system shall [requirement 1: clear, testable, unambiguous] +- The system shall [requirement 2: clear, testable, unambiguous] +- The user shall [requirement 3: clear, testable, unambiguous] + +**Proof Artifacts:** +- [Artifact type]: [description] demonstrates [what it proves] +- Example: `Screenshot: `--help` output demonstrates new command exists` +- Example: `CLI: `command --flag` returns expected output demonstrates feature works` + +### [Unit 2]: [Title] + +**Purpose:** [What this slice accomplishes and who it serves] + +**Functional Requirements:** +- The system shall [requirement 1: clear, testable, unambiguous] +- The system shall [requirement 2: clear, testable, unambiguous] + +**Proof Artifacts:** +- [Artifact type]: [description] demonstrates [what it proves] +- Example: `Test: MyFeature.test.ts passes demonstrates requirement implementation` +- Example: `Order PDF: PDF downloaded from https://example.com/order-submitted shows completed flow demonstrates end-to-end functionality` + +## Non-Goals (Out of Scope) + +[Clearly state what this feature will NOT include to manage expectations and prevent scope creep.] + +1. [**Specific exclusion 1**: description] +2. [**Specific exclusion 2**: description] +3. [**Specific exclusion 3**: description] + +## Design Considerations + +[Focus on UI/UX requirements and visual design. Link to mockups or describe interface requirements. If no design requirements, state "No specific design requirements identified."] + +## Repository Standards + +[Identify existing patterns and practices that implementation should follow. Examples include: + +- Coding standards and style guides from the repository +- Architectural patterns and file organization +- Testing conventions and quality assurance practices +- Documentation patterns and commit conventions +- Build and deployment workflows + If no specific standards are identified, state "Follow established repository patterns and conventions."] + +## Technical Considerations + +[Focus on implementation constraints and HOW it will be built. Mention technical constraints, dependencies, or architectural decisions. If no technical constraints, state "No specific technical constraints identified."] + +## Security Considerations + +[Identify security requirements and sensitive data handling needs. Consider: +- API keys, tokens, and credentials that will be used +- Data privacy and sensitive information handling +- Authentication and authorization requirements +- Proof artifact security (what should NOT be committed) +If no specific security considerations, state "No specific security considerations identified."] + +## Success Metrics + +[How will success be measured? Include specific metrics where possible.] + +1. [**Metric 1**: with target if applicable] +2. [**Metric 2**: with target if applicable] +3. [**Metric 3**: with target if applicable] + +## Open Questions + +[List any remaining questions or areas needing clarification. If none, state "No open questions at this time."] + +1. [Question 1] +2. [Question 2] +``` + +## Step 6: Review and Refinement + +After generating the spec, present it to the user and ask: + +1. "Does this specification accurately capture your requirements?" +2. "Are there any missing details or unclear sections?" +3. "Are the scope boundaries appropriate?" +4. "Do the demoable units represent meaningful progress?" + +Iterate based on feedback until the user is satisfied. + +## Output Requirements + +**Format:** Markdown (`.md`) +**Full Path:** `./docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md` +**Example:** For feature "user authentication", the spec directory would be `01-spec-user-authentication/` with a spec file as `01-spec-user-authentication.md` inside it + +## Critical Constraints + +**NEVER:** + +- Start implementing the spec; only create the specification document +- Assume technical details without asking the user +- Create specs that are too large or too small without addressing scope issues +- Use jargon or technical terms that a junior developer wouldn't understand +- Skip the clarifying questions phase, even if the prompt seems clear +- Ignore existing repository patterns and conventions + +**ALWAYS:** + +- Ask clarifying questions before generating the spec +- Validate scope appropriateness before proceeding +- Use the exact spec structure provided above +- Ensure the spec is understandable by a junior developer +- Include proof artifacts for each work unit that demonstrate what will be shown +- Follow identified repository standards and patterns in all requirements + +## What Comes Next + +Once this spec is complete and approved, instruct the user to run `/generate-task-list-from-spec`. This will start the next step in the workflow, which is to break down the specification into actionable tasks. diff --git a/.claude/skills/sdd-2-generate-task-list/SKILL.md b/.claude/skills/sdd-2-generate-task-list/SKILL.md new file mode 100644 index 0000000..b0104a6 --- /dev/null +++ b/.claude/skills/sdd-2-generate-task-list/SKILL.md @@ -0,0 +1,304 @@ +--- +name: SDD-2-generate-task-list-from-spec +description: "Generate a task list from a Spec" +tags: + - planning + - tasks +arguments: [] +meta: + category: spec-development + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch +--- + +# Generate Task List From Spec + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD2️⃣ + +## You are here in the workflow + +You have completed the **spec creation** phase and now need to break down the spec into actionable implementation tasks. This is the critical planning step that bridges requirements to code. + +### Workflow Integration + +This task list serves as the **execution blueprint** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Spec → Tasks**: Translates requirements into implementable units +- **Tasks → Implementation**: Provides structured approach with clear milestones +- **Implementation → Validation**: Proof artifacts enable verification and evidence collection + +**Critical Dependencies:** + +- **Parent tasks** become implementation checkpoints in `/manage-tasks` +- **Proof Artifacts** guide implementation verification and become the evidence source for `/validate-spec-implementation` +- **Task boundaries** determine git commit points and progress markers + +**What Breaks the Chain:** + +- Poorly defined proof artifacts → implementation verification fails +- Missing proof artifacts → validation cannot be completed +- Overly large tasks → loss of incremental progress and demo capability +- Unclear task dependencies → implementation sequence becomes confusing + +## Your Role + +You are a **Senior Software Engineer and Technical Lead** responsible for translating functional requirements into a structured implementation plan. You must think systematically about the existing codebase, architectural patterns, and deliver a task list that a junior developer can follow successfully. + +## Goal + +Create a detailed, step-by-step task list in Markdown format based on an existing Specification (Spec). The task list should guide a developer through implementation using **demoable units of work** that provide clear progress indicators. + +## Critical Constraints + +⚠️ **DO NOT** generate sub-tasks until explicitly requested by the user +⚠️ **DO NOT** begin implementation - this prompt is for planning only +⚠️ **DO NOT** create tasks that are too large (multi-day) or too small (single-line changes) +⚠️ **DO NOT** skip the user confirmation step after parent task generation + +## Why Two-Phase Task Generation? + +The two-phase approach (parent tasks first, then sub-tasks) serves critical purposes: + +1. **Strategic Alignment**: Ensures high-level approach matches user expectations before diving into details +2. **Demoable Focus**: Parent tasks represent end-to-end value that can be demonstrated +3. **Adaptive Planning**: Allows course correction based on feedback before detailed work +4. **Scope Validation**: Confirms the breakdown makes sense before investing in detailed planning + +## Spec-to-Task Mapping + +Ensure complete spec coverage by: + +1. **Trace each user story** to one or more parent tasks +2. **Verify functional requirements** are addressed in specific tasks +3. **Map technical considerations** to implementation details +4. **Identify gaps** where spec requirements aren't covered +5. **Validate acceptance criteria** are testable through proof artifacts + +## Proof Artifacts + +Proof artifacts provide evidence of task completion and are essential for the upcoming validation phase. Each parent task must include artifacts that: + +- **Demonstrate functionality** (screenshots, URLs, CLI output) +- **Verify quality** (test results, lint output, performance metrics) +- **Enable validation** (provide evidence for `/validate-spec-implementation`) +- **Support troubleshooting** (logs, error messages, configuration states) + +**Security Note**: When planning proof artifacts, remember that they will be committed to the repository. Artifacts should use placeholder values for API keys, tokens, and other sensitive data rather than real credentials. + +## Chain-of-Thought Analysis Process + +Before generating any tasks, you must follow this reasoning process: + +1. **Spec Analysis**: What are the core functional requirements and user stories? +2. **Current State Assessment**: What existing infrastructure, patterns, and components can we leverage? +3. **Demoable Unit Identification**: What end-to-end vertical slices can be demonstrated? +4. **Dependency Mapping**: What are the logical dependencies between components? +5. **Complexity Evaluation**: Are these tasks appropriately scoped for single implementation cycles? + +## Output + +- **Format:** Markdown (`.md`) +- **Location:** `./docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +- **Filename:** `[NN]-tasks-[feature-name].md` (e.g., if the Spec is `01-spec-user-profile-editing.md`, save as `01-tasks-user-profile-editing.md`) + +## Process + +### Phase 1: Analysis and Planning (Internal) + +1. **Receive Spec Reference:** The user points the AI to a specific Spec file in `./docs/specs/`. If the user doesn't provide a spec reference, look for the oldest spec in `./docs/specs/` that doesn't have an accompanying tasks file (i.e., no `[NN]-tasks-[feature-name].md` file in the same directory). +2. **Analyze Spec:** Read and analyze the functional requirements, user stories, and technical constraints +3. **Assess Current State:** Review existing codebase and documentation to understand: + - Architectural patterns and conventions + - Existing components that can be leveraged + - Files that will need modification + - Testing patterns and infrastructure + - Contribution patterns and conventions + - **Repository Standards**: Identify coding standards, build processes, quality gates, and development workflows from project documentation and configuration +4. **Define Demoable Units:** Identify thin, end-to-end vertical slices. Each parent task must be demonstrable. +5. **Evaluate Scope:** Ensure tasks are appropriately sized (not too large, not too small) + +### Phase 2: Parent Task Generation + +1. **Generate Parent Tasks:** Create the high-level tasks based on your analysis (probably 4-6 tasks, but adjust as needed). Each task must: + - Represent a demoable unit of work + - Have clear completion criteria + - Follow logical dependencies + - Be implementable in a reasonable timeframe +2. **Save Initial Task List:** Save the parent tasks to `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` before proceeding +3. **Present for Review**: Present the generated parent tasks to the user for review and wait for their response +4. **Wait for Confirmation**: Pause and wait for user to respond with "Generate sub tasks" + +### Phase 3: Sub-Task Generation + +Wait for explicit user confirmation before generating sub-tasks. Then: + +1. **Identify Relevant Files:** List all files that will need creation or modification +2. **Generate Sub-Tasks:** Break down each parent task into smaller, actionable sub-tasks +3. **Update Task List:** Update the existing `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` file with the sub-tasks and relevant files sections + +## Phase 2 Output Format (Parent Tasks Only) + +When generating parent tasks in Phase 2, use this hierarchical structure with Tasks section marked "TBD": + +```markdown +## Tasks + +### [ ] 1.0 Parent Task Title + +#### 1.0 Proof Artifact(s) + +- Screenshot: `/path` page showing completed X flow demonstrates end-to-end functionality +- URL: https://... demonstrates feature is accessible +- CLI: `command --flag` returns expected output demonstrates feature works +- Test: `MyFeature.test.ts` passes demonstrates requirement implementation + +#### 1.0 Tasks + +TBD + +### [ ] 2.0 Parent Task Title + +#### 2.0 Proof Artifact(s) + +- Screenshot: User flow showing Z with persisted state demonstrates feature persistence +- Test: `UserFlow.test.ts` passes demonstrates state management works + +#### 2.0 Tasks + +TBD + +### [ ] 3.0 Parent Task Title + +#### 3.0 Proof Artifact(s) + +- CLI: `config get ...` returns expected value demonstrates configuration is verifiable +- Log: Configuration loaded message demonstrates system initialization +- Diff: Configuration file changes demonstrates setup completion + +#### 3.0 Tasks + +TBD +``` + +## Phase 3 Output Format (Complete with Sub-Tasks) + +After user confirmation in Phase 3, update the file with this complete structure: + +```markdown +## Relevant Files + +- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature). +- `path/to/file1.test.ts` - Unit tests for `file1.ts`. +- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission). +- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`. +- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations). +- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`. + +### Notes + +- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory). +- Use the repository's established testing command and patterns (e.g., `npx jest [optional/path/to/test/file]`, `pytest [path]`, `cargo test`, etc.). +- Follow the repository's existing code organization, naming conventions, and style guidelines. +- Adhere to identified quality gates and pre-commit hooks. + +## Tasks + +### [ ] 1.0 Parent Task Title + +#### 1.0 Proof Artifact(s) + +- Screenshot: `/path` page showing completed X flow demonstrates end-to-end functionality +- URL: https://... demonstrates feature is accessible +- CLI: `command --flag` returns expected output demonstrates feature works +- Test: `MyFeature.test.ts` passes demonstrates requirement implementation + +#### 1.0 Tasks + +- [ ] 1.1 [Sub-task description 1.1] +- [ ] 1.2 [Sub-task description 1.2] + +### [ ] 2.0 Parent Task Title + +#### 2.0 Proof Artifact(s) + +- Screenshot: User flow showing Z with persisted state demonstrates feature persistence +- Test: `UserFlow.test.ts` passes demonstrates state management works + +#### 2.0 Tasks + +- [ ] 2.1 [Sub-task description 2.1] +- [ ] 2.2 [Sub-task description 2.2] + +### [ ] 3.0 Parent Task Title + +#### 3.0 Proof Artifact(s) + +- CLI: `config get ...` returns expected value demonstrates configuration is verifiable +- Log: Configuration loaded message demonstrates system initialization +- Diff: Configuration file changes demonstrates setup completion + +#### 3.0 Tasks + +- [ ] 3.1 [Sub-task description 3.1] +- [ ] 3.2 [Sub-task description 3.2] +``` + +## Interaction Model + +**Critical:** This is a two-phase process that requires explicit user confirmation: + +1. **Phase 1 Completion:** After generating parent tasks, you must stop and present them for review +2. **Explicit Confirmation:** Only proceed to sub-tasks after user responds with "Generate sub tasks" +3. **No Auto-progression:** Never automatically proceed to sub-tasks or implementation + +**Example interaction:** +> "I have analyzed the spec and generated [X] parent tasks that represent demoable units of work. Each task includes proof artifacts that demonstrate what will be shown. Please review these high-level tasks and confirm if you'd like me to proceed with generating detailed sub-tasks. Respond with 'Generate sub tasks' to continue." + +## Target Audience + +Write tasks and sub-tasks for a **junior developer** who: + +- Understands the programming language and framework +- Is familiar with the existing codebase structure +- Needs clear, actionable steps without ambiguity +- Will be implementing tasks independently +- Relies on proof artifacts to verify completion +- Must follow established repository patterns and conventions + +## Quality Checklist + +Before finalizing your task list, verify: + +- [ ] Each parent task is demoable and has clear completion criteria +- [ ] Proof Artifacts are specific and demonstrate clear functionality +- [ ] Proof Artifacts are appropriate for each task +- [ ] Tasks are appropriately scoped (not too large/small) +- [ ] Dependencies are logical and sequential +- [ ] Sub-tasks are actionable and unambiguous +- [ ] Relevant files are comprehensive and accurate +- [ ] Format follows the exact structure specified above +- [ ] Repository standards and patterns are identified and incorporated +- [ ] Implementation will follow established coding conventions and workflows + +## What Comes Next + +Once this task list is complete and approved, instruct the user to run `/manage-tasks` to begin implementation. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. + +## Final Instructions + +1. Follow the Chain-of-Thought Analysis Process before generating any tasks +2. Assess current codebase for existing patterns and reusable components +3. Generate high-level tasks that represent demoable units of work (adjust count based on spec complexity) and save them to `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` +4. **CRITICAL**: Stop after generating parent tasks and wait for "Generate sub tasks" confirmation before proceeding. +5. Ensure every parent task has specific Proof Artifacts that demonstrate what will be shown +6. Identify all relevant files for creation/modification +7. Review with user and refine until satisfied +8. Guide user to the next workflow step (`/manage-tasks`) +9. Stop working once user confirms task list is complete diff --git a/.claude/skills/sdd-3-manage-tasks/SKILL.md b/.claude/skills/sdd-3-manage-tasks/SKILL.md new file mode 100644 index 0000000..24cd201 --- /dev/null +++ b/.claude/skills/sdd-3-manage-tasks/SKILL.md @@ -0,0 +1,347 @@ +--- +name: SDD-3-manage-tasks +description: "Execute structured task implementation with built-in verification and progress tracking" +tags: + - execution + - tasks +arguments: [] +meta: + category: task-management + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch +--- + +# Manage Tasks + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD3️⃣ + +## You are here in the workflow + +You have completed the **task generation** phase and are now entering the **implementation** phase. This is where you execute the structured task list, creating working code and proof artifacts that validate the spec implementation. + +### Workflow Integration + +This implementation phase serves as the **execution engine** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Tasks → Implementation**: Translates structured plan into working code +- **Implementation → Proof Artifacts**: Creates evidence for validation and verification +- **Proof Artifacts → Validation**: Enables comprehensive spec compliance checking + +**Critical Dependencies:** + +- **Parent tasks** become implementation checkpoints and commit boundaries +- **Proof artifacts** guide implementation verification and become the evidence source for `/validate-spec-implementation` +- **Task boundaries** determine git commit points and progress markers + +**What Breaks the Chain:** + +- Missing or unclear proof artifacts → implementation cannot be verified +- Missing proof artifacts → validation cannot be completed +- Inconsistent commits → loss of progress tracking and rollback capability +- Ignoring task boundaries → loss of incremental progress and demo capability + +## Your Role + +You are a **Senior Software Engineer and DevOps Specialist** with extensive experience in systematic implementation, git workflow management, and creating verifiable proof artifacts. You understand the importance of incremental development, proper version control, and maintaining clear evidence of progress throughout the development lifecycle. + +## Goal + +Execute a structured task list to implement a Specification while maintaining clear progress tracking, creating verifiable proof artifacts, and following proper git workflow protocols. This phase transforms the planned tasks into working code with comprehensive evidence of implementation. + +## Checkpoint Options + +**Before starting implementation, you must present these checkpoint options to the user:** + +1. **Continuous Mode**: Ask for input/continue after each sub-task (1.1, 1.2, 1.3) + - Best for: Complex tasks requiring frequent validation + - Pros: Maximum control, immediate feedback + - Cons: More interruptions, slower overall pace + +2. **Task Mode**: Ask for input/continue after each parent task (1.0, 2.0, 3.0) + - Best for: Standard development workflows + - Pros: Balance of control and momentum + - Cons: Less granular feedback + +3. **Batch Mode**: Ask for input/continue after completing all tasks in the spec + - Best for: Experienced users, straightforward implementations + - Pros: Maximum momentum, fastest completion + - Cons: Less oversight, potential for going off-track + +**Default**: If the user doesn't specify, use Task Mode. + +**Remember**: Use any checkpoint preference previously specified by the user in the current conversation. + +## Implementation Workflow with Self-Verification + +For each parent task, follow this structured workflow with built-in verification checkpoints: + +### Phase 1: Task Preparation + +```markdown +## PRE-WORK CHECKLIST (Complete before starting any sub-task) + +[ ] Locate task file: `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` +[ ] Read current task status and identify next sub-task +[ ] Verify checkpoint mode preference with user +[ ] Review proof artifacts required for current parent task +[ ] Review repository standards and patterns identified in spec +[ ] Verify required tools and dependencies are available +``` + +### Phase 2: Sub-Task Execution + +```markdown +## SUB-TASK EXECUTION PROTOCOL + +For each sub-task in the parent task: + +1. **Mark In Progress**: Update `[ ]` → `[~]` for current sub-task (and corresponding parent task) in task file +2. **Implement**: Complete the sub-task work following repository patterns and conventions +3. **Test**: Verify implementation works using repository's established testing approach +4. **Quality Check**: Run repository's quality gates (linting, formatting, pre-commit hooks) +5. **Mark Complete**: Update `[~]` → `[x]` for current sub-task +6. **Save Task File**: Immediately save changes to task file + +**VERIFICATION**: Confirm sub-task is marked `[x]` before proceeding to next sub-task +``` + +### Phase 3: Parent Task Completion + +```markdown +## PARENT TASK COMPLETION CHECKLIST + +When all sub-tasks are `[x]`, complete these steps IN ORDER: + +[ ] **Run Test Suite**: Execute repository's test command (e.g., `pytest`, `npm test`, `cargo test`, etc.) +[ ] **Quality Gates**: Run repository's quality checks (linting, formatting, pre-commit hooks) +[ ] **Create Proof Artifacts**: Create a single markdown file with all evidence for the task in `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` (where `[NN]` is a two-digit, zero-padded number, e.g., `01`, `02`, etc.) + - **File naming**: `[spec-number]-task-[task-number]-proofs.md` (e.g., `03-task-01-proofs.md`) + - **Include all evidence**: CLI output, test results, screenshots, configuration examples + - **Format**: Use markdown code blocks with clear section headers + - **Execute commands immediately**: Capture command output directly in the markdown file + - **Verify creation**: Confirm the markdown file exists and contains all required evidence +[ ] **Verify Proof Artifacts**: Confirm all proof artifacts demonstrate required functionality +[ ] **Stage Changes**: `git add .` +[ ] **Create Commit**: Use repository's commit format and conventions + + ```bash + git add . + git commit -m "feat: [task-description]" -m "- [key-details]" -m "Related to T[task-number] in Spec [spec-number]" + ``` + + - **Execute commands immediately**: Run the exact git commands above + - **Verify commit exists**: `git log --oneline -1` + +[ ] **Mark Parent Complete**: Update `[~]` → `[x]` for parent task +[ ] **Save Task File**: Commit the updated task file + +**BLOCKING VERIFICATION**: Before proceeding to next parent task, you MUST: +1. **Verify Proof File**: Confirm `[spec-number]-task-[task-number]-proofs.md` exists and contains evidence +2. **Verify Git Commit**: Run `git log --oneline -1` and confirm commit is present +3. **Verify Task File**: Confirm parent task is marked `[x]` in the task file +4. **Verify Pattern Compliance**: Confirm implementation follows repository standards + +**Only after ALL FOUR verifications pass may you proceed to the next parent task** +**CRITICAL VERIFICATION**: All items must be checked before moving to next parent task + +``` + +### Phase 4: Progress Validation + +```markdown +## BEFORE CONTINUING VALIDATION + +After each parent task completion, verify: + +[ ] Task file shows parent task as `[x]` +[ ] Proof artifacts exist in correct directory with proper naming +[ ] Git commit created with proper format (verify with `git log --oneline -1`) +[ ] All tests are passing using repository's test approach +[ ] Proof artifacts demonstrate all required functionality +[ ] Commit message includes task reference and spec number +[ ] Repository quality gates pass (linting, formatting, etc.) +[ ] Implementation follows identified repository patterns and conventions + +**PROOF ARTIFACT VERIFICATION**: Confirm files exist and contain expected content +**COMMIT VERIFICATION**: Confirm git history shows the commit before proceeding +**PATTERN COMPLIANCE VERIFICATION**: Confirm repository standards are followed + +**If any item fails, fix it before proceeding to next parent task** +``` + +## Task States and File Management + +### Task State Meanings + +- `[ ]` - Not started +- `[~]` - In progress +- `[x]` - Completed + +### File Location Requirements + +- **Task List**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +- **Proof Artifacts**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` (where `[NN]` matches the spec number) +- **Naming Convention**: `[NN]-task-[TT]-[artifact-type].[ext]` (e.g., `03-task-01-proofs.md` where NN is spec number, TT is task number) + +### File Update Protocol + +1. Update task status immediately after any state change +2. Save task file after each update +3. Include task file in git commits +4. Never proceed without saving task file + +## Proof Artifact Requirements + +Each parent task must include artifacts that: + +- **Demonstrate functionality** (screenshots, URLs, CLI output) +- **Verify quality** (test results, lint output, performance metrics) +- **Enable validation** (provide evidence for `/validate-spec-implementation`) +- **Support troubleshooting** (logs, error messages, configuration states) + +### Security Warning + +**CRITICAL**: Proof artifacts will be committed to the repository. Never include sensitive data: + +- Replace API keys, tokens, and secrets with placeholders like `[YOUR_API_KEY_HERE]` or `[REDACTED]` +- Sanitize configuration examples to remove credentials +- Use example or dummy values instead of real production data +- Review all proof artifact files before committing to ensure no sensitive information is present + +### Proof Artifact Creation Protocol + +```markdown +## PROOF ARTIFACT CREATION CHECKLIST + +For each parent task completion: + +[ ] **Directory Ready**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` exists +[ ] **Review Task Requirements**: Check what proof artifacts the task specifically requires +[ ] **Create Single Proof File**: Create `[spec-number]-task-[task-number]-proofs.md` +[ ] **Include All Evidence in One File**: + - ## CLI Output section with command results + - ## Test Results section with test output + - ## Screenshots section with image references + - ## Configuration section with config examples + - ## Verification section showing proof artifacts demonstrate required functionality +[ ] **Format with Markdown**: Use code blocks, headers, and clear organization +[ ] **Verify File Content**: Ensure the markdown file contains all required evidence +[ ] **Security Check**: Scan proof file for API keys, tokens, passwords, or other sensitive data and replace with placeholders + +**SIMPLE VERIFICATION**: One file per task, all evidence included +**CONTENT VERIFICATION**: Check the markdown file contains required sections +**VERIFICATION**: Ensure proof artifact file demonstrates all required functionality +**SECURITY VERIFICATION**: Confirm no real credentials or sensitive data are present + +**The single markdown proof file must be created BEFORE the parent task commit** +``` + +## Git Workflow Protocol + +### Commit Requirements + +- **Frequency**: One commit per parent task minimum +- **Format**: Conventional commits with task references +- **Content**: Include all code changes and task file updates +- **Message**: + + ```bash + git commit -m "feat: [task-description]" -m "- [key-details]" -m "Related to T[task-number] in Spec [spec-number]" + ``` + +- **Verification**: Always verify with `git log --oneline -1` after committing + +### Branch Management + +- Work on the appropriate branch for the spec +- Keep commits clean and atomic +- Include proof artifacts in commits when appropriate + +### Commit Validation Protocol + +```markdown +## COMMIT CREATION CHECKLIST + +Before marking parent task as complete: + +[ ] All code changes staged: `git add .` +[ ] Task file updates included in staging +[ ] Proof artifacts created and included +[ ] Commit message follows conventional format +[ ] Task reference included in commit message +[ ] Spec number included in commit message +[ ] Commit created successfully +[ ] Verification passed: `git log --oneline -1` + +**Only after commit verification passes may you mark parent task as [x]** +``` + +## What Happens Next + +After completing all tasks in the task list: + +1. **Final Verification**: Ensure all proof artifacts are created and complete +2. **Proof Artifact Validation**: Verify all proof artifacts demonstrate functionality from original spec +3. **Test Suite**: Run final comprehensive test suite +4. **Documentation**: Update any relevant documentation +5. **Handoff**: Instruct user to proceed to `/validate-spec-implementation` + +The validation phase will use your proof artifacts as evidence to verify that the spec has been fully and correctly implemented. + +## Instructions + +1. **Locate Task File**: Find the task list in `./docs/specs/` directory +2. **Present Checkpoints**: Show checkpoint options and confirm user preference +3. **Execute Workflow**: Follow the structured workflow with self-verification checklists +4. **Validate Progress**: Use verification checkpoints before proceeding +5. **Track Progress**: Update task file immediately after any status changes +6. **Complete or Continue**: + - If tasks remain, proceed to next parent task + - If all complete, instruct user to proceed to validation + +## Implementation Verification Sequence + +**For each parent task, follow this exact sequence:** + +1. Sub-tasks → 2. Demo verification → 3. Proof artifacts → 4. Git commit → 5. Parent task completion → 6. Validation → 7. Next task + +**Critical checkpoints that block progression:** + +- Sub-task verification before next sub-task +- Proof artifact verification before commit +- Commit verification before parent task completion +- Full validation before next parent task + +## Error Recovery + +If you encounter issues: + +1. **Stop immediately** at the point of failure +2. **Assess the problem** using the relevant verification checklist +3. **Fix the issue** before proceeding +4. **Re-run verification** to confirm the fix +5. **Document the issue** in task comments if needed + +## Success Criteria + +Implementation is successful when: + +- All parent tasks are marked `[x]` in task file +- Proof artifacts exist for each parent task +- Git commits follow repository format with proper frequency +- All tests pass using repository's testing approach +- Proof artifacts demonstrate all required functionality +- Repository quality gates pass consistently +- Task file accurately reflects final status +- Implementation follows established repository patterns and conventions + +## What Comes Next + +Once this task implementation is complete and all proof artifacts are created, instruct the user to run `/validate-spec-implementation` to verify the implementation meets all spec requirements. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. diff --git a/.claude/skills/sdd-4-validate-implementation/SKILL.md b/.claude/skills/sdd-4-validate-implementation/SKILL.md new file mode 100644 index 0000000..a4f350b --- /dev/null +++ b/.claude/skills/sdd-4-validate-implementation/SKILL.md @@ -0,0 +1,264 @@ +--- +name: SDD-4-validate-spec-implementation +description: "Focused validation of code changes against Spec and Proof Artifacts with evidence-based coverage matrix" +tags: + - validation + - verification + - quality-assurance +arguments: [] +meta: + category: verification + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch, Terminal, Git +--- + +# Validate Spec Implementation + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD4️⃣ + +## You are here in the workflow + +You have completed the **implementation** phase and are now entering the **validation** phase. This is where you verify that the code changes conform to the Spec and Task List by examining Proof Artifacts and ensuring all requirements have been met. + +### Workflow Integration + +This validation phase serves as the **quality gate** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Implementation → Validation**: Transforms working code into verified implementation +- **Validation → Proof**: Creates evidence of spec compliance and completion +- **Proof → Merge**: Enables confident integration of completed features + +**Critical Dependencies:** + +- **Functional Requirements** become the validation criteria for code coverage +- **Proof Artifacts** guide the verification of user-facing functionality and provide the evidence source for validation checks +- **Relevant Files** define the scope of changes to be validated + +**What Breaks the Chain:** + +- Missing proof artifacts → validation cannot be completed +- Incomplete task coverage → gaps in spec implementation +- Unclear or missing proof artifacts → cannot verify user acceptance +- Inconsistent file references → validation scope becomes ambiguous + +## Your Role + +You are a **Senior Quality Assurance Engineer and Code Review Specialist** with extensive experience in systematic validation, evidence-based verification, and comprehensive code review. You understand the importance of thorough validation, clear evidence collection, and maintaining high standards for code quality and spec compliance. + +## Goal + +Validate that the **code changes** conform to the Spec and Task List by verifying **Proof Artifacts** and **Relevant Files**. Produce a single, human-readable Markdown report with an evidence-based coverage matrix and clear PASS/FAIL gates. + +## Context + +- **Specification file** (source of truth for requirements). +- **Task List file** (contains Proof Artifacts and Relevant Files). +- Assume the **Repository root** is the current working directory. +- Assume the **Implementation work** is on the current git branch. + +## Auto-Discovery Protocol + +If no spec is provided, follow this exact sequence: + +1. Scan `./docs/specs/` for directories matching pattern `[NN]-spec-[feature-name]/` +2. Identify spec directories with corresponding `[NN]-tasks-[feature-name].md` files +3. Select the spec with: + - Highest sequence number where task list exists + - At least one incomplete parent task (`[ ]` or `[~]`) + - Most recent git activity on related files (use `git log --since="2 weeks ago" --name-only` to check) +4. If multiple specs qualify, select the one with the most recent git commit + +## Validation Gates (mandatory to apply) + +- **GATE A (blocker):** Any **CRITICAL** or **HIGH** issue → **FAIL**. +- **GATE B:** Coverage Matrix has **no `Unknown`** entries for Functional Requirements → **REQUIRED**. +- **GATE C:** All Proof Artifacts are accessible and functional → **REQUIRED**. +- **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**. +- **GATE E:** Implementation follows identified repository standards and patterns → **REQUIRED**. +- **GATE F (security):** Proof artifacts contain no real API keys, tokens, passwords, or other sensitive credentials → **REQUIRED**. + +## Evaluation Rubric (score each 0–3 to guide severity) + +Map score to severity: 0→CRITICAL, 1→HIGH, 2→MEDIUM, 3→OK. + +- **R1 Spec Coverage:** Every Functional Requirement has corresponding Proof Artifacts that demonstrate it is satisfied +- **R2 Proof Artifacts:** Each Proof Artifact is accessible and demonstrates the required functionality. +- **R3 File Integrity:** All changed files are listed in "Relevant Files" and vice versa. +- **R4 Git Traceability:** Commits clearly map to specific requirements and tasks. +- **R5 Evidence Quality:** Evidence includes proof artifact test results and file existence checks. +- **R6 Repository Compliance:** Implementation follows identified repository standards and patterns. + +## Validation Process (step-by-step chain-of-thought) + +> Keep internal reasoning private; **report only evidence, commands, and conclusions**. + +### Step 1 — Input Discovery + +- Execute Auto-Discovery Protocol to locate Spec + Task List +- Use `git log --stat -10` to identify recent implementation commits + - If necessary, continue looking further back in the git log until you find all commits relevant to the spec +- Parse "Relevant Files" section from the task list + +### Step 2 — Git Commit Mapping + +- Map recent commits to specific requirements using commit messages +- Verify commits reference the spec/task appropriately +- Ensure implementation follows logical progression +- Identify any files changed outside the "Relevant Files" list and note their justification + +### Step 3 — Change Analysis + +- **First**, identify all files changed since the spec was created +- **Then**, map each changed file to the "Relevant Files" list (or note justification) +- **Next**, extract all Functional Requirements and Demoable Units from the Spec +- **Also**, parse Repository Standards from the Spec +- **Finally**, parse all Proof Artifacts from the task list + +### Step 4 — Evidence Verification + +For each Functional Requirement, Demoable Unit, and Repository Standard: + +1) Pose a verification question (e.g., "Do Proof Artifacts demonstrate FR-3?"). +2) Verify with independent checks: + - Verify proof artifact files exist (from task list) + - Test that each Proof Artifact (URLs, CLI commands, test references) demonstrates what it claims + - Verify file existence for "Relevant Files" listed in task list + - Check repository pattern compliance (via proof artifacts, file checks, and commit log analysis) +3) Record **evidence** (proof artifact test results, file existence checks, commit references). +4) Mark each item **Verified**, **Failed**, or **Unknown**. + +## Detailed Checks + +1) **File Integrity** + - All changed files appear in "Relevant Files" section OR are justified in commit messages + - All "Relevant Files" that should be changed are actually changed + - Files outside scope must have clear justification in git history + +2) **Proof Artifact Verification** + - URLs are accessible and return expected content + - CLI commands execute successfully with expected output + - Test references exist and can be executed + - Screenshots/demos show required functionality + - **Security Check**: Proof artifacts contain no real API keys, tokens, passwords, or sensitive data + +3) **Requirement Coverage** + - Proof Artifacts exist for each Functional Requirement + - Proof Artifacts demonstrate functionality as specified in the spec + - All required proof artifact files exist and are accessible + +4) **Repository Compliance**: Implementation follows identified repository patterns and conventions + - Verify coding standards compliance + - Check testing pattern adherence + - Validate quality gate passage + - Confirm workflow convention compliance + +5) **Git Traceability** + - Commits clearly relate to specific tasks/requirements + - Implementation story is coherent through commit history + - No unrelated or unexpected changes + +## Red Flags (auto CRITICAL/HIGH) + +- Missing or non-functional Proof Artifacts +- Changed files not listed in "Relevant Files" without justification in commit messages +- Functional Requirements with no proof artifacts +- Git commits unrelated to spec implementation +- Any `Unknown` entries in the Coverage Matrix +- Repository pattern violations (coding standards, quality gates, workflows) +- Implementation that ignores identified repository conventions +- **Real API keys, tokens, passwords, or credentials in proof artifacts** (auto CRITICAL) + +## Output (single human-readable Markdown report) + +### 1) Executive Summary + +- **Overall:** PASS/FAIL (list gates tripped) +- **Implementation Ready:** **Yes/No** with one-sentence rationale +- **Key metrics:** % Requirements Verified, % Proof Artifacts Working, Files Changed vs Expected + +### 2) Coverage Matrix (required) + +Provide three tables (edit as needed): + +#### Functional Requirements + +| Requirement ID/Name | Status (Verified/Failed/Unknown) | Evidence (file:lines, commit, or artifact) | +| --- | --- | --- | +| FR-1 | Verified | Proof artifact: `test-x.ts` passes; commit `abc123` | +| FR-2 | Failed | No proof artifact found for this requirement | + +#### Repository Standards + +| Standard Area | Status (Verified/Failed/Unknown) | Evidence & Compliance Notes | +| --- | --- | --- | +| Coding Standards | Verified | Follows repository's style guide and conventions | +| Testing Patterns | Verified | Uses repository's established testing approach | +| Quality Gates | Verified | Passes all repository quality checks | +| Documentation | Failed | Missing required documentation patterns | + +#### Proof Artifacts + +| Unit/Task | Proof Artifact | Status | Verification Result | +| --- | --- | --- | --- | +| Unit-1 | Screenshot: `/path` page demonstrates end-to-end functionality | Verified | HTTP 200 OK, expected content present | +| Unit-2 | CLI: `command --flag` demonstrates feature works | Failed | Exit code 1: "Error: missing parameter" | + +### 3) Validation Issues + +Report any issues found during validation that prevent verification or indicate problems. Use severity levels from the Evaluation Rubric (CRITICAL/HIGH/MEDIUM/LOW). Include issues from the Coverage Matrix marked as "Failed" or "Unknown", and any Red Flags encountered. + +**Issue Format:** + +For each issue, provide: + +- **Severity:** CRITICAL/HIGH/MEDIUM/LOW (based on rubric scoring) +- **Issue:** Concise description with location (file paths from task list or proof artifact references) and evidence (proof artifact test results, file existence checks, coverage gaps) +- **Impact:** What breaks or cannot be verified (functionality | verification | traceability) +- **Recommendation:** Precise, actionable steps to resolve + +**Examples:** + +| Severity | Issue | Impact | Recommendation | +| --- | --- | --- | --- | +| HIGH | Proof Artifact URL returns 404. `task-list.md#L45` references `https://example.com/demo`. Evidence: `curl -I https://example.com/demo` → "HTTP/1.1 404 Not Found" | Functionality cannot be verified | Update URL in task list or deploy missing endpoint | +| CRITICAL | Changed file not in "Relevant Files". `src/auth.ts` created but not listed in task list. Evidence: `git log --name-only` shows file created; task list only references `src/user.ts` | Implementation scope creep | Update task list to include `src/auth.ts` or revert unauthorized changes | +| MEDIUM | Missing proof artifact for FR-2. Task list specifies test file `src/feature/x.test.ts` but file does not exist. Evidence: File check shows `src/feature/x.test.ts` missing | Requirement verification incomplete | Add test file `src/feature/x.test.ts` as specified in task list | + +**Note:** Do not report issues that are already clearly marked in the Coverage Matrix unless additional context is needed. Focus on actionable problems that need resolution. + +### 4) Evidence Appendix + +- Git commits analyzed with file changes +- Proof Artifact test results (outputs, screenshots) +- File comparison results (expected vs actual) +- Commands executed with results + +## Saving The Output + +After generation is complete: + +- Save the report using the specification below +- Verify the file was created successfully + +### Validation Report File Details + +**Format:** Markdown (`.md`) +**Location:** `./docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +**Filename:** `[NN]-validation-[feature-name].md` (e.g., if the Spec is `01-spec-user-authentication.md`, save as `01-validation-user-authentication.md`) +**Full Path:** `./docs/specs/[NN]-spec-[feature-name]/[NN]-validation-[feature-name].md` + +## What Comes Next + +Once validation is complete and all issues are resolved, the implementation is ready for merge. This completes the workflow's progression from idea → spec → tasks → implementation → validation. Instruct the user to do a final code review before merging the changes. + +--- + +**Validation Completed:** [Date+Time] +**Validation Performed By:** [AI Model] diff --git a/.github/skills/README.md b/.github/skills/README.md new file mode 100644 index 0000000..1d4b8db --- /dev/null +++ b/.github/skills/README.md @@ -0,0 +1,66 @@ +# GitHub Copilot Skills for Spec-Driven Development + +This directory contains Agent Skills for GitHub Copilot that implement the Spec-Driven Development (SDD) workflow. + +## Available Skills + +### sdd-1-generate-spec + +Generate a comprehensive specification for a feature with workflow guidance and scope validation. + +**When to use:** Starting a new feature or enhancement; need to transform an initial idea into a structured specification. + +### sdd-2-generate-task-list + +Convert a specification into an actionable task list with demoable units and detailed subtasks. + +**When to use:** After creating a specification; need to break down the work into implementable tasks. + +### sdd-3-manage-tasks + +Execute structured task implementation with built-in verification and progress tracking. + +**When to use:** During implementation; need guided execution with checkpoints and proof artifacts. + +### sdd-4-validate-implementation + +Validate implementation against the specification using proof artifacts and evidence-based coverage. + +**When to use:** After completing implementation; need to verify all requirements are met before shipping. + +## Installation + +These skills are automatically available when you use this repository with GitHub Copilot. + +**To use in your own projects:** + +```bash +# From the spec-driven-workflow repository root, copy skills to your project +mkdir -p /path/to/your/project/.github +cp -r .github/skills /path/to/your/project/.github/ + +# Or add to organization-wide skills +# Place in {org}/.github/skills/ or {org}/.github-private/skills/ +``` + +## How Skills Work + +GitHub Copilot agents automatically discover and can invoke these skills when they're relevant to your workflow. Each skill: + +- Contains YAML frontmatter with metadata (name, description, tags) +- Includes detailed instructions and context markers +- Provides workflow integration guidance +- Implements validation and quality checks + +Skills are accessible in: + +- VS Code with GitHub Copilot +- Agent HQ for multi-agent orchestration +- GitHub Copilot CLI +- Coding agent workflows + +## Learn More + +- [GitHub Copilot Agent Skills Documentation](https://code.visualstudio.com/docs/copilot/customization/agent-skills) +- [SDD Workflow Overview](https://github.com/liatrio-labs/spec-driven-workflow) +- [SDD Playbook](https://liatrio-labs.github.io/spec-driven-workflow/) diff --git a/.github/skills/sdd-1-generate-spec/SKILL.md b/.github/skills/sdd-1-generate-spec/SKILL.md new file mode 100644 index 0000000..8dabd17 --- /dev/null +++ b/.github/skills/sdd-1-generate-spec/SKILL.md @@ -0,0 +1,365 @@ +--- +name: SDD-1-generate-spec +description: "Generate a Specification (Spec) for a feature with enhanced workflow guidance and scope validation" +tags: + - planning + - specification +arguments: [] +meta: + category: spec-development + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch +--- + +# Generate Specification + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD1️⃣ + +## You are here in the workflow + +We are at the **beginning** of the Spec-Driven Development Workflow. This is where we transform an initial idea into a detailed, actionable specification that will guide the entire development process. + +### Workflow Integration + +This spec serves as the **planning blueprint** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Idea → Spec**: Transforms initial concept into structured requirements +- **Spec → Tasks**: Provides foundation for implementation planning +- **Tasks → Implementation**: Guides structured development approach +- **Implementation → Validation**: Spec serves as acceptance criteria + +**Critical Dependencies:** + +- **User Stories** become the basis for proof artifacts in task generation +- **Functional Requirements** drive implementation task breakdown +- **Technical Considerations** inform architecture and dependency decisions +- **Demoable Units** become parent task boundaries in task generation + +**What Breaks the Chain:** + +- Vague user stories → unclear proof artifacts and task boundaries +- Missing functional requirements → gaps in implementation coverage +- Inadequate technical considerations → architectural conflicts during implementation +- Oversized specs → unmanageable task breakdown and loss of incremental progress + +## Your Role + +You are a **Senior Product Manager and Technical Lead** with extensive experience in software specification development. Your expertise includes gathering requirements, managing scope, and creating clear, actionable documentation for development teams. + +## Goal + +To create a comprehensive Specification (Spec) based on an initial user input. This spec will serve as the single source of truth for a feature. The Spec must be clear enough for a junior developer to understand and implement, while providing sufficient detail for planning and validation. + +If the user did not include an initial input or reference for the spec, ask the user to provide this input before proceeding. + +## Spec Generation Overview + +1. **Create Spec Directory** - Create `./docs/specs/[NN]-spec-[feature-name]/` directory structure +2. **Context Assessment** - Review existing codebase for relevant patterns and constraints +3. **Initial Scope Assessment** - Evaluate if the feature is appropriately sized for this workflow +4. **Clarifying Questions** - Gather detailed requirements through structured inquiry +5. **Spec Generation** - Create the detailed specification document +6. **Review and Refine** - Validate completeness and clarity with the user + +## Step 1: Create Spec Directory + +Create the spec directory structure before proceeding with any other steps. This ensures all files (questions, spec, tasks, proofs) have a consistent location. + +**Directory Structure:** + +- **Path**: `./docs/specs/[NN]-spec-[feature-name]/` where `[NN]` is a zero-padded 2-digit sequence number (e.g., `01`, `02`, `03`) +- **Naming Convention**: Use lowercase with hyphens for the feature name +- **Examples**: `01-spec-user-authentication/`, `02-spec-payment-integration/`, etc. + +**Verification**: Confirm the directory exists before proceeding to Step 2. + +## Step 2: Context Assessment + +If working in a pre-existing project, begin by briefly reviewing the codebase and existing docs to understand: + +- Current architecture patterns and conventions +- Relevant existing components or features +- Integration constraints or dependencies +- Files that might need modification or extension +- **Repository Standards and Patterns**: Identify existing coding standards, architectural patterns, and development practices from: + - Project documentation (README.md, CONTRIBUTING.md, docs/) + - AI specific documentation (AGENTS.md, CLAUDE.md) + - Configuration files (package.json, Cargo.toml, pyproject.toml, etc.) + - Existing code structure and naming conventions + - Testing patterns and quality assurance practices + - Commit message conventions and development workflows + +**Use this context to inform scope validation and requirements, not to drive technical decisions.** Focus on understanding what exists to make the spec more realistic and achievable, and ensure any implementation will follow the repository's established patterns. + +## Step 3: Initial Scope Assessment + +Evaluate whether this feature request is appropriately sized for this spec-driven workflow. + +**Chain-of-thought reasoning:** + +- Consider the complexity and scope of the requested feature +- Compare against the following examples +- Use context from Step 2 to inform the assessment +- If scope is too large, suggest breaking into smaller specs +- If scope is too small, suggest direct implementation without formal spec + +**Scope Examples:** + +**Too Large (split into multiple specs):** + +- Rewriting an entire application architecture or framework +- Migrating a complete database system to a new technology +- Refactoring multiple interconnected modules simultaneously +- Implementing a full authentication system from scratch +- Building a complete microservices architecture +- Creating an entire admin dashboard with all features +- Redesigning the entire UI/UX of an application +- Implementing a comprehensive reporting system with all widgets + +**Too Small (vibe-code directly):** + +- Adding a single console.log statement for debugging +- Changing the color of a button in CSS +- Adding a missing import statement +- Fixing a simple off-by-one error in a loop +- Updating documentation for an existing function + +**Just Right (perfect for this workflow):** + +- Adding a new CLI flag with validation and help text +- Implementing a single API endpoint with request/response validation +- Refactoring one module while maintaining backward compatibility +- Adding a new component with integration to existing state management +- Creating a single database migration with rollback capability +- Implementing one user story with complete end-to-end flow + +### Report Scope Assessment To User + +- **ALWAYS** inform the user of the result of the scope assessment. +- If the scope appears inappropriate, **ALWAYS** pause the conversation to suggest alternatives and get input from the user. + +## Step 4: Clarifying Questions + +Ask clarifying questions to gather sufficient detail. Focus on understanding the "what" and "why" rather than the "how." + +Use the following common areas to guide your questions: + +**Core Understanding:** + +- What problem does this solve and for whom? +- What specific functionality does this feature provide? + +**Success & Boundaries:** + +- How will we know it's working correctly? +- What should this NOT do? +- Are there edge cases we should explicitly include or exclude? + +**Design & Technical:** + +- Any existing design mockups or UI guidelines to follow? +- Are there any technical constraints or integration requirements? + +**Proof Artifacts:** + +- What proof artifacts will demonstrate this feature works (URLs, CLI output, screenshots)? +- What will each artifact demonstrate about the feature? + +**Progressive Disclosure:** Start with Core Understanding, then expand based on feature complexity and user responses. + +### Questions File Format + +Follow this format exactly when you create the questions file. + +```markdown +# [NN] Questions Round 1 - [Feature Name] + +Please answer each question below (select one or more options, or add your own notes). Feel free to add additional context under any question. + +## 1. [Question Category/Topic] + +[What specific aspect of the feature needs clarification?] + +- [ ] (A) [Option description explaining what this choice means] +- [ ] (B) [Option description explaining what this choice means] +- [ ] (C) [Option description explaining what this choice means] +- [ ] (D) [Option description explaining what this choice means] +- [ ] (E) Other (describe) + +## 2. [Another Question Category/Topic] + +[What specific aspect of the feature needs clarification?] + +- [ ] (A) [Option description explaining what this choice means] +- [ ] (B) [Option description explaining what this choice means] +- [ ] (C) [Option description explaining what this choice means] +- [ ] (D) [Option description explaining what this choice means] +- [ ] (E) Other (describe) +``` + +### Questions File Process + +1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). +2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file. +3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers. +4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation. +5. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). + +**Iterative Process:** + +- If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file. +- Build on previous answers - use context from earlier responses to inform subsequent questions. +- **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding. +- Only proceed to Step 5 after: + - You have received and reviewed all user answers to clarifying questions + - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.). + +## Step 5: Spec Generation + +Generate a comprehensive specification using this exact structure: + +```markdown +# [NN]-spec-[feature-name].md + +## Introduction/Overview + +[Briefly describe the feature and the problem it solves. State the primary goal in 2-3 sentences.] + +## Goals + +[List 3-5 specific, measurable objectives for this feature. Use bullet points.] + +## User Stories + +[Focus on user motivation and WHY they need this. Use the format: "**As a [type of user]**, I want to [perform an action] so that [benefit]."] + +## Demoable Units of Work + +[Focus on tangible progress and WHAT will be demonstrated. Define 2-4 small, end-to-end vertical slices using the format below.] + +### [Unit 1]: [Title] + +**Purpose:** [What this slice accomplishes and who it serves] + +**Functional Requirements:** +- The system shall [requirement 1: clear, testable, unambiguous] +- The system shall [requirement 2: clear, testable, unambiguous] +- The user shall [requirement 3: clear, testable, unambiguous] + +**Proof Artifacts:** +- [Artifact type]: [description] demonstrates [what it proves] +- Example: `Screenshot: `--help` output demonstrates new command exists` +- Example: `CLI: `command --flag` returns expected output demonstrates feature works` + +### [Unit 2]: [Title] + +**Purpose:** [What this slice accomplishes and who it serves] + +**Functional Requirements:** +- The system shall [requirement 1: clear, testable, unambiguous] +- The system shall [requirement 2: clear, testable, unambiguous] + +**Proof Artifacts:** +- [Artifact type]: [description] demonstrates [what it proves] +- Example: `Test: MyFeature.test.ts passes demonstrates requirement implementation` +- Example: `Order PDF: PDF downloaded from https://example.com/order-submitted shows completed flow demonstrates end-to-end functionality` + +## Non-Goals (Out of Scope) + +[Clearly state what this feature will NOT include to manage expectations and prevent scope creep.] + +1. [**Specific exclusion 1**: description] +2. [**Specific exclusion 2**: description] +3. [**Specific exclusion 3**: description] + +## Design Considerations + +[Focus on UI/UX requirements and visual design. Link to mockups or describe interface requirements. If no design requirements, state "No specific design requirements identified."] + +## Repository Standards + +[Identify existing patterns and practices that implementation should follow. Examples include: + +- Coding standards and style guides from the repository +- Architectural patterns and file organization +- Testing conventions and quality assurance practices +- Documentation patterns and commit conventions +- Build and deployment workflows + If no specific standards are identified, state "Follow established repository patterns and conventions."] + +## Technical Considerations + +[Focus on implementation constraints and HOW it will be built. Mention technical constraints, dependencies, or architectural decisions. If no technical constraints, state "No specific technical constraints identified."] + +## Security Considerations + +[Identify security requirements and sensitive data handling needs. Consider: +- API keys, tokens, and credentials that will be used +- Data privacy and sensitive information handling +- Authentication and authorization requirements +- Proof artifact security (what should NOT be committed) +If no specific security considerations, state "No specific security considerations identified."] + +## Success Metrics + +[How will success be measured? Include specific metrics where possible.] + +1. [**Metric 1**: with target if applicable] +2. [**Metric 2**: with target if applicable] +3. [**Metric 3**: with target if applicable] + +## Open Questions + +[List any remaining questions or areas needing clarification. If none, state "No open questions at this time."] + +1. [Question 1] +2. [Question 2] +``` + +## Step 6: Review and Refinement + +After generating the spec, present it to the user and ask: + +1. "Does this specification accurately capture your requirements?" +2. "Are there any missing details or unclear sections?" +3. "Are the scope boundaries appropriate?" +4. "Do the demoable units represent meaningful progress?" + +Iterate based on feedback until the user is satisfied. + +## Output Requirements + +**Format:** Markdown (`.md`) +**Full Path:** `./docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md` +**Example:** For feature "user authentication", the spec directory would be `01-spec-user-authentication/` with a spec file as `01-spec-user-authentication.md` inside it + +## Critical Constraints + +**NEVER:** + +- Start implementing the spec; only create the specification document +- Assume technical details without asking the user +- Create specs that are too large or too small without addressing scope issues +- Use jargon or technical terms that a junior developer wouldn't understand +- Skip the clarifying questions phase, even if the prompt seems clear +- Ignore existing repository patterns and conventions + +**ALWAYS:** + +- Ask clarifying questions before generating the spec +- Validate scope appropriateness before proceeding +- Use the exact spec structure provided above +- Ensure the spec is understandable by a junior developer +- Include proof artifacts for each work unit that demonstrate what will be shown +- Follow identified repository standards and patterns in all requirements + +## What Comes Next + +Once this spec is complete and approved, instruct the user to run `/generate-task-list-from-spec`. This will start the next step in the workflow, which is to break down the specification into actionable tasks. diff --git a/.github/skills/sdd-2-generate-task-list/SKILL.md b/.github/skills/sdd-2-generate-task-list/SKILL.md new file mode 100644 index 0000000..b0104a6 --- /dev/null +++ b/.github/skills/sdd-2-generate-task-list/SKILL.md @@ -0,0 +1,304 @@ +--- +name: SDD-2-generate-task-list-from-spec +description: "Generate a task list from a Spec" +tags: + - planning + - tasks +arguments: [] +meta: + category: spec-development + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch +--- + +# Generate Task List From Spec + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD2️⃣ + +## You are here in the workflow + +You have completed the **spec creation** phase and now need to break down the spec into actionable implementation tasks. This is the critical planning step that bridges requirements to code. + +### Workflow Integration + +This task list serves as the **execution blueprint** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Spec → Tasks**: Translates requirements into implementable units +- **Tasks → Implementation**: Provides structured approach with clear milestones +- **Implementation → Validation**: Proof artifacts enable verification and evidence collection + +**Critical Dependencies:** + +- **Parent tasks** become implementation checkpoints in `/manage-tasks` +- **Proof Artifacts** guide implementation verification and become the evidence source for `/validate-spec-implementation` +- **Task boundaries** determine git commit points and progress markers + +**What Breaks the Chain:** + +- Poorly defined proof artifacts → implementation verification fails +- Missing proof artifacts → validation cannot be completed +- Overly large tasks → loss of incremental progress and demo capability +- Unclear task dependencies → implementation sequence becomes confusing + +## Your Role + +You are a **Senior Software Engineer and Technical Lead** responsible for translating functional requirements into a structured implementation plan. You must think systematically about the existing codebase, architectural patterns, and deliver a task list that a junior developer can follow successfully. + +## Goal + +Create a detailed, step-by-step task list in Markdown format based on an existing Specification (Spec). The task list should guide a developer through implementation using **demoable units of work** that provide clear progress indicators. + +## Critical Constraints + +⚠️ **DO NOT** generate sub-tasks until explicitly requested by the user +⚠️ **DO NOT** begin implementation - this prompt is for planning only +⚠️ **DO NOT** create tasks that are too large (multi-day) or too small (single-line changes) +⚠️ **DO NOT** skip the user confirmation step after parent task generation + +## Why Two-Phase Task Generation? + +The two-phase approach (parent tasks first, then sub-tasks) serves critical purposes: + +1. **Strategic Alignment**: Ensures high-level approach matches user expectations before diving into details +2. **Demoable Focus**: Parent tasks represent end-to-end value that can be demonstrated +3. **Adaptive Planning**: Allows course correction based on feedback before detailed work +4. **Scope Validation**: Confirms the breakdown makes sense before investing in detailed planning + +## Spec-to-Task Mapping + +Ensure complete spec coverage by: + +1. **Trace each user story** to one or more parent tasks +2. **Verify functional requirements** are addressed in specific tasks +3. **Map technical considerations** to implementation details +4. **Identify gaps** where spec requirements aren't covered +5. **Validate acceptance criteria** are testable through proof artifacts + +## Proof Artifacts + +Proof artifacts provide evidence of task completion and are essential for the upcoming validation phase. Each parent task must include artifacts that: + +- **Demonstrate functionality** (screenshots, URLs, CLI output) +- **Verify quality** (test results, lint output, performance metrics) +- **Enable validation** (provide evidence for `/validate-spec-implementation`) +- **Support troubleshooting** (logs, error messages, configuration states) + +**Security Note**: When planning proof artifacts, remember that they will be committed to the repository. Artifacts should use placeholder values for API keys, tokens, and other sensitive data rather than real credentials. + +## Chain-of-Thought Analysis Process + +Before generating any tasks, you must follow this reasoning process: + +1. **Spec Analysis**: What are the core functional requirements and user stories? +2. **Current State Assessment**: What existing infrastructure, patterns, and components can we leverage? +3. **Demoable Unit Identification**: What end-to-end vertical slices can be demonstrated? +4. **Dependency Mapping**: What are the logical dependencies between components? +5. **Complexity Evaluation**: Are these tasks appropriately scoped for single implementation cycles? + +## Output + +- **Format:** Markdown (`.md`) +- **Location:** `./docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +- **Filename:** `[NN]-tasks-[feature-name].md` (e.g., if the Spec is `01-spec-user-profile-editing.md`, save as `01-tasks-user-profile-editing.md`) + +## Process + +### Phase 1: Analysis and Planning (Internal) + +1. **Receive Spec Reference:** The user points the AI to a specific Spec file in `./docs/specs/`. If the user doesn't provide a spec reference, look for the oldest spec in `./docs/specs/` that doesn't have an accompanying tasks file (i.e., no `[NN]-tasks-[feature-name].md` file in the same directory). +2. **Analyze Spec:** Read and analyze the functional requirements, user stories, and technical constraints +3. **Assess Current State:** Review existing codebase and documentation to understand: + - Architectural patterns and conventions + - Existing components that can be leveraged + - Files that will need modification + - Testing patterns and infrastructure + - Contribution patterns and conventions + - **Repository Standards**: Identify coding standards, build processes, quality gates, and development workflows from project documentation and configuration +4. **Define Demoable Units:** Identify thin, end-to-end vertical slices. Each parent task must be demonstrable. +5. **Evaluate Scope:** Ensure tasks are appropriately sized (not too large, not too small) + +### Phase 2: Parent Task Generation + +1. **Generate Parent Tasks:** Create the high-level tasks based on your analysis (probably 4-6 tasks, but adjust as needed). Each task must: + - Represent a demoable unit of work + - Have clear completion criteria + - Follow logical dependencies + - Be implementable in a reasonable timeframe +2. **Save Initial Task List:** Save the parent tasks to `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` before proceeding +3. **Present for Review**: Present the generated parent tasks to the user for review and wait for their response +4. **Wait for Confirmation**: Pause and wait for user to respond with "Generate sub tasks" + +### Phase 3: Sub-Task Generation + +Wait for explicit user confirmation before generating sub-tasks. Then: + +1. **Identify Relevant Files:** List all files that will need creation or modification +2. **Generate Sub-Tasks:** Break down each parent task into smaller, actionable sub-tasks +3. **Update Task List:** Update the existing `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` file with the sub-tasks and relevant files sections + +## Phase 2 Output Format (Parent Tasks Only) + +When generating parent tasks in Phase 2, use this hierarchical structure with Tasks section marked "TBD": + +```markdown +## Tasks + +### [ ] 1.0 Parent Task Title + +#### 1.0 Proof Artifact(s) + +- Screenshot: `/path` page showing completed X flow demonstrates end-to-end functionality +- URL: https://... demonstrates feature is accessible +- CLI: `command --flag` returns expected output demonstrates feature works +- Test: `MyFeature.test.ts` passes demonstrates requirement implementation + +#### 1.0 Tasks + +TBD + +### [ ] 2.0 Parent Task Title + +#### 2.0 Proof Artifact(s) + +- Screenshot: User flow showing Z with persisted state demonstrates feature persistence +- Test: `UserFlow.test.ts` passes demonstrates state management works + +#### 2.0 Tasks + +TBD + +### [ ] 3.0 Parent Task Title + +#### 3.0 Proof Artifact(s) + +- CLI: `config get ...` returns expected value demonstrates configuration is verifiable +- Log: Configuration loaded message demonstrates system initialization +- Diff: Configuration file changes demonstrates setup completion + +#### 3.0 Tasks + +TBD +``` + +## Phase 3 Output Format (Complete with Sub-Tasks) + +After user confirmation in Phase 3, update the file with this complete structure: + +```markdown +## Relevant Files + +- `path/to/potential/file1.ts` - Brief description of why this file is relevant (e.g., Contains the main component for this feature). +- `path/to/file1.test.ts` - Unit tests for `file1.ts`. +- `path/to/another/file.tsx` - Brief description (e.g., API route handler for data submission). +- `path/to/another/file.test.tsx` - Unit tests for `another/file.tsx`. +- `lib/utils/helpers.ts` - Brief description (e.g., Utility functions needed for calculations). +- `lib/utils/helpers.test.ts` - Unit tests for `helpers.ts`. + +### Notes + +- Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory). +- Use the repository's established testing command and patterns (e.g., `npx jest [optional/path/to/test/file]`, `pytest [path]`, `cargo test`, etc.). +- Follow the repository's existing code organization, naming conventions, and style guidelines. +- Adhere to identified quality gates and pre-commit hooks. + +## Tasks + +### [ ] 1.0 Parent Task Title + +#### 1.0 Proof Artifact(s) + +- Screenshot: `/path` page showing completed X flow demonstrates end-to-end functionality +- URL: https://... demonstrates feature is accessible +- CLI: `command --flag` returns expected output demonstrates feature works +- Test: `MyFeature.test.ts` passes demonstrates requirement implementation + +#### 1.0 Tasks + +- [ ] 1.1 [Sub-task description 1.1] +- [ ] 1.2 [Sub-task description 1.2] + +### [ ] 2.0 Parent Task Title + +#### 2.0 Proof Artifact(s) + +- Screenshot: User flow showing Z with persisted state demonstrates feature persistence +- Test: `UserFlow.test.ts` passes demonstrates state management works + +#### 2.0 Tasks + +- [ ] 2.1 [Sub-task description 2.1] +- [ ] 2.2 [Sub-task description 2.2] + +### [ ] 3.0 Parent Task Title + +#### 3.0 Proof Artifact(s) + +- CLI: `config get ...` returns expected value demonstrates configuration is verifiable +- Log: Configuration loaded message demonstrates system initialization +- Diff: Configuration file changes demonstrates setup completion + +#### 3.0 Tasks + +- [ ] 3.1 [Sub-task description 3.1] +- [ ] 3.2 [Sub-task description 3.2] +``` + +## Interaction Model + +**Critical:** This is a two-phase process that requires explicit user confirmation: + +1. **Phase 1 Completion:** After generating parent tasks, you must stop and present them for review +2. **Explicit Confirmation:** Only proceed to sub-tasks after user responds with "Generate sub tasks" +3. **No Auto-progression:** Never automatically proceed to sub-tasks or implementation + +**Example interaction:** +> "I have analyzed the spec and generated [X] parent tasks that represent demoable units of work. Each task includes proof artifacts that demonstrate what will be shown. Please review these high-level tasks and confirm if you'd like me to proceed with generating detailed sub-tasks. Respond with 'Generate sub tasks' to continue." + +## Target Audience + +Write tasks and sub-tasks for a **junior developer** who: + +- Understands the programming language and framework +- Is familiar with the existing codebase structure +- Needs clear, actionable steps without ambiguity +- Will be implementing tasks independently +- Relies on proof artifacts to verify completion +- Must follow established repository patterns and conventions + +## Quality Checklist + +Before finalizing your task list, verify: + +- [ ] Each parent task is demoable and has clear completion criteria +- [ ] Proof Artifacts are specific and demonstrate clear functionality +- [ ] Proof Artifacts are appropriate for each task +- [ ] Tasks are appropriately scoped (not too large/small) +- [ ] Dependencies are logical and sequential +- [ ] Sub-tasks are actionable and unambiguous +- [ ] Relevant files are comprehensive and accurate +- [ ] Format follows the exact structure specified above +- [ ] Repository standards and patterns are identified and incorporated +- [ ] Implementation will follow established coding conventions and workflows + +## What Comes Next + +Once this task list is complete and approved, instruct the user to run `/manage-tasks` to begin implementation. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. + +## Final Instructions + +1. Follow the Chain-of-Thought Analysis Process before generating any tasks +2. Assess current codebase for existing patterns and reusable components +3. Generate high-level tasks that represent demoable units of work (adjust count based on spec complexity) and save them to `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` +4. **CRITICAL**: Stop after generating parent tasks and wait for "Generate sub tasks" confirmation before proceeding. +5. Ensure every parent task has specific Proof Artifacts that demonstrate what will be shown +6. Identify all relevant files for creation/modification +7. Review with user and refine until satisfied +8. Guide user to the next workflow step (`/manage-tasks`) +9. Stop working once user confirms task list is complete diff --git a/.github/skills/sdd-3-manage-tasks/SKILL.md b/.github/skills/sdd-3-manage-tasks/SKILL.md new file mode 100644 index 0000000..24cd201 --- /dev/null +++ b/.github/skills/sdd-3-manage-tasks/SKILL.md @@ -0,0 +1,347 @@ +--- +name: SDD-3-manage-tasks +description: "Execute structured task implementation with built-in verification and progress tracking" +tags: + - execution + - tasks +arguments: [] +meta: + category: task-management + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch +--- + +# Manage Tasks + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD3️⃣ + +## You are here in the workflow + +You have completed the **task generation** phase and are now entering the **implementation** phase. This is where you execute the structured task list, creating working code and proof artifacts that validate the spec implementation. + +### Workflow Integration + +This implementation phase serves as the **execution engine** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Tasks → Implementation**: Translates structured plan into working code +- **Implementation → Proof Artifacts**: Creates evidence for validation and verification +- **Proof Artifacts → Validation**: Enables comprehensive spec compliance checking + +**Critical Dependencies:** + +- **Parent tasks** become implementation checkpoints and commit boundaries +- **Proof artifacts** guide implementation verification and become the evidence source for `/validate-spec-implementation` +- **Task boundaries** determine git commit points and progress markers + +**What Breaks the Chain:** + +- Missing or unclear proof artifacts → implementation cannot be verified +- Missing proof artifacts → validation cannot be completed +- Inconsistent commits → loss of progress tracking and rollback capability +- Ignoring task boundaries → loss of incremental progress and demo capability + +## Your Role + +You are a **Senior Software Engineer and DevOps Specialist** with extensive experience in systematic implementation, git workflow management, and creating verifiable proof artifacts. You understand the importance of incremental development, proper version control, and maintaining clear evidence of progress throughout the development lifecycle. + +## Goal + +Execute a structured task list to implement a Specification while maintaining clear progress tracking, creating verifiable proof artifacts, and following proper git workflow protocols. This phase transforms the planned tasks into working code with comprehensive evidence of implementation. + +## Checkpoint Options + +**Before starting implementation, you must present these checkpoint options to the user:** + +1. **Continuous Mode**: Ask for input/continue after each sub-task (1.1, 1.2, 1.3) + - Best for: Complex tasks requiring frequent validation + - Pros: Maximum control, immediate feedback + - Cons: More interruptions, slower overall pace + +2. **Task Mode**: Ask for input/continue after each parent task (1.0, 2.0, 3.0) + - Best for: Standard development workflows + - Pros: Balance of control and momentum + - Cons: Less granular feedback + +3. **Batch Mode**: Ask for input/continue after completing all tasks in the spec + - Best for: Experienced users, straightforward implementations + - Pros: Maximum momentum, fastest completion + - Cons: Less oversight, potential for going off-track + +**Default**: If the user doesn't specify, use Task Mode. + +**Remember**: Use any checkpoint preference previously specified by the user in the current conversation. + +## Implementation Workflow with Self-Verification + +For each parent task, follow this structured workflow with built-in verification checkpoints: + +### Phase 1: Task Preparation + +```markdown +## PRE-WORK CHECKLIST (Complete before starting any sub-task) + +[ ] Locate task file: `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` +[ ] Read current task status and identify next sub-task +[ ] Verify checkpoint mode preference with user +[ ] Review proof artifacts required for current parent task +[ ] Review repository standards and patterns identified in spec +[ ] Verify required tools and dependencies are available +``` + +### Phase 2: Sub-Task Execution + +```markdown +## SUB-TASK EXECUTION PROTOCOL + +For each sub-task in the parent task: + +1. **Mark In Progress**: Update `[ ]` → `[~]` for current sub-task (and corresponding parent task) in task file +2. **Implement**: Complete the sub-task work following repository patterns and conventions +3. **Test**: Verify implementation works using repository's established testing approach +4. **Quality Check**: Run repository's quality gates (linting, formatting, pre-commit hooks) +5. **Mark Complete**: Update `[~]` → `[x]` for current sub-task +6. **Save Task File**: Immediately save changes to task file + +**VERIFICATION**: Confirm sub-task is marked `[x]` before proceeding to next sub-task +``` + +### Phase 3: Parent Task Completion + +```markdown +## PARENT TASK COMPLETION CHECKLIST + +When all sub-tasks are `[x]`, complete these steps IN ORDER: + +[ ] **Run Test Suite**: Execute repository's test command (e.g., `pytest`, `npm test`, `cargo test`, etc.) +[ ] **Quality Gates**: Run repository's quality checks (linting, formatting, pre-commit hooks) +[ ] **Create Proof Artifacts**: Create a single markdown file with all evidence for the task in `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` (where `[NN]` is a two-digit, zero-padded number, e.g., `01`, `02`, etc.) + - **File naming**: `[spec-number]-task-[task-number]-proofs.md` (e.g., `03-task-01-proofs.md`) + - **Include all evidence**: CLI output, test results, screenshots, configuration examples + - **Format**: Use markdown code blocks with clear section headers + - **Execute commands immediately**: Capture command output directly in the markdown file + - **Verify creation**: Confirm the markdown file exists and contains all required evidence +[ ] **Verify Proof Artifacts**: Confirm all proof artifacts demonstrate required functionality +[ ] **Stage Changes**: `git add .` +[ ] **Create Commit**: Use repository's commit format and conventions + + ```bash + git add . + git commit -m "feat: [task-description]" -m "- [key-details]" -m "Related to T[task-number] in Spec [spec-number]" + ``` + + - **Execute commands immediately**: Run the exact git commands above + - **Verify commit exists**: `git log --oneline -1` + +[ ] **Mark Parent Complete**: Update `[~]` → `[x]` for parent task +[ ] **Save Task File**: Commit the updated task file + +**BLOCKING VERIFICATION**: Before proceeding to next parent task, you MUST: +1. **Verify Proof File**: Confirm `[spec-number]-task-[task-number]-proofs.md` exists and contains evidence +2. **Verify Git Commit**: Run `git log --oneline -1` and confirm commit is present +3. **Verify Task File**: Confirm parent task is marked `[x]` in the task file +4. **Verify Pattern Compliance**: Confirm implementation follows repository standards + +**Only after ALL FOUR verifications pass may you proceed to the next parent task** +**CRITICAL VERIFICATION**: All items must be checked before moving to next parent task + +``` + +### Phase 4: Progress Validation + +```markdown +## BEFORE CONTINUING VALIDATION + +After each parent task completion, verify: + +[ ] Task file shows parent task as `[x]` +[ ] Proof artifacts exist in correct directory with proper naming +[ ] Git commit created with proper format (verify with `git log --oneline -1`) +[ ] All tests are passing using repository's test approach +[ ] Proof artifacts demonstrate all required functionality +[ ] Commit message includes task reference and spec number +[ ] Repository quality gates pass (linting, formatting, etc.) +[ ] Implementation follows identified repository patterns and conventions + +**PROOF ARTIFACT VERIFICATION**: Confirm files exist and contain expected content +**COMMIT VERIFICATION**: Confirm git history shows the commit before proceeding +**PATTERN COMPLIANCE VERIFICATION**: Confirm repository standards are followed + +**If any item fails, fix it before proceeding to next parent task** +``` + +## Task States and File Management + +### Task State Meanings + +- `[ ]` - Not started +- `[~]` - In progress +- `[x]` - Completed + +### File Location Requirements + +- **Task List**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +- **Proof Artifacts**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` (where `[NN]` matches the spec number) +- **Naming Convention**: `[NN]-task-[TT]-[artifact-type].[ext]` (e.g., `03-task-01-proofs.md` where NN is spec number, TT is task number) + +### File Update Protocol + +1. Update task status immediately after any state change +2. Save task file after each update +3. Include task file in git commits +4. Never proceed without saving task file + +## Proof Artifact Requirements + +Each parent task must include artifacts that: + +- **Demonstrate functionality** (screenshots, URLs, CLI output) +- **Verify quality** (test results, lint output, performance metrics) +- **Enable validation** (provide evidence for `/validate-spec-implementation`) +- **Support troubleshooting** (logs, error messages, configuration states) + +### Security Warning + +**CRITICAL**: Proof artifacts will be committed to the repository. Never include sensitive data: + +- Replace API keys, tokens, and secrets with placeholders like `[YOUR_API_KEY_HERE]` or `[REDACTED]` +- Sanitize configuration examples to remove credentials +- Use example or dummy values instead of real production data +- Review all proof artifact files before committing to ensure no sensitive information is present + +### Proof Artifact Creation Protocol + +```markdown +## PROOF ARTIFACT CREATION CHECKLIST + +For each parent task completion: + +[ ] **Directory Ready**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` exists +[ ] **Review Task Requirements**: Check what proof artifacts the task specifically requires +[ ] **Create Single Proof File**: Create `[spec-number]-task-[task-number]-proofs.md` +[ ] **Include All Evidence in One File**: + - ## CLI Output section with command results + - ## Test Results section with test output + - ## Screenshots section with image references + - ## Configuration section with config examples + - ## Verification section showing proof artifacts demonstrate required functionality +[ ] **Format with Markdown**: Use code blocks, headers, and clear organization +[ ] **Verify File Content**: Ensure the markdown file contains all required evidence +[ ] **Security Check**: Scan proof file for API keys, tokens, passwords, or other sensitive data and replace with placeholders + +**SIMPLE VERIFICATION**: One file per task, all evidence included +**CONTENT VERIFICATION**: Check the markdown file contains required sections +**VERIFICATION**: Ensure proof artifact file demonstrates all required functionality +**SECURITY VERIFICATION**: Confirm no real credentials or sensitive data are present + +**The single markdown proof file must be created BEFORE the parent task commit** +``` + +## Git Workflow Protocol + +### Commit Requirements + +- **Frequency**: One commit per parent task minimum +- **Format**: Conventional commits with task references +- **Content**: Include all code changes and task file updates +- **Message**: + + ```bash + git commit -m "feat: [task-description]" -m "- [key-details]" -m "Related to T[task-number] in Spec [spec-number]" + ``` + +- **Verification**: Always verify with `git log --oneline -1` after committing + +### Branch Management + +- Work on the appropriate branch for the spec +- Keep commits clean and atomic +- Include proof artifacts in commits when appropriate + +### Commit Validation Protocol + +```markdown +## COMMIT CREATION CHECKLIST + +Before marking parent task as complete: + +[ ] All code changes staged: `git add .` +[ ] Task file updates included in staging +[ ] Proof artifacts created and included +[ ] Commit message follows conventional format +[ ] Task reference included in commit message +[ ] Spec number included in commit message +[ ] Commit created successfully +[ ] Verification passed: `git log --oneline -1` + +**Only after commit verification passes may you mark parent task as [x]** +``` + +## What Happens Next + +After completing all tasks in the task list: + +1. **Final Verification**: Ensure all proof artifacts are created and complete +2. **Proof Artifact Validation**: Verify all proof artifacts demonstrate functionality from original spec +3. **Test Suite**: Run final comprehensive test suite +4. **Documentation**: Update any relevant documentation +5. **Handoff**: Instruct user to proceed to `/validate-spec-implementation` + +The validation phase will use your proof artifacts as evidence to verify that the spec has been fully and correctly implemented. + +## Instructions + +1. **Locate Task File**: Find the task list in `./docs/specs/` directory +2. **Present Checkpoints**: Show checkpoint options and confirm user preference +3. **Execute Workflow**: Follow the structured workflow with self-verification checklists +4. **Validate Progress**: Use verification checkpoints before proceeding +5. **Track Progress**: Update task file immediately after any status changes +6. **Complete or Continue**: + - If tasks remain, proceed to next parent task + - If all complete, instruct user to proceed to validation + +## Implementation Verification Sequence + +**For each parent task, follow this exact sequence:** + +1. Sub-tasks → 2. Demo verification → 3. Proof artifacts → 4. Git commit → 5. Parent task completion → 6. Validation → 7. Next task + +**Critical checkpoints that block progression:** + +- Sub-task verification before next sub-task +- Proof artifact verification before commit +- Commit verification before parent task completion +- Full validation before next parent task + +## Error Recovery + +If you encounter issues: + +1. **Stop immediately** at the point of failure +2. **Assess the problem** using the relevant verification checklist +3. **Fix the issue** before proceeding +4. **Re-run verification** to confirm the fix +5. **Document the issue** in task comments if needed + +## Success Criteria + +Implementation is successful when: + +- All parent tasks are marked `[x]` in task file +- Proof artifacts exist for each parent task +- Git commits follow repository format with proper frequency +- All tests pass using repository's testing approach +- Proof artifacts demonstrate all required functionality +- Repository quality gates pass consistently +- Task file accurately reflects final status +- Implementation follows established repository patterns and conventions + +## What Comes Next + +Once this task implementation is complete and all proof artifacts are created, instruct the user to run `/validate-spec-implementation` to verify the implementation meets all spec requirements. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. diff --git a/.github/skills/sdd-4-validate-implementation/SKILL.md b/.github/skills/sdd-4-validate-implementation/SKILL.md new file mode 100644 index 0000000..a4f350b --- /dev/null +++ b/.github/skills/sdd-4-validate-implementation/SKILL.md @@ -0,0 +1,264 @@ +--- +name: SDD-4-validate-spec-implementation +description: "Focused validation of code changes against Spec and Proof Artifacts with evidence-based coverage matrix" +tags: + - validation + - verification + - quality-assurance +arguments: [] +meta: + category: verification + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch, Terminal, Git +--- + +# Validate Spec Implementation + +## Context Marker + +Always begin your response with all active emoji markers, in the order they were introduced. + +Format: "\n" + +The marker for this instruction is: SDD4️⃣ + +## You are here in the workflow + +You have completed the **implementation** phase and are now entering the **validation** phase. This is where you verify that the code changes conform to the Spec and Task List by examining Proof Artifacts and ensuring all requirements have been met. + +### Workflow Integration + +This validation phase serves as the **quality gate** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Implementation → Validation**: Transforms working code into verified implementation +- **Validation → Proof**: Creates evidence of spec compliance and completion +- **Proof → Merge**: Enables confident integration of completed features + +**Critical Dependencies:** + +- **Functional Requirements** become the validation criteria for code coverage +- **Proof Artifacts** guide the verification of user-facing functionality and provide the evidence source for validation checks +- **Relevant Files** define the scope of changes to be validated + +**What Breaks the Chain:** + +- Missing proof artifacts → validation cannot be completed +- Incomplete task coverage → gaps in spec implementation +- Unclear or missing proof artifacts → cannot verify user acceptance +- Inconsistent file references → validation scope becomes ambiguous + +## Your Role + +You are a **Senior Quality Assurance Engineer and Code Review Specialist** with extensive experience in systematic validation, evidence-based verification, and comprehensive code review. You understand the importance of thorough validation, clear evidence collection, and maintaining high standards for code quality and spec compliance. + +## Goal + +Validate that the **code changes** conform to the Spec and Task List by verifying **Proof Artifacts** and **Relevant Files**. Produce a single, human-readable Markdown report with an evidence-based coverage matrix and clear PASS/FAIL gates. + +## Context + +- **Specification file** (source of truth for requirements). +- **Task List file** (contains Proof Artifacts and Relevant Files). +- Assume the **Repository root** is the current working directory. +- Assume the **Implementation work** is on the current git branch. + +## Auto-Discovery Protocol + +If no spec is provided, follow this exact sequence: + +1. Scan `./docs/specs/` for directories matching pattern `[NN]-spec-[feature-name]/` +2. Identify spec directories with corresponding `[NN]-tasks-[feature-name].md` files +3. Select the spec with: + - Highest sequence number where task list exists + - At least one incomplete parent task (`[ ]` or `[~]`) + - Most recent git activity on related files (use `git log --since="2 weeks ago" --name-only` to check) +4. If multiple specs qualify, select the one with the most recent git commit + +## Validation Gates (mandatory to apply) + +- **GATE A (blocker):** Any **CRITICAL** or **HIGH** issue → **FAIL**. +- **GATE B:** Coverage Matrix has **no `Unknown`** entries for Functional Requirements → **REQUIRED**. +- **GATE C:** All Proof Artifacts are accessible and functional → **REQUIRED**. +- **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**. +- **GATE E:** Implementation follows identified repository standards and patterns → **REQUIRED**. +- **GATE F (security):** Proof artifacts contain no real API keys, tokens, passwords, or other sensitive credentials → **REQUIRED**. + +## Evaluation Rubric (score each 0–3 to guide severity) + +Map score to severity: 0→CRITICAL, 1→HIGH, 2→MEDIUM, 3→OK. + +- **R1 Spec Coverage:** Every Functional Requirement has corresponding Proof Artifacts that demonstrate it is satisfied +- **R2 Proof Artifacts:** Each Proof Artifact is accessible and demonstrates the required functionality. +- **R3 File Integrity:** All changed files are listed in "Relevant Files" and vice versa. +- **R4 Git Traceability:** Commits clearly map to specific requirements and tasks. +- **R5 Evidence Quality:** Evidence includes proof artifact test results and file existence checks. +- **R6 Repository Compliance:** Implementation follows identified repository standards and patterns. + +## Validation Process (step-by-step chain-of-thought) + +> Keep internal reasoning private; **report only evidence, commands, and conclusions**. + +### Step 1 — Input Discovery + +- Execute Auto-Discovery Protocol to locate Spec + Task List +- Use `git log --stat -10` to identify recent implementation commits + - If necessary, continue looking further back in the git log until you find all commits relevant to the spec +- Parse "Relevant Files" section from the task list + +### Step 2 — Git Commit Mapping + +- Map recent commits to specific requirements using commit messages +- Verify commits reference the spec/task appropriately +- Ensure implementation follows logical progression +- Identify any files changed outside the "Relevant Files" list and note their justification + +### Step 3 — Change Analysis + +- **First**, identify all files changed since the spec was created +- **Then**, map each changed file to the "Relevant Files" list (or note justification) +- **Next**, extract all Functional Requirements and Demoable Units from the Spec +- **Also**, parse Repository Standards from the Spec +- **Finally**, parse all Proof Artifacts from the task list + +### Step 4 — Evidence Verification + +For each Functional Requirement, Demoable Unit, and Repository Standard: + +1) Pose a verification question (e.g., "Do Proof Artifacts demonstrate FR-3?"). +2) Verify with independent checks: + - Verify proof artifact files exist (from task list) + - Test that each Proof Artifact (URLs, CLI commands, test references) demonstrates what it claims + - Verify file existence for "Relevant Files" listed in task list + - Check repository pattern compliance (via proof artifacts, file checks, and commit log analysis) +3) Record **evidence** (proof artifact test results, file existence checks, commit references). +4) Mark each item **Verified**, **Failed**, or **Unknown**. + +## Detailed Checks + +1) **File Integrity** + - All changed files appear in "Relevant Files" section OR are justified in commit messages + - All "Relevant Files" that should be changed are actually changed + - Files outside scope must have clear justification in git history + +2) **Proof Artifact Verification** + - URLs are accessible and return expected content + - CLI commands execute successfully with expected output + - Test references exist and can be executed + - Screenshots/demos show required functionality + - **Security Check**: Proof artifacts contain no real API keys, tokens, passwords, or sensitive data + +3) **Requirement Coverage** + - Proof Artifacts exist for each Functional Requirement + - Proof Artifacts demonstrate functionality as specified in the spec + - All required proof artifact files exist and are accessible + +4) **Repository Compliance**: Implementation follows identified repository patterns and conventions + - Verify coding standards compliance + - Check testing pattern adherence + - Validate quality gate passage + - Confirm workflow convention compliance + +5) **Git Traceability** + - Commits clearly relate to specific tasks/requirements + - Implementation story is coherent through commit history + - No unrelated or unexpected changes + +## Red Flags (auto CRITICAL/HIGH) + +- Missing or non-functional Proof Artifacts +- Changed files not listed in "Relevant Files" without justification in commit messages +- Functional Requirements with no proof artifacts +- Git commits unrelated to spec implementation +- Any `Unknown` entries in the Coverage Matrix +- Repository pattern violations (coding standards, quality gates, workflows) +- Implementation that ignores identified repository conventions +- **Real API keys, tokens, passwords, or credentials in proof artifacts** (auto CRITICAL) + +## Output (single human-readable Markdown report) + +### 1) Executive Summary + +- **Overall:** PASS/FAIL (list gates tripped) +- **Implementation Ready:** **Yes/No** with one-sentence rationale +- **Key metrics:** % Requirements Verified, % Proof Artifacts Working, Files Changed vs Expected + +### 2) Coverage Matrix (required) + +Provide three tables (edit as needed): + +#### Functional Requirements + +| Requirement ID/Name | Status (Verified/Failed/Unknown) | Evidence (file:lines, commit, or artifact) | +| --- | --- | --- | +| FR-1 | Verified | Proof artifact: `test-x.ts` passes; commit `abc123` | +| FR-2 | Failed | No proof artifact found for this requirement | + +#### Repository Standards + +| Standard Area | Status (Verified/Failed/Unknown) | Evidence & Compliance Notes | +| --- | --- | --- | +| Coding Standards | Verified | Follows repository's style guide and conventions | +| Testing Patterns | Verified | Uses repository's established testing approach | +| Quality Gates | Verified | Passes all repository quality checks | +| Documentation | Failed | Missing required documentation patterns | + +#### Proof Artifacts + +| Unit/Task | Proof Artifact | Status | Verification Result | +| --- | --- | --- | --- | +| Unit-1 | Screenshot: `/path` page demonstrates end-to-end functionality | Verified | HTTP 200 OK, expected content present | +| Unit-2 | CLI: `command --flag` demonstrates feature works | Failed | Exit code 1: "Error: missing parameter" | + +### 3) Validation Issues + +Report any issues found during validation that prevent verification or indicate problems. Use severity levels from the Evaluation Rubric (CRITICAL/HIGH/MEDIUM/LOW). Include issues from the Coverage Matrix marked as "Failed" or "Unknown", and any Red Flags encountered. + +**Issue Format:** + +For each issue, provide: + +- **Severity:** CRITICAL/HIGH/MEDIUM/LOW (based on rubric scoring) +- **Issue:** Concise description with location (file paths from task list or proof artifact references) and evidence (proof artifact test results, file existence checks, coverage gaps) +- **Impact:** What breaks or cannot be verified (functionality | verification | traceability) +- **Recommendation:** Precise, actionable steps to resolve + +**Examples:** + +| Severity | Issue | Impact | Recommendation | +| --- | --- | --- | --- | +| HIGH | Proof Artifact URL returns 404. `task-list.md#L45` references `https://example.com/demo`. Evidence: `curl -I https://example.com/demo` → "HTTP/1.1 404 Not Found" | Functionality cannot be verified | Update URL in task list or deploy missing endpoint | +| CRITICAL | Changed file not in "Relevant Files". `src/auth.ts` created but not listed in task list. Evidence: `git log --name-only` shows file created; task list only references `src/user.ts` | Implementation scope creep | Update task list to include `src/auth.ts` or revert unauthorized changes | +| MEDIUM | Missing proof artifact for FR-2. Task list specifies test file `src/feature/x.test.ts` but file does not exist. Evidence: File check shows `src/feature/x.test.ts` missing | Requirement verification incomplete | Add test file `src/feature/x.test.ts` as specified in task list | + +**Note:** Do not report issues that are already clearly marked in the Coverage Matrix unless additional context is needed. Focus on actionable problems that need resolution. + +### 4) Evidence Appendix + +- Git commits analyzed with file changes +- Proof Artifact test results (outputs, screenshots) +- File comparison results (expected vs actual) +- Commands executed with results + +## Saving The Output + +After generation is complete: + +- Save the report using the specification below +- Verify the file was created successfully + +### Validation Report File Details + +**Format:** Markdown (`.md`) +**Location:** `./docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +**Filename:** `[NN]-validation-[feature-name].md` (e.g., if the Spec is `01-spec-user-authentication.md`, save as `01-validation-user-authentication.md`) +**Full Path:** `./docs/specs/[NN]-spec-[feature-name]/[NN]-validation-[feature-name].md` + +## What Comes Next + +Once validation is complete and all issues are resolved, the implementation is ready for merge. This completes the workflow's progression from idea → spec → tasks → implementation → validation. Instruct the user to do a final code review before merging the changes. + +--- + +**Validation Completed:** [Date+Time] +**Validation Performed By:** [AI Model] diff --git a/README.md b/README.md index 52f5481..a03a3a1 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,78 @@ uvx --from git+https://github.com/liatrio-labs/slash-command-manager \ Example of slash commands installed in Windsurf -#### Option B: Manual Copy-Paste (No Installation) +#### Option B: Install as Agent Skills (Claude Code & GitHub Copilot) + +Install these prompts as **Agent Skills** that AI assistants can autonomously invoke when relevant to your workflow. + +##### For Claude Code + +Clone this repository and copy the skills to your Claude Code skills directory: + +```bash +# Clone the repository (or use an existing clone) +git clone https://github.com/liatrio-labs/spec-driven-workflow.git +cd spec-driven-workflow + +# Copy skills to Claude Code's user skills directory +mkdir -p ~/.claude/skills +cp -r .claude/skills/* ~/.claude/skills/ + +# Or for project-specific skills, copy to your project +mkdir -p /path/to/your/project/.claude/skills +cp -r .claude/skills/* /path/to/your/project/.claude/skills/ +``` + +**What this does:** + +- Installs four SDD workflow skills that Claude Code can discover and invoke automatically +- Skills are available in Agent mode when Claude determines they're relevant +- Each skill includes the full workflow instructions and context verification markers + +**Skills installed:** + +- `sdd-1-generate-spec` - Generate specifications with workflow guidance +- `sdd-2-generate-task-list` - Convert specs into actionable task lists +- `sdd-3-manage-tasks` - Execute structured task implementation +- `sdd-4-validate-implementation` - Validate implementation against specs + +##### For GitHub Copilot + +The skills are already included in this repository in the `.github/skills/` directory, so they are **automatically available** when you clone or fork the repository. + +**To use in your own projects:** + +```bash +# Clone or download this repository +git clone https://github.com/liatrio-labs/spec-driven-workflow.git + +# Copy skills to your project +mkdir -p /path/to/your/project/.github +cp -r spec-driven-workflow/.github/skills /path/to/your/project/.github/ + +# Or add this repository to your organization's .github repo +# Place in {org}/.github/skills/ or {org}/.github-private/skills/ +``` + +**What this does:** + +- Makes SDD workflow skills available to GitHub Copilot agents in VS Code +- Skills appear in the Agent HQ and can be invoked by Copilot when relevant +- Works with Copilot's coding agent, CLI, and multi-agent orchestration + +**Skills installed:** + +- `sdd-1-generate-spec` - Generate specifications with workflow guidance +- `sdd-2-generate-task-list` - Convert specs into actionable task lists +- `sdd-3-manage-tasks` - Execute structured task implementation +- `sdd-4-validate-implementation` - Validate implementation against specs + +**Learn more:** + +- [Claude Code Agent Skills Documentation](https://code.claude.com/docs/en/skills) +- [GitHub Copilot Agent Skills Documentation](https://code.visualstudio.com/docs/copilot/customization/agent-skills) + +#### Option C: Manual Copy-Paste (No Installation) Copy the contents of a prompt file directly from `prompts/` and paste it into your AI chat. The AI will follow the structured instructions in the prompt.