diff --git a/AGENTS.md b/AGENTS.md index 2c34acf4..3b1dfeec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,11 +21,11 @@ When creating or modifying jobs in this repository, you MUST understand which ty - NEVER edit the installed copies in `.deepwork/jobs/` directly - After editing, run `deepwork install --platform claude` to sync -### 2. Library Jobs (`library_jobs/`) +### 2. Library Jobs (`library/jobs/`) **What they are**: Example or reusable jobs that any repository is welcome to use, but are NOT auto-installed. Users must explicitly copy or import these into their projects. -**Location**: `library_jobs/[job_name]/` +**Location**: `library/jobs/[job_name]/` **Examples** (potential): - Competitive research workflows @@ -34,7 +34,7 @@ When creating or modifying jobs in this repository, you MUST understand which ty - Release management **Editing rules**: -- Edit directly in `library_jobs/[job_name]/` +- Edit directly in `library/jobs/[job_name]/` - These are templates/examples for users to adopt - Should be well-documented and self-contained @@ -77,7 +77,7 @@ deepwork/ ├── src/deepwork/standard_jobs/ # Standard jobs (source of truth) │ ├── deepwork_jobs/ │ └── deepwork_rules/ -├── library_jobs/ # Library/example jobs +├── library/jobs/ # Library/example jobs │ └── [example_job]/ └── .deepwork/jobs/ # Installed standard jobs + bespoke jobs ├── deepwork_jobs/ # ← Installed copy, NOT source of truth diff --git a/claude.md b/claude.md index a90782ca..07d4b325 100644 --- a/claude.md +++ b/claude.md @@ -47,7 +47,7 @@ deepwork/ │ │ └── deepwork_rules/ │ ├── schemas/ # Job definition schemas │ └── utils/ # Utilities (fs, git, yaml, validation) -├── library_jobs/ # Reusable example jobs (not auto-installed) +├── library/jobs/ # Reusable example jobs (not auto-installed) ├── tests/ # Test suite ├── doc/ # Documentation └── doc/architecture.md # Detailed architecture document @@ -191,7 +191,7 @@ my-project/ | Type | Location | Purpose | |------|----------|---------| | **Standard Jobs** | `src/deepwork/standard_jobs/` | Framework core, auto-installed to users | -| **Library Jobs** | `library_jobs/` | Reusable examples users can adopt | +| **Library Jobs** | `library/jobs/` | Reusable examples users can adopt | | **Bespoke Jobs** | `.deepwork/jobs/` (if not in standard_jobs) | This repo's internal workflows only | ### Editing Standard Jobs @@ -218,7 +218,7 @@ Instead, follow this workflow: ### How to Identify Job Types - **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_rules`) -- **Library jobs**: Exist in `library_jobs/` +- **Library jobs**: Exist in `library/jobs/` - **Bespoke jobs**: Exist ONLY in `.deepwork/jobs/` with no corresponding standard_jobs entry **When creating a new job, always clarify which type it should be.** If uncertain, ask the user. diff --git a/job_library/README.md b/library/jobs/README.md similarity index 99% rename from job_library/README.md rename to library/jobs/README.md index e6cbd4d2..4c49bb02 100644 --- a/job_library/README.md +++ b/library/jobs/README.md @@ -15,7 +15,7 @@ The job library provides: Each job in this library follows the same structure as the `.deepwork/jobs` subfolders in your local project: ``` -job_library/ +library/jobs/ ├── [job-name]/ │ ├── job.yml # Job definition (name, steps, dependencies) │ └── steps/ diff --git a/library/jobs/spec_driven_development/job.yml b/library/jobs/spec_driven_development/job.yml new file mode 100644 index 00000000..cd442feb --- /dev/null +++ b/library/jobs/spec_driven_development/job.yml @@ -0,0 +1,177 @@ +name: spec_driven_development +version: "1.0.0" +summary: "Spec-driven development workflow that turns specifications into working implementations through structured planning." +description: | + A comprehensive workflow inspired by GitHub's spec-kit that enables "spec-driven development" - + a methodology where executable specifications generate working implementations rather than + merely guiding them. + + This job inverts traditional development: instead of starting with code, you first create + detailed specifications that directly generate implementations. The workflow progresses through + six phases: + + 1. **Constitution**: Establish project governance principles and development guidelines + 2. **Specification**: Define functional requirements focusing on "what" and "why" + 3. **Clarification**: Resolve ambiguities before technical planning + 4. **Planning**: Create technical implementation strategy and architecture + 5. **Task Generation**: Break plans into actionable, ordered development tasks + 6. **Implementation**: Execute tasks to deliver the complete feature + + The workflow produces all artifacts in a `specs/[feature-name]/` directory structure, + keeping specifications versioned alongside the implementation they generate. + + Ideal for: + - New feature development requiring upfront design + - Complex features with multiple stakeholders + - Projects where specification quality directly impacts implementation success + - Teams wanting to capture design decisions for future reference + +changelog: + - version: "1.0.0" + changes: "Initial version based on GitHub spec-kit workflow" + +steps: + - id: constitution + name: "Establish Constitution" + description: "Creates foundational governance principles and development guidelines for the project. Use when starting a new project or establishing standards." + instructions_file: steps/constitution.md + inputs: + - name: development_priorities + description: "Key priorities like code quality, testing, UX consistency, performance" + outputs: + - file: "[docs_folder]/constitution.md" + dependencies: [] + quality_criteria: + - "**Priorities Captured**: Did the agent gather specific development priorities from the user?" + - "**Principles Defined**: Are governance principles clear and actionable?" + - "**Technology Guidance**: Does the constitution include relevant technology stack preferences?" + - "**Quality Standards**: Are quality standards and testing expectations defined?" + - "**File Created**: Has constitution.md been created in the project's documentation folder?" + + - id: specify + name: "Create Specification" + description: "Defines functional requirements as user stories without technology choices. Use when starting to design a new feature." + instructions_file: steps/specify.md + inputs: + - name: feature_name + description: "Name of the feature being specified (lowercase, hyphens for spaces)" + - name: feature_description + description: "High-level description of what the feature should do" + - file: "[docs_folder]/constitution.md" + from_step: constitution + outputs: + - file: specs/[feature-name]/spec.md + dependencies: + - constitution + quality_criteria: + - "**User Stories Complete**: Are all user stories written in standard format (As a... I want... So that...)?" + - "**Acceptance Criteria**: Does each story have clear, testable acceptance criteria?" + - "**Non-Functional Requirements**: Are performance, security, and accessibility requirements captured?" + - "**Scope Boundaries**: Is it clear what's in and out of scope?" + - "**Constitution Aligned**: Does the spec respect the governance principles from the constitution?" + - "**Technology Agnostic**: Is the spec free of implementation details and technology choices?" + - "**File Created**: Has spec.md been created in `specs/[feature-name]/`?" + + - id: clarify + name: "Clarify Specification" + description: "Resolves ambiguities and gaps in the specification through structured questioning. Use after specification to ensure completeness." + instructions_file: steps/clarify.md + inputs: + - file: specs/[feature-name]/spec.md + from_step: specify + outputs: + - file: specs/[feature-name]/spec.md + dependencies: + - specify + quality_criteria: + - "**Ambiguities Identified**: Were underspecified areas systematically identified?" + - "**Questions Asked**: Did the agent ask structured questions to resolve each ambiguity?" + - "**Answers Documented**: Are clarification answers recorded in the spec document?" + - "**Edge Cases Covered**: Are edge cases and error scenarios now defined?" + - "**Acceptance Checklist**: Is the acceptance criteria checklist complete and validated?" + - "**Spec Updated**: Has spec.md been updated with all clarifications?" + + - id: plan + name: "Generate Technical Plan" + description: "Creates technical implementation strategy including architecture and technology choices. Use after specification is clarified." + instructions_file: steps/plan.md + inputs: + - file: specs/[feature-name]/spec.md + from_step: clarify + - file: "[docs_folder]/constitution.md" + from_step: constitution + - file: "[docs_folder]/architecture.md" + description: "Existing project architecture document (if present)" + outputs: + - file: specs/[feature-name]/plan.md + - file: specs/[feature-name]/data-model.md + - file: specs/[feature-name]/api-spec.json + - file: specs/[feature-name]/research.md + - file: "[docs_folder]/architecture.md" + description: "Updated project architecture document" + dependencies: + - clarify + quality_criteria: + - "**Architecture Defined**: Is the high-level architecture clearly described?" + - "**Technology Justified**: Are technology choices explained with rationale?" + - "**Data Model Complete**: Is the data model documented with all entities and relationships?" + - "**API Contracts**: Are API endpoints defined with request/response schemas?" + - "**Research Documented**: Are any research findings or technology evaluations captured?" + - "**Dependencies Listed**: Are external dependencies and their versions specified?" + - "**Constitution Respected**: Does the plan align with governance principles?" + - "**Architecture Doc Updated**: Has the project architecture document been reviewed and updated if needed?" + - "**Files Created**: Have all output files been created in `specs/[feature-name]/`?" + + - id: tasks + name: "Generate Task Breakdown" + description: "Converts the implementation plan into actionable, ordered development tasks. Use after plan is validated." + instructions_file: steps/tasks.md + inputs: + - file: specs/[feature-name]/plan.md + from_step: plan + - file: specs/[feature-name]/spec.md + from_step: clarify + - file: "[docs_folder]/architecture.md" + from_step: plan + outputs: + - file: specs/[feature-name]/tasks.md + dependencies: + - plan + quality_criteria: + - "**User Story Organization**: Are tasks organized by user story?" + - "**Dependencies Sequenced**: Are task dependencies correctly ordered?" + - "**Parallel Tasks Marked**: Are parallelizable tasks identified with [P] markers?" + - "**File Paths Specified**: Does each task specify which files it creates/modifies?" + - "**TDD Structure**: Are test tasks included before or alongside implementation tasks?" + - "**Checkpoints Defined**: Are validation checkpoints included between phases?" + - "**Granularity Appropriate**: Are tasks small enough to be completed in one session?" + - "**File Created**: Has tasks.md been created in `specs/[feature-name]/`?" + + - id: implement + name: "Execute Implementation" + description: "Generates code and assets by executing the task breakdown. Use when ready to build the feature." + instructions_file: steps/implement.md + inputs: + - file: specs/[feature-name]/tasks.md + from_step: tasks + - file: specs/[feature-name]/plan.md + from_step: plan + - file: specs/[feature-name]/spec.md + from_step: clarify + - file: "[docs_folder]/architecture.md" + from_step: plan + outputs: + - directory: src/ + description: "Implementation source files as specified in tasks" + - directory: tests/ + description: "Test files as specified in tasks" + dependencies: + - tasks + quality_criteria: + - "**Prerequisites Met**: Were all spec/plan/tasks artifacts validated before starting?" + - "**Task Order Followed**: Were tasks executed in dependency order?" + - "**Tests Written**: Are tests created alongside or before implementation?" + - "**Acceptance Criteria Met**: Does the implementation satisfy all acceptance criteria from spec?" + - "**Code Quality**: Does the code meet the standards defined in the constitution?" + - "**Progress Tracked**: Was progress communicated throughout implementation?" + - "**All Tasks Complete**: Have all tasks in tasks.md been completed?" diff --git a/library/jobs/spec_driven_development/readme.md b/library/jobs/spec_driven_development/readme.md new file mode 100644 index 00000000..85049378 --- /dev/null +++ b/library/jobs/spec_driven_development/readme.md @@ -0,0 +1,51 @@ +# Spec-Driven Development + +A structured workflow for building features through executable specifications rather than ad-hoc coding. + +## Overview + +This job implements "spec-driven development" - a methodology where detailed specifications directly generate working implementations. Instead of jumping straight to code, you first create specifications that serve as executable blueprints. + +The workflow progresses through six steps: + +1. **Constitution** - Establish project governance principles, technology standards, and quality guidelines +2. **Specify** - Define functional requirements as user stories with acceptance criteria (what and why, not how) +3. **Clarify** - Resolve ambiguities and gaps through systematic questioning +4. **Plan** - Design architecture, select technologies, define data models and API contracts; update project architecture document +5. **Tasks** - Break the plan into ordered, actionable development tasks +6. **Implement** - Execute tasks to deliver the complete feature + +## When to Use + +This workflow is ideal for: +- New feature development requiring upfront design +- Complex features with multiple stakeholders +- Projects where specification quality directly impacts implementation success +- Teams wanting to capture design decisions for future reference + +## Artifacts Produced + +- `[docs_folder]/constitution.md` - Project-wide governance principles (created once) +- `[docs_folder]/architecture.md` - Project architecture document (updated with each feature) +- `specs/[feature-name]/spec.md` - Feature requirements and user stories +- `specs/[feature-name]/plan.md` - Technical architecture and implementation strategy +- `specs/[feature-name]/data-model.md` - Database schema and relationships +- `specs/[feature-name]/api-spec.json` - OpenAPI specification (if applicable) +- `specs/[feature-name]/tasks.md` - Ordered task breakdown with dependencies + +## Credits + +This job is inspired by [spec-kit](https://github.com/github/spec-kit), GitHub's open-source toolkit for spec-driven development. The workflow structure, step progression, and core concepts are adapted from spec-kit's methodology. + +## IMPT: REQUIRED CUSTOMIZATION + +When installing this job to a new project, you must customize the following: + +### Replace `[docs_folder]` + +The placeholder `[docs_folder]` appears throughout this job and must be replaced with your project's actual documentation directory path. This can be done with find / sed commands. + +**Examples:** +- If your docs are in `docs/`: replace `[docs_folder]` with `docs` +- If your docs are in `documentation/`: replace `[docs_folder]` with `documentation` +- If your docs are at the root: replace `[docs_folder]/constitution.md` with `constitution.md` diff --git a/library/jobs/spec_driven_development/steps/clarify.md b/library/jobs/spec_driven_development/steps/clarify.md new file mode 100644 index 00000000..5d8d53da --- /dev/null +++ b/library/jobs/spec_driven_development/steps/clarify.md @@ -0,0 +1,263 @@ +# Clarify Specification + +## Objective + +Resolve ambiguities, fill gaps, and validate completeness of the specification through systematic questioning. The goal is to ensure the spec is detailed enough for technical planning. + +## Task + +Review the existing specification, identify underspecified areas, and ask structured questions to resolve them. Update the spec.md with clarifications. + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. + +**Critical**: This step refines requirements, not implementation. Do not add code examples or technical solutions. Keep clarifications focused on user needs, acceptance criteria, and behavior - not how things will be coded. + +### Prerequisites + +Before starting, verify: +1. The specification exists at `specs/[feature-name]/spec.md` +2. Read the specification thoroughly + +If no specification exists, inform the user they should run `/spec_driven_development.specify` first. + +### Step 1: Identify the Feature + +Ask the user which feature specification to clarify: + +``` +Which feature specification would you like to clarify? +``` + +If they provide a name, look for `specs/[feature-name]/spec.md`. + +### Step 2: Analyze for Ambiguities + +Read the specification and identify gaps in these categories: + +1. **Underspecified User Stories** + - Stories missing acceptance criteria + - Vague or unmeasurable criteria + - Missing edge case definitions + +2. **Unclear Requirements** + - Requirements with ambiguous language ("fast", "user-friendly", "secure") + - Missing quantitative thresholds + - Undefined terms or jargon + +3. **Missing Scenarios** + - Error handling not defined + - Edge cases not covered + - Multi-user scenarios not addressed + +4. **Integration Gaps** + - Undefined interactions with other features + - Missing data flow definitions + - Unclear state transitions + +5. **Open Questions** + - Any questions listed in the "Open Questions" section + - Implicit assumptions that need validation + +### Step 3: Systematic Clarification + +For each ambiguity identified, ask structured questions: + +**Format your questions systematically:** + +``` +I've identified [N] areas that need clarification in your specification. + +**Ambiguity 1: [Category] - [Brief Description]** + +The spec says: "[Quote from spec]" + +This is ambiguous because: [Explanation] + +Question: [Specific clarifying question] + +Options: +- [Option A with implications] +- [Option B with implications] +- [Other - user can specify] +``` + +**Question best practices:** +- One topic per question +- Provide options when possible +- Explain implications of each option +- Reference specific parts of the spec + +### Step 4: Validate Edge Cases + +For each user story, ensure edge cases are covered: + +1. **What happens if the user...** + - Provides invalid input? + - Cancels midway? + - Loses connection? + - Times out? + +2. **What happens when...** + - The system is under load? + - Required data is missing? + - External services are unavailable? + +3. **What about...** + - First-time users vs returning users? + - Different user permission levels? + - Concurrent access scenarios? + +### Step 5: Update the Specification + +After gathering clarifications, update `specs/[feature-name]/spec.md`: + +1. **Add a Clarifications section:** + ```markdown + ## Clarifications + + ### [Date] Clarification Session + + **Q1: [Original question]** + A: [Answer received] + Impact: [How this affects the spec] + + **Q2: [Original question]** + A: [Answer received] + Impact: [How this affects the spec] + ``` + +2. **Update affected sections:** + - Refine vague acceptance criteria with specific thresholds + - Add missing edge cases to user stories + - Update non-functional requirements with concrete numbers + - Remove or resolve open questions + +3. **Mark resolved questions:** + - Move resolved items from "Open Questions" to "Clarifications" + - Add any new questions discovered during clarification + +### Step 6: Validate Acceptance Checklist + +Create or update an acceptance checklist: + +```markdown +## Acceptance Checklist + +### User Stories +- [ ] All stories have 3+ acceptance criteria +- [ ] All criteria are testable/measurable +- [ ] Edge cases are documented + +### Requirements +- [ ] Performance thresholds defined (response times, throughput) +- [ ] Security requirements are specific +- [ ] Accessibility standards identified + +### Scope +- [ ] In-scope items are detailed +- [ ] Out-of-scope items are explicit +- [ ] Assumptions are documented + +### Completeness +- [ ] No open questions remain +- [ ] All ambiguities resolved +- [ ] Ready for technical planning +``` + +## Example Dialog + +``` +Claude: I'll help clarify the specification. Which feature would you like to work on? + +User: user-authentication + +Claude: Let me review the spec at `specs/user-authentication/spec.md`... + +[Reads specification] + +I've identified 4 areas that need clarification: + +**Ambiguity 1: Performance - "Quick signup flow"** + +The spec says: "The whole flow should take under a minute" + +This is ambiguous because: It's unclear if this refers to user time, system response time, +or includes email verification. + +What does "under a minute" mean for the signup flow? + +[Uses AskUserQuestion with options: +- User can complete form in under 1 minute (not including email verification) +- System processes signup in under 1 minute (including sending verification email) +- End-to-end including email verification click +- Other] + +User: User can complete form in under 1 minute, not including verification + +Claude: Got it. I'll update the spec to say: +"Users can complete the signup form within 60 seconds. Email verification is asynchronous +and not included in this timing." + +**Ambiguity 2: Security - "Email verification required"** + +The spec doesn't define what happens if verification isn't completed. + +What should happen to unverified accounts? + +[Uses AskUserQuestion with options: +- Allow limited access for 24 hours, then restrict +- No access until verified +- Full access but with reminder prompts +- Other] + +User: Allow limited access for 24 hours + +Claude: What does "limited access" mean? What can unverified users do vs not do? + +[Continues clarification...] + +After resolving all ambiguities: + +✓ Specification clarified! + +**Updates made to** specs/user-authentication/spec.md: +- Added 4 clarifications with answers +- Updated 3 acceptance criteria with specific thresholds +- Added 5 edge cases to user stories +- Resolved all open questions + +**Acceptance checklist:** All items complete ✓ + +**Next step:** +Run `/spec_driven_development.plan` to create the technical implementation plan. +``` + +## Output Format + +### Updated specs/[feature-name]/spec.md + +The specification file updated with: +- Clarifications section with Q&A +- Refined acceptance criteria +- Additional edge cases +- Resolved open questions +- Acceptance checklist (all items checked) + +**Location**: `specs/[feature-name]/spec.md` (same file, updated) + +After updating the file: +1. Summarize the clarifications made +2. Confirm the acceptance checklist is complete +3. Tell the user to run `/spec_driven_development.plan` to create the technical plan + +## Quality Criteria + +- All ambiguities in the spec were identified +- Structured questions were asked for each ambiguity +- Answers are documented in Clarifications section +- Acceptance criteria now have specific, measurable thresholds +- Edge cases are comprehensively covered +- Open questions are resolved +- Acceptance checklist is complete +- Spec is ready for technical planning +- **No implementation code**: Clarifications describe behavior, not code diff --git a/library/jobs/spec_driven_development/steps/constitution.md b/library/jobs/spec_driven_development/steps/constitution.md new file mode 100644 index 00000000..11ab7c70 --- /dev/null +++ b/library/jobs/spec_driven_development/steps/constitution.md @@ -0,0 +1,241 @@ +# Establish Constitution + +## Objective + +Create a foundational governance document (`constitution.md`) that establishes project principles, development guidelines, and quality standards that will guide all subsequent specification and implementation work. + +## Task + +Guide the user through defining their project's constitution by asking structured questions about their development priorities, quality standards, and governance preferences. + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. + +**Critical**: This step captures principles and standards, not implementation code. The constitution describes what technologies and patterns to use, not how to code them. Do not include code examples - those belong only in the implement step. + +### Step 1: Understand Development Priorities + +Ask structured questions to understand the project's core values: + +1. **What are your top development priorities?** (Select all that apply) + - Code quality and maintainability + - Test coverage and reliability + - Performance and scalability + - Security and data protection + - UX consistency and accessibility + - Developer experience and productivity + - Documentation quality + +2. **What's the primary nature of this project?** + - New greenfield development + - Adding features to existing codebase + - Refactoring/modernization effort + - Prototype/experimental work + +3. **Who are the stakeholders?** + - Who will review specifications? + - Who will review code? + - Who are the end users? + +### Step 2: Define Technology Preferences + +Gather technology stack information: + +1. **What's your preferred technology stack?** + - Languages (e.g., TypeScript, Python, Go) + - Frameworks (e.g., React, Django, FastAPI) + - Databases (e.g., PostgreSQL, MongoDB, SQLite) + - Infrastructure (e.g., AWS, GCP, self-hosted) + +2. **What are your testing preferences?** + - Unit testing framework preferences + - Integration testing approach + - E2E testing tools (if applicable) + - Required coverage thresholds + +3. **What coding standards do you follow?** + - Style guides (e.g., Airbnb, Google, PEP 8) + - Linting/formatting tools + - Code review requirements + +### Step 3: Establish Quality Standards + +Define what "good" looks like: + +1. **What are your code quality requirements?** + - Type safety requirements + - Documentation requirements (JSDoc, docstrings, etc.) + - Maximum complexity thresholds + - Required patterns (e.g., dependency injection, SOLID) + +2. **What are your testing requirements?** + - Minimum test coverage percentage + - Required test types (unit, integration, e2e) + - Performance benchmarks + +3. **What are your security requirements?** + - Authentication/authorization standards + - Data handling requirements + - Compliance needs (GDPR, HIPAA, etc.) + +### Step 4: Define Governance Rules + +Establish how the project will be managed: + +1. **What's your branching strategy?** + - Main branch protection rules + - Feature branch naming conventions + - PR/MR requirements + +2. **What are your review requirements?** + - Number of required reviewers + - Who can approve what types of changes + - Automated checks that must pass + +3. **How should specifications be maintained?** + - When should specs be updated? + - Who owns spec maintenance? + - How are spec changes tracked? + +### Step 5: Create the Constitution File + +After gathering all information, create the constitution document. + +**Create the constitution file** at `[docs_folder]/constitution.md`: + +```markdown +# Project Constitution + +## Overview + +[Brief description of the project and its purpose] + +## Development Priorities + +[Ordered list of priorities gathered from Step 1] + +1. [Top priority] +2. [Second priority] +... + +## Technology Stack + +### Languages +- [Primary language]: [Version] + +### Frameworks +- [Framework]: [Version] + +### Databases +- [Database]: [Purpose] + +### Infrastructure +- [Platform]: [Services used] + +## Quality Standards + +### Code Quality +- [Standard 1] +- [Standard 2] + +### Testing Requirements +- Minimum coverage: [X]% +- Required test types: [List] + +### Security Requirements +- [Requirement 1] +- [Requirement 2] + +## Governance + +### Branching Strategy +[Description] + +### Review Requirements +- Required reviewers: [Number] +- Required checks: [List] + +### Specification Maintenance +[How specs should be updated and tracked] + +## Principles + +[3-5 guiding principles that should inform all development decisions] + +1. **[Principle Name]**: [Description] +2. **[Principle Name]**: [Description] +... +``` + +## Example Dialog + +``` +Claude: I'll help you establish a constitution for your project. This will define the governance +principles and development guidelines that will guide all specifications and implementations. + +Let's start with your development priorities. What matters most to you? + +[Uses AskUserQuestion with multi-select options for priorities] + +User: [Selects: Code quality, Test coverage, Security] + +Claude: Great choices. Now let me understand your technology preferences. + +What's your primary language and framework? + +User: We're using TypeScript with Next.js and PostgreSQL + +Claude: Perfect. What are your testing requirements? Do you have specific coverage thresholds +or required test types? + +User: We need 80% coverage minimum, with unit tests for all business logic and integration +tests for API endpoints. + +Claude: Got it. What about security? Are there specific compliance requirements or security +standards you need to follow? + +User: We handle user data, so GDPR compliance is important. All data must be encrypted at +rest and in transit. + +[Continues gathering information...] + +Claude: Based on our conversation, here's the constitution I've created: + +[Shows constitution content] + +✓ Constitution established! + +**File created:** +- [docs_folder]/constitution.md + +**Next step:** +Run `/spec_driven_development.specify` to create your first feature specification. +``` + +## Output Format + +### [docs_folder]/constitution.md + +A markdown document containing: +- Project overview +- Prioritized development values +- Technology stack with versions +- Quality standards and thresholds +- Governance rules and processes +- Guiding principles + +**Location**: `[docs_folder]/constitution.md` + +After creating the file: +1. Summarize the key principles established +2. Confirm the file has been created +3. Tell the user to run `/spec_driven_development.specify` to create their first feature specification + +## Quality Criteria + +- Asked structured questions to understand user priorities +- Technology preferences are specific and versioned +- Quality standards include measurable thresholds +- Governance rules are actionable +- Principles are clear and will guide future decisions +- File created in correct location +- **No implementation code**: Constitution describes standards, not code examples diff --git a/library/jobs/spec_driven_development/steps/implement.md b/library/jobs/spec_driven_development/steps/implement.md new file mode 100644 index 00000000..827a26d9 --- /dev/null +++ b/library/jobs/spec_driven_development/steps/implement.md @@ -0,0 +1,382 @@ +# Execute Implementation + +## Objective + +Execute the task breakdown to generate working code that implements the feature specification. Tasks are executed in dependency order, with progress tracked throughout. + +## Task + +Systematically work through each task in `tasks.md`, implementing the feature according to the specification and plan. + +### Prerequisites + +Before starting, verify ALL prerequisite files exist: + +1. `[docs_folder]/constitution.md` - Project principles +2. `[docs_folder]/architecture.md` - Project architecture document +3. `specs/[feature-name]/spec.md` - Requirements and acceptance criteria +4. `specs/[feature-name]/plan.md` - Architecture and technology choices +5. `specs/[feature-name]/tasks.md` - Task breakdown + +**If any file is missing**, inform the user which step they need to complete first. Do NOT proceed without all artifacts. + +### Step 1: Identify the Feature + +Ask the user which feature to implement: + +``` +Which feature would you like to implement? +``` + +Load and review all specification artifacts. + +### Step 2: Validate Prerequisites + +Before implementing, verify: + +1. **Specification is complete** + - All user stories have acceptance criteria + - No open questions remain + - Scope is clearly defined + +2. **Plan is actionable** + - Architecture is defined + - Technology choices are made + - Data model is specified + +3. **Tasks are ready** + - Tasks are properly sequenced + - Dependencies are clear + - Checkpoints are defined + +If validation fails, inform the user what needs to be addressed. + +### Step 3: Setup Progress Tracking + +Create or update progress tracking in tasks.md: + +```markdown +## Implementation Progress + +**Started**: [Date/Time] +**Current Phase**: 1 of 4 +**Tasks Completed**: 0 of 18 + +| Task | Status | Notes | +|------|--------|-------| +| 1 | ⏳ Pending | | +| 2 | ⏳ Pending | | +... +``` + +**Status indicators:** +- ⏳ Pending +- 🔄 In Progress +- ✅ Complete +- ⚠️ Blocked +- ❌ Failed + +### Step 4: Execute Tasks + +For each task in order: + +1. **Announce the task:** + ``` + Starting Task [N]: [Title] + Type: [Type] + Dependencies: [Met/Pending] + ``` + +2. **Verify dependencies are met:** + - Check all prerequisite tasks are complete + - If not, skip and note as blocked + +3. **Implement the task:** + - Follow the task description + - Create/modify specified files + - Use constitution guidelines for code quality + +4. **Validate completion:** + - Check all acceptance criteria + - Run specified validation commands + - Fix any issues before proceeding + +5. **Update progress:** + ``` + ✅ Task [N] Complete + Files created/modified: + - path/to/file.ts + - path/to/another.ts + ``` + +### Step 5: Handle Checkpoints + +At each checkpoint: + +1. **Stop and validate:** + ``` + 📍 Checkpoint: [Name] + + Validating: + - [ ] [Criterion 1] + - [ ] [Criterion 2] + ``` + +2. **Run validation commands:** + - Execute tests + - Run linting + - Check build + +3. **Report status:** + ``` + Checkpoint [Name]: ✅ PASSED + All criteria met. Proceeding to Phase [N]. + ``` + + OR + + ``` + Checkpoint [Name]: ❌ FAILED + Issues found: + - [Issue 1] + - [Issue 2] + + Addressing issues before proceeding... + ``` + +4. **Do not proceed until checkpoint passes** + +### Step 6: Handle Parallel Tasks + +When encountering parallel tasks: + +1. **Identify the parallel group:** + ``` + Tasks 5 and 6 can run in parallel. + Implementing Task 5... + ``` + +2. **Complete all parallel tasks before moving to dependents:** + ``` + ✅ Task 5 Complete + ✅ Task 6 Complete + + Both parallel tasks complete. Proceeding to Task 7. + ``` + +### Step 7: Handle Issues + +When problems occur: + +1. **Document the issue:** + ``` + ⚠️ Issue in Task [N]: + [Description of the problem] + ``` + +2. **Attempt resolution:** + - If fixable, fix it + - If needs clarification, ask user + - If blocked by external factor, mark as blocked + +3. **Update task status:** + ```markdown + | 7 | ⚠️ Blocked | Waiting for API credentials | + ``` + +4. **Continue with non-dependent tasks:** + - Skip blocked tasks + - Proceed with independent tasks + - Return to blocked tasks when resolved + +### Step 8: Verify Acceptance Criteria + +After all tasks complete: + +1. **Review specification acceptance criteria:** + - Go through each user story + - Verify all criteria are met + - Document any gaps + +2. **Run full test suite:** + ```bash + npm test + npm run lint + npm run build + ``` + +3. **Final validation:** + ``` + ## Implementation Complete + + **Acceptance Criteria Verification:** + + US-1: [Story Title] + - [x] [Criterion 1] - Implemented in src/auth/signup.ts + - [x] [Criterion 2] - Tested in tests/auth/signup.test.ts + + US-2: [Story Title] + - [x] [Criterion 1] - Implemented in src/auth/login.ts + ... + ``` + +### Step 9: Final Report + +Produce a completion report: + +```markdown +## Implementation Summary + +**Feature**: [Feature Name] +**Completed**: [Date/Time] + +### Statistics +- Total Tasks: [N] +- Completed: [N] +- Blocked: [N] +- Duration: [Time] + +### Files Created +- `src/auth/signup.ts` - Signup endpoint +- `src/auth/login.ts` - Login endpoint +... + +### Files Modified +- `src/routes/index.ts` - Added auth routes +... + +### Tests Added +- `tests/auth/signup.test.ts` - 8 tests +- `tests/auth/login.test.ts` - 6 tests +... + +### Acceptance Criteria Status +- US-1: ✅ All criteria met +- US-2: ✅ All criteria met +- US-3: ⚠️ 1 criterion deferred (noted in spec) + +### Notes +[Any important observations or follow-up items] +``` + +## Example Dialog + +``` +Claude: I'll implement the feature. Which one are you working on? + +User: user-authentication + +Claude: Let me verify all prerequisites... + +✅ Constitution exists +✅ Specification complete (5 user stories, all clarified) +✅ Plan complete (architecture, data model, API spec) +✅ Tasks complete (18 tasks across 4 phases) + +Starting implementation... + +--- + +**Phase 1: Database** + +Starting Task 1: Create users migration +Type: Database +Dependencies: None + +Creating migration file... + +[Creates migrations/001_create_users.sql] + +Running migration validation... + +✅ Task 1 Complete +Files created: +- migrations/001_create_users.sql + +--- + +Starting Task 2: Create OAuth connections migration [P] +Type: Database +Dependencies: Task 1 + +[Creates migrations/002_create_oauth_connections.sql] + +✅ Task 2 Complete + +--- + +📍 Checkpoint: Database Layer Complete + +Validating: +- [x] All migrations run successfully +- [x] Tables created with correct schema +- [x] Indexes are in place + +Running: `npm run db:migrate` + +Checkpoint Database Layer: ✅ PASSED + +--- + +**Phase 2: Backend API** + +Starting Task 3: Implement password hashing utility +Type: Backend +Dependencies: None + +[Creates src/utils/password.ts] + +Running tests... + +✅ Task 3 Complete +Files created: +- src/utils/password.ts +- tests/utils/password.test.ts + +--- + +[Continues through all tasks...] + +--- + +## Implementation Complete! + +**Statistics:** +- Total Tasks: 18 +- Completed: 18 +- Blocked: 0 + +**Acceptance Criteria:** +All 5 user stories have all criteria met. + +**Files Created:** 14 +**Tests Added:** 24 tests, all passing + +The user-authentication feature is ready for review. +``` + +## Output Format + +This step produces working code: +- Source files as specified in tasks +- Test files alongside implementation +- Configuration as needed + +Progress is tracked by updating `specs/[feature-name]/tasks.md` with status. + +After completion: +1. Summarize what was implemented +2. List all files created/modified +3. Confirm all acceptance criteria are met +4. Note any issues or follow-up items + +## Quality Criteria + +- All prerequisite artifacts were validated before starting +- Tasks were executed in correct dependency order +- Checkpoints were validated before proceeding +- Code follows constitution guidelines +- Tests were written alongside implementation +- All acceptance criteria from spec are met +- Progress was tracked throughout +- Final report summarizes implementation diff --git a/library/jobs/spec_driven_development/steps/plan.md b/library/jobs/spec_driven_development/steps/plan.md new file mode 100644 index 00000000..1d4c6b6e --- /dev/null +++ b/library/jobs/spec_driven_development/steps/plan.md @@ -0,0 +1,391 @@ +# Generate Technical Plan + +## Objective + +Create a comprehensive technical implementation plan that defines architecture, technology choices, data models, and API contracts. This is where "how" decisions are made, guided by the specification ("what") and constitution (principles). + +## Task + +Analyze the clarified specification and create detailed technical planning documents that will guide implementation. + +**Important**: Use the AskUserQuestion tool to ask structured questions when technology choices need user input. + +**Critical**: This step produces planning documents, NOT implementation code. Do not write actual code - that happens in the implement step. You may include: +- API contracts (endpoints, request/response schemas) +- Data model schemas (tables, fields, relationships) +- Architecture diagrams (text-based) +- Technology selection rationale + +Do NOT include: +- Actual implementation code (functions, classes, logic) +- Code snippets showing "how to implement" something +- Sample implementations or starter code + +### Prerequisites + +Before starting, verify these files exist and read them: +1. `[docs_folder]/constitution.md` - Project principles and technology preferences +2. `specs/[feature-name]/spec.md` - Clarified specification with all requirements +3. `[docs_folder]/architecture.md` - Existing project architecture document (if present) + +If the constitution or spec is missing, inform the user which step they need to complete first. The architecture document may not exist yet for new projects - that's okay, you'll create it. + +### Step 1: Identify the Feature + +Ask the user which feature to plan: + +``` +Which feature would you like to create a technical plan for? +``` + +If they provide a name, verify `specs/[feature-name]/spec.md` exists and has been clarified (has a Clarifications section and complete acceptance checklist). + +### Step 2: Architecture Design + +Analyze the specification and design the high-level architecture: + +1. **Component Identification** + - What major components are needed? + - How do they interact? + - What are the boundaries between components? + +2. **Integration Points** + - What external systems must this integrate with? + - What APIs will be consumed? + - What APIs will be exposed? + +3. **Data Flow** + - How does data move through the system? + - What transformations occur? + - Where is data persisted? + +**Ask for input when:** +- Multiple valid architectural approaches exist +- Trade-offs need user decision (e.g., simplicity vs scalability) +- Constitution doesn't specify a preference + +### Step 3: Technology Selection + +Based on the constitution and requirements, select specific technologies: + +1. **Framework/Library Choices** + - What frameworks best fit the requirements? + - Are there existing patterns in the codebase to follow? + - What libraries are needed for specific functionality? + +2. **Database Design** + - What database(s) are appropriate? + - What's the data model strategy (relational, document, etc.)? + - What indexing/performance considerations exist? + +3. **Infrastructure Considerations** + - What hosting/deployment approach? + - What caching strategy (if needed)? + - What monitoring/observability needs? + +**Document rationale for each choice:** +```markdown +### [Technology] Selection + +**Chosen**: [Technology name and version] +**Alternatives Considered**: [Other options] +**Rationale**: [Why this was selected] +**Constitution Alignment**: [How it aligns with project principles] +``` + +### Step 4: Data Model Design + +Create a comprehensive data model: + +1. **Entities** + - What data entities are needed? + - What are their attributes? + - What are the relationships? + +2. **Schema Design** + ```markdown + ### [Entity Name] + + | Field | Type | Constraints | Description | + |-------|------|-------------|-------------| + | id | UUID | PK | Unique identifier | + | ... | ... | ... | ... | + + **Relationships:** + - [Relationship description] + + **Indexes:** + - [Index description and purpose] + ``` + +3. **Data Lifecycle** + - How is data created, updated, deleted? + - What are the retention policies? + - How is data migrated/versioned? + +### Step 5: API Design + +Define the API contracts: + +1. **Endpoint Design** + ```markdown + ### [Operation Name] + + **Endpoint**: `[METHOD] /api/v1/[resource]` + **Description**: [What it does] + **Authentication**: [Required/Optional, type] + + **Request:** + ```json + { + "field": "type - description" + } + ``` + + **Response (200):** + ```json + { + "field": "type - description" + } + ``` + + **Error Responses:** + - 400: [When/why] + - 401: [When/why] + - 404: [When/why] + ``` + +2. **Create OpenAPI/JSON Schema** (if applicable) + - Generate `api-spec.json` with full endpoint definitions + +### Step 6: Research Documentation + +Document any research performed: + +1. **Technology Evaluations** + - What options were researched? + - What were the findings? + - What benchmarks were run (if any)? + +2. **Pattern Research** + - What design patterns were considered? + - What examples were referenced? + - What best practices were identified? + +3. **Risk Assessment** + - What technical risks exist? + - What mitigations are planned? + +### Step 7: Review and Update Project Architecture + +Review the existing project architecture document (`[docs_folder]/architecture.md`) and update it to accommodate this feature: + +1. **If the architecture document exists:** + - Read it thoroughly to understand the current system architecture + - Identify where this feature fits into the existing architecture + - Determine if any existing components need modification + - Add new components, services, or modules introduced by this feature + - Update diagrams or descriptions to reflect the changes + - Ensure consistency between the feature plan and the overall architecture + +2. **If the architecture document doesn't exist:** + - Create a new architecture document that captures the project's structure + - Include the components being added by this feature + - Document the high-level system design + +3. **What to include in architecture updates:** + - New components or services added + - Modified integration points + - New data flows + - Updated system boundaries + - Any architectural decisions that affect the broader system + +**Important**: The architecture document is a living document that evolves with the project. Each feature should leave it more complete and accurate than before. + +### Step 8: Create Planning Documents + +Create the following files in `specs/[feature-name]/`: + +**1. plan.md** - Main implementation plan +```markdown +# [Feature Name] Implementation Plan + +## Architecture Overview + +### High-Level Design +[Diagram or description of component architecture] + +### Component Responsibilities +- **[Component 1]**: [Responsibility] +- **[Component 2]**: [Responsibility] + +### Integration Points +- [External system]: [How it integrates] + +## Technology Stack + +### [Category] +**Chosen**: [Technology] +**Rationale**: [Why] + +## Implementation Strategy + +### Phase 1: [Phase Name] +[Description of what will be built] + +### Phase 2: [Phase Name] +[Description of what will be built] + +## Security Considerations +[How security requirements will be met] + +## Performance Strategy +[How performance requirements will be met] + +## Testing Strategy +[Approach to testing this feature] + +## Deployment Considerations +[How this will be deployed] +``` + +**2. data-model.md** - Database schema and relationships +```markdown +# [Feature Name] Data Model + +## Entity Relationship Diagram +[Text-based ERD or description] + +## Entities + +### [Entity Name] +[Table definition as shown in Step 4] + +## Migrations +[Migration strategy if applicable] +``` + +**3. api-spec.json** - OpenAPI specification (if applicable) +```json +{ + "openapi": "3.0.0", + "info": { + "title": "[Feature] API", + "version": "1.0.0" + }, + "paths": { + ... + } +} +``` + +**4. research.md** - Research findings +```markdown +# [Feature Name] Research + +## Technology Evaluations +[Findings from research] + +## Design Decisions +[Key decisions and rationale] + +## References +[Links to documentation, articles, examples referenced] +``` + +## Example Dialog + +``` +Claude: I'll create a technical implementation plan. Which feature are you planning? + +User: user-authentication + +Claude: Let me review the specification and constitution... + +[Reads both files] + +I see you're using TypeScript with Next.js and prioritizing security. The spec requires +email/password and Google OAuth signup with email verification. + +Let me design the architecture. I have a question about session management: + +[Uses AskUserQuestion with options: +- JWT tokens (stateless, good for scaling) +- Server-side sessions with Redis (more control, easier revocation) +- Next.js built-in auth (iron-session) +- Other] + +User: JWT tokens + +Claude: Good choice for scalability. For the database schema, I see you're using PostgreSQL. + +Here's the proposed data model: + +**Users Table:** +| Field | Type | Constraints | +|-------|------|-------------| +| id | UUID | PK | +| email | VARCHAR(255) | UNIQUE, NOT NULL | +| password_hash | VARCHAR(255) | NULL (for OAuth users) | +| email_verified | BOOLEAN | DEFAULT FALSE | +| created_at | TIMESTAMP | NOT NULL | + +**OAuth Connections Table:** +| Field | Type | Constraints | +|-------|------|-------------| +| id | UUID | PK | +| user_id | UUID | FK → users | +| provider | VARCHAR(50) | NOT NULL | +| provider_id | VARCHAR(255) | NOT NULL | + +Does this data model match your needs? + +[Continues planning...] + +✓ Technical plan created! + +**Files created/updated:** +- specs/user-authentication/plan.md +- specs/user-authentication/data-model.md +- specs/user-authentication/api-spec.json +- specs/user-authentication/research.md +- [docs_folder]/architecture.md (updated with auth components) + +**Next step:** +Run `/spec_driven_development.tasks` to generate the implementation task breakdown. +``` + +## Output Format + +### specs/[feature-name]/plan.md +Main implementation plan with architecture, technology choices, and strategy. + +### specs/[feature-name]/data-model.md +Database schema with entities, relationships, and migration strategy. + +### specs/[feature-name]/api-spec.json +OpenAPI specification for API endpoints (if applicable). + +### specs/[feature-name]/research.md +Research findings, technology evaluations, and references. + +### [docs_folder]/architecture.md +Project-wide architecture document, updated to include this feature's components and integrations. + +After creating the files: +1. Summarize the architecture and key technology choices +2. Highlight any decisions that required user input +3. Tell the user to run `/spec_driven_development.tasks` to generate tasks + +## Quality Criteria + +- Architecture clearly addresses all specification requirements +- Technology choices are justified with rationale +- Constitution principles are respected +- Data model is normalized and complete +- API contracts are well-defined +- Security considerations are addressed +- Research is documented +- Project architecture document reviewed and updated +- All planning documents created in correct location +- **No implementation code**: Documents contain schemas and contracts, not actual code diff --git a/library/jobs/spec_driven_development/steps/specify.md b/library/jobs/spec_driven_development/steps/specify.md new file mode 100644 index 00000000..6cb0a597 --- /dev/null +++ b/library/jobs/spec_driven_development/steps/specify.md @@ -0,0 +1,290 @@ +# Create Specification + +## Objective + +Create a functional specification (`spec.md`) that defines what the feature should do and why, using user stories and acceptance criteria, without making technology or implementation decisions. + +## Task + +Guide the user through creating a comprehensive specification by asking structured questions about their feature requirements, user needs, and success criteria. + +**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. + +**Key Principle**: This step focuses entirely on the **"what"** and **"why"** - never the **"how"**. Technology choices and implementation details belong in the planning step. + +**Critical**: Do not include any code examples, implementation snippets, or technical solutions. The specification describes user needs and acceptance criteria in plain language. Code is written only in the implement step. + +### Prerequisites + +Before starting, verify: +1. The constitution exists at `[docs_folder]/constitution.md` +2. Read the constitution to understand project principles and priorities + +If the constitution doesn't exist, inform the user they should run `/spec_driven_development.constitution` first. + +### Step 1: Define the Feature + +Ask structured questions to understand the feature: + +1. **What is this feature called?** + - Get a concise, descriptive name + - Convert to lowercase with hyphens for the directory name (e.g., "User Authentication" → "user-authentication") + +2. **What problem does this feature solve?** + - What user pain point does it address? + - What business value does it provide? + - Why is this feature needed now? + +3. **Who are the users of this feature?** + - Primary user personas + - Secondary stakeholders + - Admin or support considerations + +### Step 2: Gather User Stories + +For each user type identified, ask structured questions to create user stories: + +1. **What does [user type] need to do?** + - What's their goal? + - What triggers them to use this feature? + - What does success look like for them? + +2. **Create user stories in standard format:** + ``` + As a [user type] + I want to [action] + So that [benefit/goal] + ``` + +3. **Define acceptance criteria for each story:** + - What must be true for this story to be "done"? + - What are the happy path scenarios? + - What are the edge cases? + +### Step 3: Define Requirements + +Gather detailed requirements: + +1. **Functional Requirements** + - What actions must users be able to take? + - What data must be captured or displayed? + - What workflows must be supported? + +2. **Non-Functional Requirements** + - Performance: What are acceptable response times? + - Security: What data needs protection? What access controls? + - Accessibility: What accessibility standards apply? + - Scalability: What load must this support? + +3. **Constraints** + - What are the boundaries of this feature? + - What is explicitly out of scope? + - What dependencies exist on other features? + +### Step 4: Define Scope Boundaries + +Clearly establish what's in and out of scope: + +1. **In Scope** + - List all capabilities included in this feature + - Be specific about what will be delivered + +2. **Out of Scope** + - Explicitly list what will NOT be included + - Identify items that might be assumed but aren't part of this work + - Note future enhancements that are deferred + +3. **Assumptions** + - What are we assuming to be true? + - What dependencies must be in place? + +### Step 5: Create the Specification File + +**Create directory structure first:** +```bash +mkdir -p specs/[feature-name] +``` + +**Create the specification file** at `specs/[feature-name]/spec.md`: + +```markdown +# [Feature Name] Specification + +## Overview + +### Problem Statement +[Description of the problem this feature solves] + +### Business Value +[Why this feature matters to the business/users] + +### Target Users +- **[User Type 1]**: [Description and needs] +- **[User Type 2]**: [Description and needs] + +## User Stories + +### US-1: [Story Title] + +**As a** [user type] +**I want to** [action] +**So that** [benefit] + +**Acceptance Criteria:** +- [ ] [Criterion 1] +- [ ] [Criterion 2] +- [ ] [Criterion 3] + +**Edge Cases:** +- [Edge case 1]: [Expected behavior] +- [Edge case 2]: [Expected behavior] + +### US-2: [Story Title] +[Continue for each user story...] + +## Requirements + +### Functional Requirements + +| ID | Requirement | Priority | Notes | +|----|-------------|----------|-------| +| FR-1 | [Requirement] | Must Have | | +| FR-2 | [Requirement] | Should Have | | + +### Non-Functional Requirements + +#### Performance +- [Performance requirement 1] +- [Performance requirement 2] + +#### Security +- [Security requirement 1] +- [Security requirement 2] + +#### Accessibility +- [Accessibility requirement 1] + +## Scope + +### In Scope +- [Capability 1] +- [Capability 2] + +### Out of Scope +- [Excluded item 1] +- [Excluded item 2] + +### Assumptions +- [Assumption 1] +- [Assumption 2] + +### Dependencies +- [Dependency 1] +- [Dependency 2] + +## Open Questions + +[List any questions that need clarification before planning] + +1. [Question 1] +2. [Question 2] +``` + +## Example Dialog + +``` +Claude: I'll help you create a specification for your new feature. Let me first check the +project constitution... + +[Reads [docs_folder]/constitution.md] + +Great, I see you're prioritizing code quality and security. Let's define your feature. + +What feature are you building? Give me a name and brief description. + +User: User authentication - allowing users to sign up and log in to our app + +Claude: Perfect. I'll create this under `specs/user-authentication/`. + +What problem does authentication solve for your users? Why do they need accounts? + +User: Users need accounts to save their preferences and access their data across devices. + +Claude: That makes sense. Who are the primary users of this authentication system? + +[Uses AskUserQuestion with options: New users signing up, Returning users logging in, +Admins managing users, All of the above] + +User: All of the above + +Claude: Let's create user stories for each. Starting with new users signing up: + +What's most important to a new user when creating an account? + +User: Quick signup - ideally with email or social login. No lengthy forms. + +Claude: Got it. Here's the user story I'd write: + +**As a** new user +**I want to** sign up quickly using my email or social account +**So that** I can start using the app without friction + +What would make this story "done"? What must work for you to accept it? + +User: They need to be able to sign up with email/password or Google. Email verification +should be required. The whole flow should take under a minute. + +Claude: Those are clear acceptance criteria. Now let's think about edge cases... + +[Continues gathering information...] + +✓ Specification created! + +**File created:** +- specs/user-authentication/spec.md + +**Open Questions:** +I noted 2 questions that need clarification before we can plan the implementation. + +**Next step:** +Run `/spec_driven_development.clarify` to resolve open questions and finalize the spec. +``` + +## Validation Rules + +Before creating the spec.md, ensure: +- Feature name is lowercase with hyphens +- All user stories follow "As a... I want... So that..." format +- Each story has at least 2 acceptance criteria +- In/out of scope sections are populated +- No technology or implementation details are included +- Open questions are documented + +## Output Format + +### specs/[feature-name]/spec.md + +A markdown document containing: +- Overview (problem, value, users) +- User stories with acceptance criteria +- Functional and non-functional requirements +- Scope boundaries +- Open questions + +**Location**: `specs/[feature-name]/spec.md` + +After creating the file: +1. Summarize the key user stories +2. Highlight any open questions that need resolution +3. Tell the user to run `/spec_driven_development.clarify` to resolve ambiguities + +## Quality Criteria + +- Asked structured questions to understand user needs +- All user stories are in correct format +- Acceptance criteria are testable +- Non-functional requirements are captured +- Scope boundaries are clear +- **No implementation code**: Spec describes behavior in plain language, not code +- Constitution principles are respected +- File created in correct location diff --git a/library/jobs/spec_driven_development/steps/tasks.md b/library/jobs/spec_driven_development/steps/tasks.md new file mode 100644 index 00000000..250b733c --- /dev/null +++ b/library/jobs/spec_driven_development/steps/tasks.md @@ -0,0 +1,358 @@ +# Generate Task Breakdown + +## Objective + +Convert the implementation plan into an ordered list of actionable development tasks. Each task should be small enough to complete in a single coding session and clearly specify what files will be created or modified. + +## Task + +Analyze the implementation plan and specification to generate a comprehensive task list organized by user story with proper dependency ordering. + +**Critical**: This step produces a task breakdown, NOT implementation code. Task descriptions should specify: +- What files to create or modify +- What the file should accomplish +- Acceptance criteria for the task + +Do NOT include: +- Actual code snippets or implementations +- "Here's how to implement this" examples +- Starter code or templates with real logic + +The implement step is where code gets written. This step only plans the work. + +### Prerequisites + +Before starting, verify these files exist and read them: +1. `specs/[feature-name]/spec.md` - User stories and acceptance criteria +2. `specs/[feature-name]/plan.md` - Architecture and implementation strategy +3. `[docs_folder]/architecture.md` - Project architecture document + +If any are missing, inform the user which step they need to complete first. + +### Step 1: Identify the Feature + +Ask the user which feature to generate tasks for: + +``` +Which feature would you like to generate tasks for? +``` + +Verify the plan exists and review it along with the specification. + +### Step 2: Analyze Dependencies + +Map out the dependency graph: + +1. **Infrastructure Dependencies** + - Database setup must come before data access code + - Authentication must come before protected routes + - Base components before compound components + +2. **User Story Dependencies** + - Some stories may depend on others + - Identify the critical path + +3. **Testing Dependencies** + - Tests often written alongside or before implementation (TDD) + - Integration tests after unit tests + +### Step 3: Task Decomposition + +For each user story, break down into tasks: + +1. **Database/Model Tasks** + - Create migrations + - Define models/entities + - Add indexes + +2. **Backend Tasks** + - Implement API endpoints + - Add business logic + - Integrate services + +3. **Frontend Tasks** (if applicable) + - Create components + - Add pages/routes + - Implement state management + +4. **Testing Tasks** + - Unit tests for business logic + - Integration tests for APIs + - E2E tests for critical flows + +5. **Infrastructure Tasks** + - Configuration + - Deployment scripts + - Monitoring setup + +### Step 4: Task Format + +Each task should follow this format: + +```markdown +### Task [N]: [Descriptive Title] + +**User Story**: US-[N] (or "Infrastructure" if not tied to a story) +**Type**: [Database | Backend | Frontend | Test | Infrastructure] +**Dependencies**: [List of task numbers that must complete first, or "None"] +**Parallel**: [P] (add if can run in parallel with other tasks) + +**Description:** +[What needs to be done] + +**Files to Create/Modify:** +- `path/to/file.ts` - [What to do with this file] +- `path/to/another.ts` - [What to do with this file] + +**Acceptance Criteria:** +- [ ] [Specific criterion] +- [ ] [Specific criterion] + +**Validation:** +[How to verify this task is complete - e.g., "Run tests", "Check endpoint responds"] +``` + +### Step 5: Identify Parallel Tasks + +Mark tasks that can run in parallel with `[P]`: + +- Tasks with no dependencies on each other +- Tasks working on different subsystems +- Independent test suites + +**Parallel notation:** +```markdown +### Task 5: Create User Model [P] +### Task 6: Create OAuth Connection Model [P] + +(Tasks 5 and 6 can run in parallel after Task 4 completes) +``` + +### Step 6: Add Checkpoints + +Insert validation checkpoints between phases: + +```markdown +## Checkpoint: Database Layer Complete + +**Verify before proceeding:** +- [ ] All migrations run successfully +- [ ] Models are defined with correct relationships +- [ ] Database can be seeded with test data + +**Run:** `npm run db:migrate && npm run db:seed` +``` + +### Step 7: Create Tasks File + +Create `specs/[feature-name]/tasks.md`: + +```markdown +# [Feature Name] Implementation Tasks + +## Overview + +**Total Tasks**: [N] +**Estimated Phases**: [N] +**Parallelizable Tasks**: [N] + +## Task Dependency Graph + +``` +[1] → [2] → [5] + ↘ +[3] → [4] → [6] → [7] + ↗ +[1] → [8] +``` + +## Phase 1: Infrastructure & Database + +### Task 1: Setup Database Migrations + +**User Story**: Infrastructure +**Type**: Database +**Dependencies**: None + +**Description:** +Create the initial database migrations for [entity] tables. + +**Files to Create/Modify:** +- `migrations/001_create_users.sql` - Create users table +- `migrations/002_create_oauth_connections.sql` - Create OAuth table + +**Acceptance Criteria:** +- [ ] Migrations run without errors +- [ ] Tables created with correct schema +- [ ] Indexes are in place + +**Validation:** +Run `npm run db:migrate` and verify tables exist. + +--- + +### Task 2: [Next Task] +... + +--- + +## Checkpoint: Database Layer Complete +[Checkpoint content] + +--- + +## Phase 2: Backend API + +### Task 3: [Backend Task] +... + +--- + +## Checkpoint: API Layer Complete +[Checkpoint content] + +--- + +## Phase 3: Frontend Components + +### Task 4: [Frontend Task] +... + +--- + +## Checkpoint: Feature Complete +[Final validation checklist] + +--- + +## Summary + +| Phase | Tasks | Parallel | +|-------|-------|----------| +| 1. Infrastructure | 1-2 | 0 | +| 2. Backend | 3-6 | 2 | +| 3. Frontend | 7-10 | 3 | +| 4. Testing | 11-14 | 4 | + +**Critical Path**: Tasks 1 → 3 → 7 → 11 → 14 + +**Total Parallelizable**: [N] tasks can run concurrently +``` + +## Example Dialog + +``` +Claude: I'll generate implementation tasks. Which feature are you working on? + +User: user-authentication + +Claude: Let me review the plan and specification... + +[Reads specs/user-authentication/plan.md and spec.md] + +Based on the plan, I see we need: +- Database: Users and OAuth connections tables +- API: Signup, login, OAuth, and verification endpoints +- Frontend: Signup form, login form, OAuth buttons + +I'll organize tasks by user story and phase. Here's the structure: + +**Phase 1: Database (4 tasks)** +- Task 1: Create users migration +- Task 2: Create OAuth connections migration [P] +- Task 3: Create user model +- Task 4: Create OAuth connection model [P] + +**Phase 2: Authentication Backend (6 tasks)** +- Task 5: Implement password hashing utility +- Task 6: Implement JWT token service [P] +- Task 7: Create signup endpoint +- Task 8: Create login endpoint [P] +- Task 9: Create OAuth callback handler +- Task 10: Create email verification endpoint + +**Phase 3: Frontend (4 tasks)** +- Task 11: Create signup form component +- Task 12: Create login form component [P] +- Task 13: Create OAuth button component [P] +- Task 14: Add authentication pages + +**Phase 4: Testing (4 tasks)** +- Task 15: Unit tests for auth utilities +- Task 16: Integration tests for auth API [P] +- Task 17: E2E test for signup flow [P] +- Task 18: E2E test for login flow [P] + +That's 18 tasks total, with 9 parallelizable. + +Does this breakdown look right? Any tasks you'd like to add or modify? + +User: Looks good! + +Claude: Creating the tasks file... + +✓ Task breakdown created! + +**File created:** +- specs/user-authentication/tasks.md + +**Summary:** +- 18 tasks across 4 phases +- 9 tasks can run in parallel +- Critical path: 9 tasks in sequence +- 4 checkpoints for validation + +**Next step:** +Run `/spec_driven_development.implement` to start executing tasks. +``` + +## Task Sizing Guidelines + +**Good task size:** +- Can be completed in 15-60 minutes +- Creates/modifies 1-3 files +- Has clear start and end state +- Can be validated independently + +**Too large (split it):** +- Takes more than 2 hours +- Touches more than 5 files +- Has multiple distinct outcomes +- Hard to validate incrementally + +**Too small (combine it):** +- Takes less than 5 minutes +- Is just configuration +- Can't be validated alone + +## Output Format + +### specs/[feature-name]/tasks.md + +A markdown document containing: +- Task dependency overview/graph +- Numbered tasks organized by phase +- Each task with full details (story, type, dependencies, files, criteria) +- Checkpoints between phases +- Summary table with parallelization info + +**Location**: `specs/[feature-name]/tasks.md` + +After creating the file: +1. Summarize total tasks and phases +2. Highlight parallelization opportunities +3. Show the critical path +4. Tell the user to run `/spec_driven_development.implement` to begin implementation + +## Quality Criteria + +- Tasks are organized by user story +- Dependencies are correctly sequenced +- Parallel tasks are identified with [P] +- Each task specifies files to create/modify +- Tasks are appropriately sized +- Checkpoints exist between phases +- Testing tasks are included +- Critical path is identifiable +- File created in correct location +- **No implementation code**: Tasks describe what to build, not how to code it