From acb2e8058f9989993a0cd4c694454795c7b6cfc1 Mon Sep 17 00:00:00 2001 From: Aniket Date: Thu, 11 Dec 2025 10:27:32 +0530 Subject: [PATCH 1/6] docs: expand fork rationale with constitution gap analysis --- README.md | 17 +- .../checklists/requirements.md | 38 +++++ specs/001-commit-based-tasks/spec.md | 160 ++++++++++++++++++ 3 files changed, 211 insertions(+), 4 deletions(-) create mode 100644 specs/001-commit-based-tasks/checklists/requirements.md create mode 100644 specs/001-commit-based-tasks/spec.md diff --git a/README.md b/README.md index 281b254541..634f16188b 100644 --- a/README.md +++ b/README.md @@ -20,14 +20,23 @@ > > This is a fork of the original [Spec Kit](https://github.com/github/spec-kit) with enhancements to bridge the gap between planning and execution. > -> The original Spec Kit has three planning layers: **Specification → Planning → Tasks**. However, there's a missing link between planning and tasks. This fork introduces the concept of **Commits** as the bridge: +> **The Problem**: In the original Spec Kit, the constitution (your project's quality principles) influences the *plan* but not the *tasks* or *execution*: +> +> | Phase | Constitution Used? | Gap | +> | ----- | ------------------ | --- | +> | `/speckit.plan` | ✅ Gates workflow | Works well | +> | `/speckit.analyze` | ✅ Validates compliance | Works well | +> | `/speckit.tasks` | ❌ Not loaded | Tasks don't reflect constitution | +> | `/speckit.implement` | ❌ Not loaded | No quality checks at commit time | +> +> **The Solution**: This fork introduces **Commits** as the bridge between planning and tasks: > > - **Commits are planned ahead of time** — Tasks achieve commits, not the other way around > - **Two types of tasks**: -> - **Repetitive tasks** — Driven by your constitution (e.g., TDD's RED-GREEN-REFACTOR cycle for each commit, Playwright tests updated with UI changes) -> - **Non-repetitive tasks** — The actual work required to implement the specification +> - **Repetitive tasks** — Automatically derived from your constitution (e.g., TDD's RED-GREEN-REFACTOR cycle, Playwright tests for UI changes, linting verification) +> - **Non-repetitive tasks** — The actual implementation work unique to each commit > -> This approach ensures that quality practices defined in your constitution are automatically woven into every commit, not bolted on as an afterthought. +> This ensures that quality practices defined in your constitution are automatically woven into every commit, not bolted on as an afterthought. --- diff --git a/specs/001-commit-based-tasks/checklists/requirements.md b/specs/001-commit-based-tasks/checklists/requirements.md new file mode 100644 index 0000000000..ca231698df --- /dev/null +++ b/specs/001-commit-based-tasks/checklists/requirements.md @@ -0,0 +1,38 @@ +# Specification Quality Checklist: Commit-Based Task Orchestration + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2025-12-11 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +- Specification is complete and ready for `/speckit.clarify` or `/speckit.plan` +- Problem statement clearly articulates the gap in the current workflow +- Solution overview provides a clear mental model (Specification → Planning → Commits → Tasks) +- Two task types (repetitive vs non-repetitive) are well-defined +- Edge cases cover key failure scenarios diff --git a/specs/001-commit-based-tasks/spec.md b/specs/001-commit-based-tasks/spec.md new file mode 100644 index 0000000000..fd6ff48a0d --- /dev/null +++ b/specs/001-commit-based-tasks/spec.md @@ -0,0 +1,160 @@ +# Feature Specification: Commit-Based Task Orchestration + +**Feature Branch**: `001-commit-based-tasks` +**Created**: 2025-12-11 +**Status**: Draft +**Input**: User description: "Introduce commits as the bridge between planning and tasks, with repetitive and non-repetitive task types driven by the project constitution" + +## Problem Statement + +The current Spec Kit workflow has three planning layers: **Specification → Planning → Tasks**. However, there is a gap between the planning phase and task execution. Tasks are generated as flat lists without clear boundaries for what constitutes a "done" unit of work. This leads to: + +1. **Quality practices as afterthoughts** - TDD, testing, and documentation are separate tasks rather than integral parts of each deliverable +2. **Unclear progress tracking** - Without commit boundaries, it's hard to know when a unit of work is complete +3. **Constitution principles not enforced** - Quality requirements defined in the constitution are not automatically woven into the workflow + +## Solution Overview + +Introduce **Commits** as the intermediate layer between Planning and Tasks: + +**Specification → Planning → Commits → Tasks** + +Where: + +- **Commits** are planned units of deliverable work (each commit should leave the codebase in a working state) +- **Tasks** are grouped under commits and divided into two types: + - **Repetitive tasks**: Automatically derived from constitution principles (e.g., TDD cycles, test updates) + - **Non-repetitive tasks**: The actual implementation work unique to each commit + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Plan Commits from Implementation Plan (Priority: P1) + +As a developer using Spec Kit, I want the `/speckit.tasks` command to generate a list of planned commits (not just tasks) so that I have clear boundaries for what constitutes a complete unit of work. + +**Why this priority**: This is the foundational change - without commit planning, the rest of the feature cannot work. Commits provide the structure that enables everything else. + +**Independent Test**: Can be fully tested by running `/speckit.tasks` on a sample plan and verifying the output contains commit boundaries with descriptions of what each commit achieves. + +**Acceptance Scenarios**: + +1. **Given** a completed `plan.md`, **When** I run `/speckit.tasks`, **Then** the output `tasks.md` contains a list of planned commits, each with a clear description of the deliverable +2. **Given** a plan with multiple user stories, **When** commits are generated, **Then** each commit maps to a logical, independently testable unit of the implementation +3. **Given** a generated commits list, **When** I review it, **Then** each commit description follows the conventional commit format (type: description) + +--- + +### User Story 2 - Generate Repetitive Tasks from Constitution (Priority: P1) + +As a developer, I want repetitive quality tasks (like TDD cycles, test updates) to be automatically generated for each commit based on my project's constitution, so that quality practices are built into every deliverable rather than bolted on. + +**Why this priority**: This is the core innovation - ensuring constitution-defined quality practices are automatically enforced at the commit level. + +**Independent Test**: Can be tested by creating a constitution with TDD requirements and verifying that each planned commit automatically includes RED-GREEN-REFACTOR tasks. + +**Acceptance Scenarios**: + +1. **Given** a constitution that requires TDD, **When** commits are generated, **Then** each commit includes repetitive tasks for: write failing test → implement → refactor +2. **Given** a constitution that requires Playwright tests for UI changes, **When** a commit involves UI changes, **Then** repetitive tasks for Playwright test creation/update are included +3. **Given** a constitution with linting requirements, **When** commits are generated, **Then** each commit includes a verification task for linting +4. **Given** a constitution with documentation requirements, **When** a commit adds/changes features, **Then** repetitive tasks for documentation updates are included + +--- + +### User Story 3 - Generate Non-Repetitive Tasks for Implementation (Priority: P2) + +As a developer, I want the actual implementation work to be broken down into non-repetitive tasks under each commit, so that I have a clear checklist of what needs to be done for each deliverable. + +**Why this priority**: Without the implementation tasks, the commits would only have quality checks but no actual work. + +**Independent Test**: Can be tested by verifying that each commit contains specific implementation tasks derived from the plan. + +**Acceptance Scenarios**: + +1. **Given** a commit for "Add user model", **When** tasks are generated, **Then** non-repetitive tasks include: create model file, define attributes, add validation rules +2. **Given** a plan with technical decisions documented, **When** non-repetitive tasks are generated, **Then** they reference the relevant technical decisions +3. **Given** a commit with dependencies on another commit, **When** tasks are generated, **Then** the dependency is clearly noted + +--- + +### User Story 4 - Execute Commits Sequentially (Priority: P2) + +As a developer, I want `/speckit.implement` to execute commits one at a time, completing all tasks (repetitive + non-repetitive) for each commit before moving to the next, so that the codebase remains in a working state after each commit. + +**Why this priority**: This ensures the commit-based workflow is actually followed during implementation. + +**Independent Test**: Can be tested by running `/speckit.implement` and verifying that actual git commits are created at the defined boundaries. + +**Acceptance Scenarios**: + +1. **Given** a tasks.md with 5 planned commits, **When** I run `/speckit.implement`, **Then** the AI agent executes all tasks for commit 1 before starting commit 2 +2. **Given** a commit with repetitive TDD tasks, **When** the commit is being implemented, **Then** tests are written before implementation code +3. **Given** a commit is complete, **When** all its tasks pass, **Then** a git commit is created with the planned commit message +4. **Given** a commit fails its verification tasks (linting, tests), **When** reviewed, **Then** the implementation pauses for fixes before proceeding + +--- + +### User Story 5 - Constitution-Aware Task Templates (Priority: P3) + +As a project maintainer, I want to define custom repetitive task templates in the constitution, so that project-specific quality practices are automatically included in every commit. + +**Why this priority**: This enables customization beyond the default repetitive tasks. + +**Independent Test**: Can be tested by adding a custom task template to the constitution and verifying it appears in generated commits. + +**Acceptance Scenarios**: + +1. **Given** a constitution with a custom "security review" repetitive task, **When** commits are generated, **Then** each commit includes the security review task +2. **Given** a constitution with conditional repetitive tasks (e.g., "API documentation for API changes"), **When** a commit involves API changes, **Then** the conditional task is included +3. **Given** a constitution without custom templates, **When** commits are generated, **Then** default repetitive tasks based on detected patterns are used + +--- + +### Edge Cases + +- What happens when a commit's non-repetitive tasks fail but repetitive tasks pass? → The commit should not be created; implementation should pause for fixes +- How does the system handle commits that span multiple files with different test requirements? → Repetitive tasks should be aggregated at the commit level, not per-file +- What happens when the constitution is updated mid-implementation? → New commits should use updated constitution; in-progress commits continue with original requirements +- How are circular dependencies between commits handled? → Validation should fail during `/speckit.tasks` with a clear error message + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: The `/speckit.tasks` command MUST generate a `tasks.md` that organizes work into planned commits +- **FR-002**: Each commit MUST have a clear, conventional-format description of its deliverable +- **FR-003**: The system MUST parse the constitution to identify repetitive task requirements +- **FR-004**: Repetitive tasks MUST be automatically added to each commit based on constitution principles +- **FR-005**: Non-repetitive tasks MUST be derived from the implementation plan and organized under commits +- **FR-006**: The `/speckit.implement` command MUST execute commits sequentially, completing all tasks before creating a git commit +- **FR-007**: The system MUST validate that all repetitive tasks pass before allowing a commit to be created +- **FR-008**: Task dependencies within a commit MUST be respected during execution order +- **FR-009**: The system MUST support conditional repetitive tasks (tasks that apply only to certain types of changes) +- **FR-010**: The tasks.md format MUST clearly distinguish between repetitive and non-repetitive tasks + +### Key Entities + +- **Commit**: A planned unit of deliverable work with a description, list of tasks, and completion criteria +- **Repetitive Task**: A task derived from constitution principles that applies to every (or conditional) commit +- **Non-Repetitive Task**: A task specific to the implementation work of a single commit +- **Constitution Principle**: A quality requirement that may generate repetitive tasks (e.g., TDD, linting, documentation) +- **Task Dependency**: A relationship indicating one task must complete before another can begin + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: 100% of commits generated by `/speckit.tasks` include repetitive tasks derived from the constitution +- **SC-002**: Users can understand the scope of each commit by reading its description alone (no need to read individual tasks) +- **SC-003**: Implementation via `/speckit.implement` creates git commits at the planned boundaries 90%+ of the time +- **SC-004**: Quality violations (failed tests, linting errors) are caught before git commits are created +- **SC-005**: Time from plan to implementation reduces by enabling AI agents to work autonomously through well-defined commit boundaries +- **SC-006**: Users report that quality practices feel "built-in" rather than "bolted on" in post-implementation surveys + +## Assumptions + +- The project constitution follows the established format with clearly identifiable principles +- Git is available and configured in the project repository +- AI agents support the concept of executing tasks in sequence and creating commits +- The existing `/speckit.tasks` template structure can be extended to support commit-based organization +- Repetitive tasks for common patterns (TDD, linting, testing) can be detected from constitution keywords From ee80eec0fac9854c4db56a23474e766952dce7dd Mon Sep 17 00:00:00 2001 From: Aniket Date: Thu, 11 Dec 2025 10:50:22 +0530 Subject: [PATCH 2/6] docs: refine to diverge-converge workflow model - Correct conceptual model: tasks accumulate INTO commits (not the reverse) - Add convergent phases: /speckit.commits and /speckit.milestones - Milestones are verification checkpoints requiring human review - Update README with ASCII diagram showing diverge-converge flow - Clarify repetitive vs non-repetitive tasks within commits --- README.md | 30 ++- .../checklists/requirements.md | 10 +- specs/001-commit-based-tasks/spec.md | 201 +++++++++++------- 3 files changed, 146 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 634f16188b..ed08bb5ff3 100644 --- a/README.md +++ b/README.md @@ -18,25 +18,37 @@ > **🔀 Why This Fork?** > -> This is a fork of the original [Spec Kit](https://github.com/github/spec-kit) with enhancements to bridge the gap between planning and execution. +> This is a fork of the original [Spec Kit](https://github.com/github/spec-kit) that introduces a **Diverge-Converge** workflow model. > -> **The Problem**: In the original Spec Kit, the constitution (your project's quality principles) influences the *plan* but not the *tasks* or *execution*: +> **The Problem**: The original Spec Kit only diverges (breaks down work) but never converges: > > | Phase | Constitution Used? | Gap | > | ----- | ------------------ | --- | > | `/speckit.plan` | ✅ Gates workflow | Works well | > | `/speckit.analyze` | ✅ Validates compliance | Works well | > | `/speckit.tasks` | ❌ Not loaded | Tasks don't reflect constitution | -> | `/speckit.implement` | ❌ Not loaded | No quality checks at commit time | +> | `/speckit.implement` | ❌ Not loaded | No verification checkpoints | > -> **The Solution**: This fork introduces **Commits** as the bridge between planning and tasks: +> **The Solution**: A complete **Diverge-Converge** workflow: > -> - **Commits are planned ahead of time** — Tasks achieve commits, not the other way around -> - **Two types of tasks**: -> - **Repetitive tasks** — Automatically derived from your constitution (e.g., TDD's RED-GREEN-REFACTOR cycle, Playwright tests for UI changes, linting verification) -> - **Non-repetitive tasks** — The actual implementation work unique to each commit +> ``` +> DIVERGENT (Breaking Down) CONVERGENT (Building Up) +> ┌─────────────────────────┐ ┌─────────────────────────┐ +> │ /speckit.specify │ │ /speckit.commits │ +> │ ↓ │ │ (tasks → commits) │ +> │ /speckit.plan │ ───► │ ↓ │ +> │ ↓ │ │ /speckit.milestones │ +> │ /speckit.tasks │ │ (commits → milestones) │ +> └─────────────────────────┘ └─────────────────────────┘ +> ``` > -> This ensures that quality practices defined in your constitution are automatically woven into every commit, not bolted on as an afterthought. +> **Key Concepts**: +> - **Commits** accumulate tasks (each commit includes repetitive + non-repetitive tasks) +> - **Repetitive tasks** — Derived from constitution (TDD, linting, Playwright tests) +> - **Non-repetitive tasks** — The actual implementation work +> - **Milestones** — Verification checkpoints requiring manual human review +> +> This ensures quality practices are woven into every commit, with clear checkpoints for human verification. --- diff --git a/specs/001-commit-based-tasks/checklists/requirements.md b/specs/001-commit-based-tasks/checklists/requirements.md index ca231698df..389921c90c 100644 --- a/specs/001-commit-based-tasks/checklists/requirements.md +++ b/specs/001-commit-based-tasks/checklists/requirements.md @@ -1,4 +1,4 @@ -# Specification Quality Checklist: Commit-Based Task Orchestration +# Specification Quality Checklist: Diverge-Converge Workflow **Purpose**: Validate specification completeness and quality before proceeding to planning **Created**: 2025-12-11 @@ -32,7 +32,7 @@ ## Notes - Specification is complete and ready for `/speckit.clarify` or `/speckit.plan` -- Problem statement clearly articulates the gap in the current workflow -- Solution overview provides a clear mental model (Specification → Planning → Commits → Tasks) -- Two task types (repetitive vs non-repetitive) are well-defined -- Edge cases cover key failure scenarios +- Diverge-Converge model clearly articulated with ASCII diagram +- Two new slash commands identified: `/speckit.commits` and `/speckit.milestones` +- Key entities defined: Task, Commit, Milestone, Repetitive Task, Non-Repetitive Task +- Edge cases cover failure scenarios and mid-implementation changes diff --git a/specs/001-commit-based-tasks/spec.md b/specs/001-commit-based-tasks/spec.md index fd6ff48a0d..12e1d54d25 100644 --- a/specs/001-commit-based-tasks/spec.md +++ b/specs/001-commit-based-tasks/spec.md @@ -1,160 +1,199 @@ -# Feature Specification: Commit-Based Task Orchestration +# Feature Specification: Diverge-Converge Workflow **Feature Branch**: `001-commit-based-tasks` **Created**: 2025-12-11 **Status**: Draft -**Input**: User description: "Introduce commits as the bridge between planning and tasks, with repetitive and non-repetitive task types driven by the project constitution" +**Input**: User description: "Implement diverge-converge workflow where specification breaks down into plan, plan breaks down into tasks (divergent), then tasks accumulate into commits, commits accumulate into milestones (convergent). Commits include repetitive and non-repetitive tasks based on constitution." ## Problem Statement -The current Spec Kit workflow has three planning layers: **Specification → Planning → Tasks**. However, there is a gap between the planning phase and task execution. Tasks are generated as flat lists without clear boundaries for what constitutes a "done" unit of work. This leads to: +The current Spec Kit workflow has three planning layers: **Specification → Planning → Tasks**. However, there are two critical gaps: -1. **Quality practices as afterthoughts** - TDD, testing, and documentation are separate tasks rather than integral parts of each deliverable -2. **Unclear progress tracking** - Without commit boundaries, it's hard to know when a unit of work is complete -3. **Constitution principles not enforced** - Quality requirements defined in the constitution are not automatically woven into the workflow +1. **No convergence mechanism** - Tasks are generated as flat lists with no way to group them into meaningful deliverables +2. **No verification checkpoints** - There's no defined point where manual verification of the implementation occurs +3. **Constitution principles not enforced during execution** - Quality requirements are checked during planning but not woven into task execution ## Solution Overview -Introduce **Commits** as the intermediate layer between Planning and Tasks: - -**Specification → Planning → Commits → Tasks** - -Where: - -- **Commits** are planned units of deliverable work (each commit should leave the codebase in a working state) -- **Tasks** are grouped under commits and divided into two types: - - **Repetitive tasks**: Automatically derived from constitution principles (e.g., TDD cycles, test updates) - - **Non-repetitive tasks**: The actual implementation work unique to each commit +Introduce a **Diverge-Converge** workflow model: + +``` +DIVERGENT PHASES (Breaking Down) CONVERGENT PHASES (Building Up) +┌─────────────────────────────────┐ ┌─────────────────────────────────┐ +│ Specification │ │ Tasks │ +│ ↓ │ │ ↓ │ +│ Plan (breakdown of spec) │ │ Commits (accumulation of tasks)│ +│ ↓ │ │ ↓ │ +│ Tasks (breakdown of plan) │ │ Milestones (verification point)│ +└─────────────────────────────────┘ └─────────────────────────────────┘ +``` + +**Divergent Phases** (existing, enhanced): +1. `/speckit.specify` - Define what to build +2. `/speckit.plan` - Break specification into technical approach +3. `/speckit.tasks` - Break plan into actionable tasks + +**Convergent Phases** (new): +1. `/speckit.commits` - Group tasks into commits with constitution-driven repetitive tasks +2. `/speckit.milestones` - Group commits into milestones requiring manual verification + +**Key Concepts**: +- **Commits** accumulate tasks (not the other way around) +- Each commit has two types of tasks: + - **Repetitive tasks**: Derived from constitution (TDD, linting, testing) + - **Non-repetitive tasks**: The actual implementation work +- **Milestones** are verification checkpoints requiring human review ## User Scenarios & Testing *(mandatory)* -### User Story 1 - Plan Commits from Implementation Plan (Priority: P1) +### User Story 1 - Group Tasks into Commits (Priority: P1) -As a developer using Spec Kit, I want the `/speckit.tasks` command to generate a list of planned commits (not just tasks) so that I have clear boundaries for what constitutes a complete unit of work. +As a developer, I want to run `/speckit.commits` to group my tasks into logical commits, so that I have clear boundaries for what constitutes a complete, committable unit of work. -**Why this priority**: This is the foundational change - without commit planning, the rest of the feature cannot work. Commits provide the structure that enables everything else. +**Why this priority**: This is the foundation of the convergent phase - without commit grouping, tasks remain a flat list. -**Independent Test**: Can be fully tested by running `/speckit.tasks` on a sample plan and verifying the output contains commit boundaries with descriptions of what each commit achieves. +**Independent Test**: Can be fully tested by running `/speckit.commits` on a tasks.md and verifying the output contains commit groupings with task assignments. **Acceptance Scenarios**: -1. **Given** a completed `plan.md`, **When** I run `/speckit.tasks`, **Then** the output `tasks.md` contains a list of planned commits, each with a clear description of the deliverable -2. **Given** a plan with multiple user stories, **When** commits are generated, **Then** each commit maps to a logical, independently testable unit of the implementation -3. **Given** a generated commits list, **When** I review it, **Then** each commit description follows the conventional commit format (type: description) +1. **Given** a completed `tasks.md`, **When** I run `/speckit.commits`, **Then** the output `commits.md` contains commits with grouped tasks +2. **Given** tasks that logically belong together (e.g., model + service + endpoint for one feature), **When** commits are generated, **Then** they are grouped into a single commit +3. **Given** a generated commits list, **When** I review it, **Then** each commit has a conventional commit message (type: description) +4. **Given** independent tasks that can be committed separately, **When** commits are generated, **Then** they are organized into separate commits --- -### User Story 2 - Generate Repetitive Tasks from Constitution (Priority: P1) +### User Story 2 - Add Repetitive Tasks from Constitution (Priority: P1) -As a developer, I want repetitive quality tasks (like TDD cycles, test updates) to be automatically generated for each commit based on my project's constitution, so that quality practices are built into every deliverable rather than bolted on. +As a developer, I want `/speckit.commits` to automatically add repetitive tasks to each commit based on my constitution, so that quality practices are enforced at the commit level. -**Why this priority**: This is the core innovation - ensuring constitution-defined quality practices are automatically enforced at the commit level. +**Why this priority**: This ensures constitution compliance is built into every commit, not checked after the fact. -**Independent Test**: Can be tested by creating a constitution with TDD requirements and verifying that each planned commit automatically includes RED-GREEN-REFACTOR tasks. +**Independent Test**: Can be tested by having a constitution with TDD requirements and verifying each commit includes RED-GREEN-REFACTOR tasks. **Acceptance Scenarios**: -1. **Given** a constitution that requires TDD, **When** commits are generated, **Then** each commit includes repetitive tasks for: write failing test → implement → refactor -2. **Given** a constitution that requires Playwright tests for UI changes, **When** a commit involves UI changes, **Then** repetitive tasks for Playwright test creation/update are included -3. **Given** a constitution with linting requirements, **When** commits are generated, **Then** each commit includes a verification task for linting -4. **Given** a constitution with documentation requirements, **When** a commit adds/changes features, **Then** repetitive tasks for documentation updates are included +1. **Given** a constitution requiring TDD, **When** commits are generated, **Then** each commit includes: write failing test → implement → verify test passes → refactor +2. **Given** a constitution requiring linting, **When** commits are generated, **Then** each commit includes a "run linter" task at the end +3. **Given** a constitution requiring documentation updates, **When** a commit changes public interfaces, **Then** a documentation update task is included +4. **Given** a constitution with Playwright test requirements, **When** a commit involves UI changes, **Then** Playwright test tasks are included --- -### User Story 3 - Generate Non-Repetitive Tasks for Implementation (Priority: P2) +### User Story 3 - Define Milestones for Verification (Priority: P2) -As a developer, I want the actual implementation work to be broken down into non-repetitive tasks under each commit, so that I have a clear checklist of what needs to be done for each deliverable. +As a developer, I want to run `/speckit.milestones` to group commits into milestones that require manual verification, so that I have clear checkpoints for human review. -**Why this priority**: Without the implementation tasks, the commits would only have quality checks but no actual work. +**Why this priority**: Milestones provide the human-in-the-loop verification that ensures quality before proceeding to the next phase. -**Independent Test**: Can be tested by verifying that each commit contains specific implementation tasks derived from the plan. +**Independent Test**: Can be tested by running `/speckit.milestones` on commits.md and verifying milestone boundaries with verification criteria. **Acceptance Scenarios**: -1. **Given** a commit for "Add user model", **When** tasks are generated, **Then** non-repetitive tasks include: create model file, define attributes, add validation rules -2. **Given** a plan with technical decisions documented, **When** non-repetitive tasks are generated, **Then** they reference the relevant technical decisions -3. **Given** a commit with dependencies on another commit, **When** tasks are generated, **Then** the dependency is clearly noted +1. **Given** a completed `commits.md`, **When** I run `/speckit.milestones`, **Then** the output `milestones.md` groups commits into milestones +2. **Given** a milestone definition, **When** I review it, **Then** it includes specific verification criteria (what to check) +3. **Given** a milestone is reached during implementation, **When** the AI agent reaches it, **Then** it pauses and requests manual verification +4. **Given** multiple user stories in the spec, **When** milestones are generated, **Then** each user story maps to at least one milestone --- -### User Story 4 - Execute Commits Sequentially (Priority: P2) +### User Story 4 - Execute with Commit and Milestone Boundaries (Priority: P2) -As a developer, I want `/speckit.implement` to execute commits one at a time, completing all tasks (repetitive + non-repetitive) for each commit before moving to the next, so that the codebase remains in a working state after each commit. +As a developer, I want `/speckit.implement` to respect commit and milestone boundaries, executing tasks commit-by-commit and pausing at milestones for verification. -**Why this priority**: This ensures the commit-based workflow is actually followed during implementation. +**Why this priority**: This ensures the workflow structure is actually followed during execution. -**Independent Test**: Can be tested by running `/speckit.implement` and verifying that actual git commits are created at the defined boundaries. +**Independent Test**: Can be tested by running `/speckit.implement` and verifying it creates git commits at defined boundaries and pauses at milestones. **Acceptance Scenarios**: -1. **Given** a tasks.md with 5 planned commits, **When** I run `/speckit.implement`, **Then** the AI agent executes all tasks for commit 1 before starting commit 2 -2. **Given** a commit with repetitive TDD tasks, **When** the commit is being implemented, **Then** tests are written before implementation code -3. **Given** a commit is complete, **When** all its tasks pass, **Then** a git commit is created with the planned commit message -4. **Given** a commit fails its verification tasks (linting, tests), **When** reviewed, **Then** the implementation pauses for fixes before proceeding +1. **Given** a milestones.md with 3 milestones, **When** I run `/speckit.implement`, **Then** implementation pauses after each milestone for verification +2. **Given** a commit with repetitive tasks, **When** the commit is executed, **Then** repetitive tasks run in the correct order (test before implement) +3. **Given** a commit completes successfully, **When** all tasks pass, **Then** a git commit is created with the planned message +4. **Given** a milestone verification fails, **When** the user rejects, **Then** implementation can roll back to the milestone start --- -### User Story 5 - Constitution-Aware Task Templates (Priority: P3) +### User Story 5 - View Workflow Progress (Priority: P3) -As a project maintainer, I want to define custom repetitive task templates in the constitution, so that project-specific quality practices are automatically included in every commit. +As a developer, I want to see a visual representation of my diverge-converge workflow, so that I understand where I am in the process. -**Why this priority**: This enables customization beyond the default repetitive tasks. +**Why this priority**: Visibility into progress helps developers track complex implementations. -**Independent Test**: Can be tested by adding a custom task template to the constitution and verifying it appears in generated commits. +**Independent Test**: Can be tested by running a status command and verifying it shows current phase, completed items, and next steps. **Acceptance Scenarios**: -1. **Given** a constitution with a custom "security review" repetitive task, **When** commits are generated, **Then** each commit includes the security review task -2. **Given** a constitution with conditional repetitive tasks (e.g., "API documentation for API changes"), **When** a commit involves API changes, **Then** the conditional task is included -3. **Given** a constitution without custom templates, **When** commits are generated, **Then** default repetitive tasks based on detected patterns are used +1. **Given** a project mid-implementation, **When** I check status, **Then** I see which commits are complete and which milestone I'm working toward +2. **Given** a completed milestone, **When** I view progress, **Then** it shows verification status (passed/failed/pending) +3. **Given** multiple milestones, **When** I view the workflow, **Then** I see the full diverge-converge structure --- ### Edge Cases -- What happens when a commit's non-repetitive tasks fail but repetitive tasks pass? → The commit should not be created; implementation should pause for fixes -- How does the system handle commits that span multiple files with different test requirements? → Repetitive tasks should be aggregated at the commit level, not per-file -- What happens when the constitution is updated mid-implementation? → New commits should use updated constitution; in-progress commits continue with original requirements -- How are circular dependencies between commits handled? → Validation should fail during `/speckit.tasks` with a clear error message +- What happens when a commit's tasks fail? → The commit is not created; implementation pauses for fixes +- What happens when the constitution is updated mid-implementation? → New commits use updated constitution; in-progress commits continue with original +- How are task dependencies across commits handled? → Commits must be executed in order; cross-commit dependencies are validated during `/speckit.commits` +- What if a milestone verification is rejected? → User can choose to fix issues or roll back; implementation pauses until resolved +- What if tasks don't logically group into commits? → `/speckit.commits` suggests groupings but allows manual override ## Requirements *(mandatory)* ### Functional Requirements -- **FR-001**: The `/speckit.tasks` command MUST generate a `tasks.md` that organizes work into planned commits -- **FR-002**: Each commit MUST have a clear, conventional-format description of its deliverable -- **FR-003**: The system MUST parse the constitution to identify repetitive task requirements -- **FR-004**: Repetitive tasks MUST be automatically added to each commit based on constitution principles -- **FR-005**: Non-repetitive tasks MUST be derived from the implementation plan and organized under commits -- **FR-006**: The `/speckit.implement` command MUST execute commits sequentially, completing all tasks before creating a git commit -- **FR-007**: The system MUST validate that all repetitive tasks pass before allowing a commit to be created -- **FR-008**: Task dependencies within a commit MUST be respected during execution order -- **FR-009**: The system MUST support conditional repetitive tasks (tasks that apply only to certain types of changes) -- **FR-010**: The tasks.md format MUST clearly distinguish between repetitive and non-repetitive tasks +**Divergent Phase (existing, enhanced)**: +- **FR-001**: `/speckit.specify` MUST create a specification document +- **FR-002**: `/speckit.plan` MUST break the specification into a technical plan +- **FR-003**: `/speckit.tasks` MUST break the plan into actionable tasks + +**Convergent Phase (new)**: +- **FR-004**: `/speckit.commits` MUST group tasks into logical commits +- **FR-005**: `/speckit.commits` MUST parse the constitution and add repetitive tasks to each commit +- **FR-006**: Each commit MUST have both repetitive tasks (from constitution) and non-repetitive tasks (from plan) +- **FR-007**: `/speckit.milestones` MUST group commits into milestones with verification criteria +- **FR-008**: Each milestone MUST define what needs to be manually verified +- **FR-009**: `/speckit.implement` MUST execute tasks commit-by-commit +- **FR-010**: `/speckit.implement` MUST pause at milestones for manual verification +- **FR-011**: `/speckit.implement` MUST create git commits at defined boundaries +- **FR-012**: The system MUST support conditional repetitive tasks based on commit content ### Key Entities -- **Commit**: A planned unit of deliverable work with a description, list of tasks, and completion criteria -- **Repetitive Task**: A task derived from constitution principles that applies to every (or conditional) commit +- **Task**: The smallest unit of work (from `/speckit.tasks`) +- **Commit**: An accumulation of tasks that forms a single git commit + - Contains repetitive tasks (from constitution) + - Contains non-repetitive tasks (from plan) +- **Milestone**: An accumulation of commits that requires manual verification +- **Repetitive Task**: A task derived from constitution that applies to every (or conditional) commit - **Non-Repetitive Task**: A task specific to the implementation work of a single commit -- **Constitution Principle**: A quality requirement that may generate repetitive tasks (e.g., TDD, linting, documentation) -- **Task Dependency**: A relationship indicating one task must complete before another can begin +- **Verification Criteria**: What must be checked at a milestone (defined by user or derived from spec) ## Success Criteria *(mandatory)* ### Measurable Outcomes -- **SC-001**: 100% of commits generated by `/speckit.tasks` include repetitive tasks derived from the constitution -- **SC-002**: Users can understand the scope of each commit by reading its description alone (no need to read individual tasks) -- **SC-003**: Implementation via `/speckit.implement` creates git commits at the planned boundaries 90%+ of the time -- **SC-004**: Quality violations (failed tests, linting errors) are caught before git commits are created -- **SC-005**: Time from plan to implementation reduces by enabling AI agents to work autonomously through well-defined commit boundaries -- **SC-006**: Users report that quality practices feel "built-in" rather than "bolted on" in post-implementation surveys +- **SC-001**: 100% of commits generated include both repetitive and non-repetitive tasks +- **SC-002**: Users can understand the scope of each commit by reading its message alone +- **SC-003**: Implementation pauses at every milestone for manual verification 100% of the time +- **SC-004**: Quality violations (failed tests, linting) are caught before git commits are created +- **SC-005**: Users report clearer understanding of progress through diverge-converge visualization +- **SC-006**: Time spent on post-implementation fixes reduces due to milestone verification checkpoints ## Assumptions -- The project constitution follows the established format with clearly identifiable principles +- The project constitution follows the established format with identifiable principles - Git is available and configured in the project repository -- AI agents support the concept of executing tasks in sequence and creating commits -- The existing `/speckit.tasks` template structure can be extended to support commit-based organization -- Repetitive tasks for common patterns (TDD, linting, testing) can be detected from constitution keywords +- AI agents support pausing for human verification +- The existing `/speckit.tasks` output can be parsed for commit grouping +- Repetitive tasks can be detected from constitution keywords (TDD, lint, test, document) +- Users will perform manual verification at milestones (not skip them) + +## New Slash Commands Required + +| Command | Phase | Purpose | +| ------- | ----- | ------- | +| `/speckit.commits` | Convergent | Group tasks into commits, add constitution-driven repetitive tasks | +| `/speckit.milestones` | Convergent | Group commits into milestones with verification criteria | + +The existing `/speckit.implement` command will be enhanced to respect commit and milestone boundaries. From 58aba85b496ba199fdf9db6890bf2dfedb1a2a33 Mon Sep 17 00:00:00 2001 From: Aniket Date: Thu, 11 Dec 2025 13:49:33 +0530 Subject: [PATCH 3/6] docs: amend constitution to v1.3.0 (TDD principle + authorship policy) - Add Principle VII: Test-Driven Development (TDD) with Red-Green-Refactor workflow - Add Commit Authorship Policy: AI assistants must not be added as co-authors - Enhanced CI/CD Enforcement: make check MUST pass before any commit - Document TDD workflow by language (Python/pytest, Bash/bats, PowerShell/Pester) - Updated Code Review Checklist to verify TDD was followed - Fix markdown linting errors in README and spec --- .specify/memory/constitution.md | 74 +++++++++++++++++++++------- README.md | 3 +- specs/001-commit-based-tasks/spec.md | 7 ++- 3 files changed, 64 insertions(+), 20 deletions(-) diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 8fa140a5ed..8f2eb3458b 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,13 +1,12 @@ + diff --git a/specs/001-commit-based-tasks/contracts/commits-format.md b/specs/001-commit-based-tasks/contracts/commits-format.md new file mode 100644 index 0000000000..0d1c7c93d9 --- /dev/null +++ b/specs/001-commit-based-tasks/contracts/commits-format.md @@ -0,0 +1,200 @@ +# Contract: commits.md File Format + +**Version**: 1.0.0 +**Date**: 2025-12-11 + +## Overview + +The `commits.md` file defines how tasks from `tasks.md` are grouped into logical git commits. It is generated by the `/speckit.commits` command and consumed by `/speckit.implement`. + +## File Structure + +```markdown +# Commits: [Feature Name] + +**Generated**: [ISO 8601 timestamp] +**Source**: [path to tasks.md] +**Constitution**: [path to constitution.md] + +## Summary + +- Total Commits: [N] +- Total Tasks: [N] (non-repetitive) + [N] (repetitive) +- Stories Covered: [list] + +--- + +## Commit 1: [type(scope): description] + +**ID**: C001 +**Status**: pending | in_progress | completed | failed +**Story**: [Story reference, e.g., US1] +**Git SHA**: + +### Non-Repetitive Tasks + +- [ ] [T001] [P1] Task description `file/path.ext` +- [ ] [T002] [P1] Task description `file/path.ext` + +### Repetitive Tasks + +- [ ] [TDD-RED] Write failing test for [component] +- [ ] [TDD-GREEN] Implement [component] to pass test +- [ ] [TDD-REFACTOR] Refactor [component] if needed +- [ ] [VERIFY] Run make check + +--- + +## Commit 2: [type(scope): description] +... +``` + +## Field Specifications + +### Header Fields + +| Field | Required | Format | Description | +|-------|----------|--------|-------------| +| Feature Name | Yes | string | Name from spec.md | +| Generated | Yes | ISO 8601 | Generation timestamp | +| Source | Yes | path | Relative path to tasks.md | +| Constitution | Yes | path | Relative path to constitution.md | + +### Summary Fields + +| Field | Required | Format | Description | +|-------|----------|--------|-------------| +| Total Commits | Yes | integer | Number of commits defined | +| Total Tasks | Yes | "N + M" | Non-repetitive + repetitive counts | +| Stories Covered | Yes | list | User story references | + +### Commit Fields + +| Field | Required | Format | Description | +|-------|----------|--------|-------------| +| Heading | Yes | `## Commit N: message` | Conventional commit message | +| ID | Yes | `C###` | Unique identifier | +| Status | Yes | enum | See status values below | +| Story | Yes | string | Primary user story reference | +| Git SHA | No | hex string | **Runtime only** - populated by `/speckit.implement` after git commit is created. Empty during planning. | + +### Status Values + +- `pending`: Not yet started +- `in_progress`: Currently executing tasks +- `completed`: All tasks done, git commit created +- `failed`: Task or verification failed + +### Task Format + +Non-repetitive tasks: + +```text +- [ ] [T###] [P#] Description `optional/file/path.ext` +``` + +Repetitive tasks: + +```text +- [ ] [TEMPLATE-ID] Description for [component] +``` + +## Parsing Rules + +### For Bash Scripts + +```bash +# Extract commit count +grep -c "^## Commit" commits.md + +# Extract commit messages +grep "^## Commit" commits.md | sed 's/## Commit [0-9]*: //' + +# Extract tasks for a commit (between two ## headers) +sed -n '/^## Commit 1:/,/^## Commit 2:/p' commits.md | grep "^\- \[" + +# Check if commit completed +grep -A 3 "^## Commit 1:" commits.md | grep "Status.*completed" +``` + +### For Claude Code + +The slash command should: + +1. Read entire file as Markdown +2. Parse `## Commit N:` sections as commit boundaries +3. Extract task checkboxes from each section +4. Update status and checkbox states during execution + +## Validation Rules + +1. **Task Coverage**: Every task ID in `tasks.md` must appear in exactly one commit +2. **Commit Ordering**: Commits must be ordered by dependency (earlier commits have no dependencies on later ones) +3. **Story Consistency**: All tasks in a commit should reference the same or related stories +4. **Conventional Format**: Commit messages must follow `type(scope): description` format + +## Example + +```markdown +# Commits: Diverge-Converge Workflow + +**Generated**: 2025-12-11T10:30:00Z +**Source**: ./tasks.md +**Constitution**: ../../.specify/memory/constitution.md + +## Summary + +- Total Commits: 3 +- Total Tasks: 8 (non-repetitive) + 12 (repetitive) +- Stories Covered: US1, US2 + +--- + +## Commit 1: feat(commits): add speckit.commits slash command + +**ID**: C001 +**Status**: pending +**Story**: US1 +**Git SHA**: + +### Non-Repetitive Tasks + +- [ ] [T001] [P1] Create speckit.commits.md command file `.claude/commands/speckit.commits.md` +- [ ] [T002] [P1] Implement task grouping logic in command + +### Repetitive Tasks + +- [ ] [TDD-RED] Write failing test for commits command +- [ ] [TDD-GREEN] Implement commits command to pass test +- [ ] [TDD-REFACTOR] Refactor commits command if needed +- [ ] [VERIFY] Run make check + +--- + +## Commit 2: feat(commits): add constitution parsing + +**ID**: C002 +**Status**: pending +**Story**: US2 +**Git SHA**: + +### Non-Repetitive Tasks + +- [ ] [T003] [P1] Create parse-constitution.sh script `.specify/scripts/bash/parse-constitution.sh` +- [ ] [T004] [P1] Extract TDD requirements from constitution +- [ ] [T005] [P1] Extract linting requirements from constitution + +### Repetitive Tasks + +- [ ] [TDD-RED] Write failing test for constitution parser +- [ ] [TDD-GREEN] Implement parser to pass test +- [ ] [TDD-REFACTOR] Refactor parser if needed +- [ ] [LINT-BASH] Run shellcheck on new script +- [ ] [VERIFY] Run make check +``` + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0.0 | 2025-12-11 | Initial specification | diff --git a/specs/001-commit-based-tasks/contracts/milestones-format.md b/specs/001-commit-based-tasks/contracts/milestones-format.md new file mode 100644 index 0000000000..0a076a878c --- /dev/null +++ b/specs/001-commit-based-tasks/contracts/milestones-format.md @@ -0,0 +1,269 @@ +# Contract: milestones.md File Format + +**Version**: 1.0.0 +**Date**: 2025-12-11 + +## Overview + +The `milestones.md` file defines verification checkpoints by grouping commits into milestones. It is generated by the `/speckit.milestones` command and consumed by `/speckit.implement` to pause for manual verification. + +## File Structure + +```markdown +# Milestones: [Feature Name] + +**Generated**: [ISO 8601 timestamp] +**Source**: [path to commits.md] +**Spec**: [path to spec.md] + +## Summary + +- Total Milestones: [N] +- Total Commits: [N] +- Verification Points: [N] + +--- + +## Milestone 1: [User Story Title] + +**ID**: M001 +**Status**: pending | verification_required | verified | rejected +**Story**: [Story reference, e.g., US1] +**Priority**: P1 | P2 | P3 +**Verified At**: +**Verified By**: + +### Commits Included + +1. [C001] feat(scope): commit message +2. [C002] test(scope): commit message + +### Verification Criteria + +> Derived from acceptance scenarios in spec.md + +- [ ] [V001] Given [precondition], When [action], Then [result] +- [ ] [V002] Given [precondition], When [action], Then [result] +- [ ] [V003] Given [precondition], When [action], Then [result] + +### Manual Verification Notes + +[Space for reviewer to add comments during verification] + +--- + +## Milestone 2: [User Story Title] +... +``` + +## Field Specifications + +### Header Fields + +| Field | Required | Format | Description | +|-------|----------|--------|-------------| +| Feature Name | Yes | string | Name from spec.md | +| Generated | Yes | ISO 8601 | Generation timestamp | +| Source | Yes | path | Relative path to commits.md | +| Spec | Yes | path | Relative path to spec.md | + +### Summary Fields + +| Field | Required | Format | Description | +|-------|----------|--------|-------------| +| Total Milestones | Yes | integer | Number of milestones | +| Total Commits | Yes | integer | Sum of commits across milestones | +| Verification Points | Yes | integer | Total verification criteria | + +### Milestone Fields + +| Field | Required | Format | Description | +|-------|----------|--------|-------------| +| Heading | Yes | `## Milestone N: title` | User story title | +| ID | Yes | `M###` | Unique identifier | +| Status | Yes | enum | See status values below | +| Story | Yes | string | User story reference | +| Priority | Yes | enum | P1, P2, P3 | +| Verified At | No | ISO 8601 | Verification timestamp | +| Verified By | No | string | Reviewer identifier | + +### Status Values + +- `pending`: Commits not yet completed +- `verification_required`: All commits done, awaiting review +- `verified`: Manual verification passed +- `rejected`: Verification failed, needs fixes + +### Verification Criterion Format + +```text +- [ ] [V###] Given [precondition], When [action], Then [result] +``` + +Or for non-scenario criteria: + +```text +- [ ] [V###] [Description of what to verify] +``` + +## Parsing Rules + +### For Bash Scripts + +```bash +# Extract milestone count +grep -c "^## Milestone" milestones.md + +# Extract milestone titles +grep "^## Milestone" milestones.md | sed 's/## Milestone [0-9]*: //' + +# Check milestone status +grep -A 5 "^## Milestone 1:" milestones.md | grep "Status" + +# Extract verification criteria for a milestone +sed -n '/^## Milestone 1:/,/^## Milestone 2:/p' milestones.md | grep "^\- \[.\] \[V" + +# Count pending verifications +grep -c "\- \[ \] \[V" milestones.md +``` + +### For Claude Code + +The slash command should: + +1. Read entire file as Markdown +2. Parse `## Milestone N:` sections as milestone boundaries +3. Track status transitions +4. Pause execution when status becomes `verification_required` +5. Wait for user to update status to `verified` or `rejected` + +## Verification Flow + +```text +1. /speckit.implement executes commits +2. When all commits in milestone complete: + - Status changes to 'verification_required' + - Implementation PAUSES + - User is prompted to verify + +3. User verifies: + - Checks each criterion + - Marks [X] for passed, [ ] for failed + - Adds notes if needed + +4. User decision: + - If all pass → Status = 'verified', continue to next milestone + - If any fail → Status = 'rejected', implementation can rollback +``` + +## Validation Rules + +1. **Commit Coverage**: Every commit ID in `commits.md` must appear in exactly one milestone +2. **Milestone Ordering**: Milestones must be ordered by priority (P1 first) then dependency +3. **Story Mapping**: Each milestone must reference a user story from spec +4. **Criteria Source**: Verification criteria must trace to acceptance scenarios in spec + +## Example + +```markdown +# Milestones: Diverge-Converge Workflow + +**Generated**: 2025-12-11T11:00:00Z +**Source**: ./commits.md +**Spec**: ./spec.md + +## Summary + +- Total Milestones: 3 +- Total Commits: 8 +- Verification Points: 12 + +--- + +## Milestone 1: Group Tasks into Commits + +**ID**: M001 +**Status**: pending +**Story**: US1 +**Priority**: P1 +**Verified At**: +**Verified By**: + +### Commits Included + +1. [C001] feat(commits): add speckit.commits slash command +2. [C002] feat(commits): add task grouping algorithm +3. [C003] test(commits): add integration tests + +### Verification Criteria + +> From US1 Acceptance Scenarios + +- [ ] [V001] Given a completed tasks.md, When I run /speckit.commits, Then commits.md contains commits with grouped tasks +- [ ] [V002] Given tasks that logically belong together, When commits are generated, Then they are grouped into a single commit +- [ ] [V003] Given a generated commits list, When I review it, Then each commit has a conventional commit message +- [ ] [V004] Given independent tasks, When commits are generated, Then they are in separate commits + +### Manual Verification Notes + +--- + +## Milestone 2: Add Repetitive Tasks from Constitution + +**ID**: M002 +**Status**: pending +**Story**: US2 +**Priority**: P1 +**Verified At**: +**Verified By**: + +### Commits Included + +1. [C004] feat(constitution): add constitution parser script +2. [C005] feat(commits): integrate repetitive task injection + +### Verification Criteria + +> From US2 Acceptance Scenarios + +- [ ] [V005] Given a constitution requiring TDD, When commits are generated, Then each includes RED-GREEN-REFACTOR tasks +- [ ] [V006] Given a constitution requiring linting, When commits are generated, Then each includes "run linter" task +- [ ] [V007] Given documentation requirements, When commit changes public interfaces, Then documentation task included +- [ ] [V008] Given Playwright requirements, When commit involves UI, Then Playwright test tasks included + +### Manual Verification Notes + +--- + +## Milestone 3: Define Milestones for Verification + +**ID**: M003 +**Status**: pending +**Story**: US3 +**Priority**: P2 +**Verified At**: +**Verified By**: + +### Commits Included + +1. [C006] feat(milestones): add speckit.milestones slash command +2. [C007] feat(milestones): add verification criteria extraction +3. [C008] docs: update README with new commands + +### Verification Criteria + +> From US3 Acceptance Scenarios + +- [ ] [V009] Given completed commits.md, When I run /speckit.milestones, Then milestones.md groups commits into milestones +- [ ] [V010] Given a milestone definition, When I review it, Then it includes specific verification criteria +- [ ] [V011] Given milestone reached, When AI reaches it, Then it pauses for verification +- [ ] [V012] Given multiple user stories, When milestones generated, Then each story maps to at least one milestone + +### Manual Verification Notes +``` + +## Version History + +| Version | Date | Changes | +|---------|------|---------| +| 1.0.0 | 2025-12-11 | Initial specification | diff --git a/specs/001-commit-based-tasks/data-model.md b/specs/001-commit-based-tasks/data-model.md new file mode 100644 index 0000000000..4c3ef46ebd --- /dev/null +++ b/specs/001-commit-based-tasks/data-model.md @@ -0,0 +1,203 @@ +# Data Model: Diverge-Converge Workflow + +**Feature**: 001-commit-based-tasks +**Date**: 2025-12-11 + +## Entity Overview + +```text +┌─────────────────────────────────────────────────────────────────┐ +│ DIVERGENT │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Spec │───>│ Plan │───>│ Task │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ │ │ +├────────────────────────────────────────┼────────────────────────┤ +│ CONVERGENT │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ Commit │ │ +│ │ ┌────────┐ │ │ +│ │ │Rep.Task│ │ │ +│ │ └────────┘ │ │ +│ └──────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ │ +│ │ Milestone │ │ +│ │ ┌────────┐ │ │ +│ │ │Verify │ │ │ +│ │ └────────┘ │ │ +│ └──────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Entities + +### Task + +The smallest unit of work, generated by `/speckit.tasks`. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Unique identifier (e.g., "T001", "T002") | +| `description` | string | What needs to be done | +| `story_ref` | string | Reference to user story (e.g., "US1") | +| `priority` | enum | P1, P2, P3 | +| `phase` | string | Implementation phase (e.g., "Phase 1: Core") | +| `file_path` | string? | Target file path hint (optional) | +| `status` | enum | pending, in_progress, completed, skipped | +| `dependencies` | string[] | List of task IDs this depends on | + +**Source**: `tasks.md` (generated by `/speckit.tasks`) + +**Example**: + +```markdown +- [ ] [T001] [P1] [US1] Create speckit.commits.md slash command `/.claude/commands/speckit.commits.md` +``` + +### RepetitiveTask + +A task derived from constitution that applies to commits based on triggers. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Template identifier (e.g., "TDD-RED", "LINT-BASH") | +| `name` | string | Human-readable task name | +| `source` | string | Constitution section reference | +| `trigger` | enum | code_change, bash_script, python_code, markdown, all | +| `order` | number | Execution order within commit (lower = earlier) | +| `phase` | string? | TDD phase (RED, GREEN, REFACTOR) if applicable | + +**Source**: Constitution parsing (`.specify/memory/constitution.md`) + +**Instances** (from current constitution): + +| ID | Name | Trigger | Order | +|----|------|---------|-------| +| TDD-RED | Write failing test | code_change | 1 | +| TDD-GREEN | Implement to pass test | code_change | 2 | +| TDD-REFACTOR | Refactor while green | code_change | 3 | +| LINT-BASH | Run shellcheck | bash_script | 90 | +| LINT-PYTHON | Run ruff check | python_code | 90 | +| LINT-MD | Run markdownlint | markdown | 90 | +| VERIFY | Run make check | all | 99 | + +### Commit + +An accumulation of tasks that forms a single git commit. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Commit identifier (e.g., "C001") | +| `message` | string | Conventional commit message | +| `type` | enum | feat, fix, test, refactor, docs, chore | +| `scope` | string? | Affected component (optional) | +| `story_ref` | string | Primary user story reference | +| `status` | enum | pending, in_progress, completed, failed | +| `tasks` | Task[] | Non-repetitive tasks in this commit | +| `repetitive_tasks` | RepetitiveTask[] | Constitution-derived tasks | +| `git_sha` | string? | **Runtime only** - populated by `/speckit.implement` after git commit created | + +**Source**: `commits.md` (generated by `/speckit.commits`) + +**Relationships**: + +- Contains 1..n Tasks (non-repetitive) +- Contains 0..n RepetitiveTasks (based on triggers) +- Belongs to 1 Milestone + +**Validation Rules**: + +1. At least one non-repetitive task required +2. All tasks must have same or compatible story_ref +3. Task dependencies must be satisfiable within commit or prior commits + +### Milestone + +An accumulation of commits requiring manual verification. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Milestone identifier (e.g., "M001") | +| `title` | string | User story title or custom name | +| `story_ref` | string | Primary user story reference | +| `priority` | enum | P1, P2, P3 (inherited from story) | +| `status` | enum | pending, verification_required, verified, rejected | +| `commits` | Commit[] | Commits included in this milestone | +| `verification_criteria` | VerificationCriterion[] | What to check | +| `verification_notes` | string? | **Runtime only** - reviewer comments added during verification | +| `verified_at` | datetime? | **Runtime only** - populated when milestone is verified | +| `verified_by` | string? | **Runtime only** - populated when milestone is verified | + +**Source**: `milestones.md` (generated by `/speckit.milestones`) + +**Relationships**: + +- Contains 1..n Commits +- Has 1..n VerificationCriteria + +### VerificationCriterion + +A specific check to perform at milestone verification. + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Criterion identifier (e.g., "V001") | +| `description` | string | What to verify (from acceptance scenario) | +| `source` | string | "spec" or "manual" | +| `status` | enum | pending, passed, failed | +| `notes` | string? | Verification notes | + +**Source**: Acceptance scenarios from `spec.md` + +## State Transitions + +### Task Status + +```text +pending ──> in_progress ──> completed + │ + └──> skipped (if blocked or not needed) +``` + +### Commit Status + +```text +pending ──> in_progress ──> completed ──> [git commit created] + │ + └──> failed (tests fail, lint errors) + │ + └──> pending (after fixes) +``` + +### Milestone Status + +```text +pending ──> verification_required ──> verified + │ + └──> rejected ──> pending (rollback) +``` + +## Relationships Summary + +```text +Specification (1) ──contains──> (n) User Stories +User Story (1) ──maps to──> (1..n) Milestones +Milestone (1) ──contains──> (1..n) Commits +Commit (1) ──contains──> (1..n) Tasks +Commit (1) ──contains──> (0..n) Repetitive Tasks +Task (n) ──references──> (1) User Story +Constitution (1) ──defines──> (n) Repetitive Task Templates +``` + +## File Artifacts + +| Entity | File | Generated By | +|--------|------|--------------| +| Task | `tasks.md` | `/speckit.tasks` | +| Commit | `commits.md` | `/speckit.commits` | +| Milestone | `milestones.md` | `/speckit.milestones` | +| RepetitiveTask | (parsed at runtime) | `/speckit.commits` from constitution | +| VerificationCriterion | `milestones.md` | `/speckit.milestones` from spec | diff --git a/specs/001-commit-based-tasks/plan.md b/specs/001-commit-based-tasks/plan.md new file mode 100644 index 0000000000..88c7dff3ce --- /dev/null +++ b/specs/001-commit-based-tasks/plan.md @@ -0,0 +1,111 @@ +# Implementation Plan: Diverge-Converge Workflow + +**Branch**: `001-commit-based-tasks` | **Date**: 2025-12-11 | **Spec**: [spec.md](./spec.md) +**Input**: Feature specification from `/specs/001-commit-based-tasks/spec.md` + +## Summary + +Implement the **Diverge-Converge** workflow model that extends Spec Kit's existing divergent phases (specify → plan → tasks) with convergent phases (tasks → commits → milestones). This introduces two new slash commands (`/speckit.commits` and `/speckit.milestones`) and enhances `/speckit.implement` to respect commit boundaries and pause at milestones for manual verification. Constitution-driven repetitive tasks (TDD, linting) are automatically added to each commit. + +## Technical Context + +**Language/Version**: Markdown (slash commands), Bash 5.x (scripts), Python 3.11+ (CLI utilities if needed) +**Primary Dependencies**: Existing Spec Kit infrastructure (check-prerequisites.sh, common.sh), Claude Code slash command system +**Storage**: Markdown files (commits.md, milestones.md) in feature specs directory +**Testing**: bats-core (Bash script tests), pytest (Python utility tests), manual slash command validation +**Target Platform**: Cross-platform (macOS, Linux, Windows via WSL/PowerShell) +**Project Type**: CLI tool extension (single project structure) +**Performance Goals**: N/A (command-line tool, not latency-sensitive) +**Constraints**: Must follow TDD workflow, `make check` must pass before commits +**Scale/Scope**: 2 new slash commands, 1 enhanced command, ~3 new scripts, ~5 new markdown artifacts + +## Constitution Check + +*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* + +| Principle | Gate | Status | +|-----------|------|--------| +| I. Code Quality Through Linting | Bash scripts must pass `shellcheck`, Markdown must pass `markdownlint-cli2` | ✅ PASS | +| II. Test Coverage for Scripts | New bash scripts must have `bats-core` tests | ✅ PASS (will implement) | +| III. CI/CD Enforcement | `make check` must pass before any commit | ✅ PASS | +| V. Cross-Platform Parity | Bash scripts must have PowerShell equivalents | ⚠️ DEFERRED (PowerShell scripts pending) | +| VI. Documentation Maintenance | README updated with new commands | ✅ PASS (will update) | +| VII. TDD | Tests written before implementation (Red-Green-Refactor) | ✅ PASS (will follow) | +| Commit Authorship | No AI co-authors on commits | ✅ PASS | + +**Gate Evaluation**: All critical gates pass. Cross-platform parity (Principle V) is deferred as PowerShell test infrastructure is marked "pending" in the constitution. New scripts will have bash implementations first, with PowerShell equivalents tracked as follow-up. + +## Project Structure + +### Documentation (this feature) + +```text +specs/001-commit-based-tasks/ +├── spec.md # Feature specification (completed) +├── plan.md # This file +├── research.md # Phase 0 output - design decisions +├── data-model.md # Phase 1 output - entity definitions +├── quickstart.md # Phase 1 output - integration test scenarios +├── contracts/ # Phase 1 output - file format specifications +│ ├── commits-format.md # commits.md file format contract +│ └── milestones-format.md # milestones.md file format contract +├── checklists/ # Quality checklists (exists) +│ └── requirements.md # Specification quality checklist (completed) +└── tasks.md # Phase 2 output (/speckit.tasks command) +``` + +### Source Code (repository root) + +```text +.claude/commands/ +├── speckit.commits.md # NEW: Group tasks into commits +├── speckit.milestones.md # NEW: Group commits into milestones +└── speckit.implement.md # ENHANCED: Respect commits/milestones + +.specify/ +├── scripts/bash/ +│ ├── common.sh # ENHANCED: Add commit/milestone path helpers +│ ├── check-prerequisites.sh # ENHANCED: Add --require-commits flag +│ └── parse-constitution.sh # NEW: Extract repetitive tasks from constitution +├── templates/ +│ ├── commits-template.md # NEW: Template for commits.md output +│ └── milestones-template.md # NEW: Template for milestones.md output +└── memory/ + └── constitution.md # Reference only (already has TDD requirements) + +tests/bash/ +├── test_parse_constitution.bats # NEW: Tests for constitution parsing +└── test_check_prerequisites.bats # NEW: Tests for enhanced prerequisites +``` + +**Structure Decision**: Single project structure (Option 1). This feature extends the existing Spec Kit CLI tool by adding new slash commands and enhancing existing scripts. No new Python code is required - the implementation is primarily Markdown (slash commands) and Bash (helper scripts). + +## Complexity Tracking + +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| PowerShell parity deferred | Pester test infrastructure not yet implemented | Cannot block feature on missing test framework; tracked as follow-up | + +## Implementation Phases + +### Phase 0: Research & Design Decisions + +Key decisions to document in `research.md`: + +1. **Task Grouping Algorithm**: How to automatically group tasks into commits +2. **Constitution Parsing**: How to extract repetitive tasks from constitution keywords +3. **Milestone Boundary Detection**: How to determine where milestones should be placed +4. **Commit Message Generation**: Format and content of auto-generated commit messages + +### Phase 1: Design Artifacts + +1. **data-model.md**: Define entities (Task, Commit, Milestone, RepetitiveTask) +2. **contracts/commits-format.md**: File format specification for commits.md +3. **contracts/milestones-format.md**: File format specification for milestones.md +4. **quickstart.md**: Integration test scenarios for the new commands + +### Phase 2: Implementation (via /speckit.tasks) + +Tasks will be generated by the `/speckit.tasks` command based on this plan. diff --git a/specs/001-commit-based-tasks/quickstart.md b/specs/001-commit-based-tasks/quickstart.md new file mode 100644 index 0000000000..1a0c6681bd --- /dev/null +++ b/specs/001-commit-based-tasks/quickstart.md @@ -0,0 +1,265 @@ +# Quickstart: Diverge-Converge Workflow + +**Feature**: 001-commit-based-tasks +**Date**: 2025-12-11 + +## Prerequisites + +Before testing the diverge-converge workflow, ensure: + +1. Spec Kit is installed and configured +2. A feature specification exists with user stories +3. `tasks.md` has been generated via `/speckit.tasks` +4. Constitution file exists at `.specify/memory/constitution.md` + +## Integration Test Scenarios + +### Scenario 1: Basic Commit Generation + +**Purpose**: Verify `/speckit.commits` groups tasks correctly + +**Setup**: + +```bash +# Create a test feature with sample tasks +mkdir -p specs/test-feature +cat > specs/test-feature/tasks.md << 'EOF' +# Tasks: Test Feature + +## Phase 1: Core Implementation + +- [ ] [T001] [P1] [US1] Create user model `src/models/user.py` +- [ ] [T002] [P1] [US1] Create user service `src/services/user.py` +- [ ] [T003] [P1] [US1] Create user API endpoint `src/api/user.py` +- [ ] [T004] [P1] [US2] Create auth middleware `src/middleware/auth.py` +EOF +``` + +**Execute**: + +```text +/speckit.commits +``` + +**Expected Output**: + +- `commits.md` created in `specs/test-feature/` +- T001, T002, T003 grouped into one commit (same story US1, related files) +- T004 in separate commit (different story US2) +- Each commit includes TDD repetitive tasks from constitution + +**Verification**: + +```bash +# Check commits file exists +test -f specs/test-feature/commits.md && echo "PASS" || echo "FAIL" + +# Check task grouping (US1 tasks together) +grep -A 20 "## Commit 1:" specs/test-feature/commits.md | grep -c "\[US1\]" +# Expected: 3 + +# Check repetitive tasks present +grep -c "TDD-RED" specs/test-feature/commits.md +# Expected: >= 2 (one per commit) +``` + +### Scenario 2: Constitution-Driven Repetitive Tasks + +**Purpose**: Verify repetitive tasks are injected based on constitution + +**Setup**: + +Ensure constitution has TDD requirements: + +```bash +grep "TDD" .specify/memory/constitution.md +# Should find "Test-Driven Development" section +``` + +**Execute**: + +```text +/speckit.commits +``` + +**Expected Output**: + +For each commit in `commits.md`: + +- `[TDD-RED] Write failing test for [component]` +- `[TDD-GREEN] Implement [component] to pass test` +- `[TDD-REFACTOR] Refactor [component] if needed` +- `[VERIFY] Run make check` + +**Verification**: + +```bash +# Count TDD tasks per commit +for commit in $(grep "^## Commit" specs/test-feature/commits.md | wc -l | tr -d ' '); do + echo "Checking commit $commit" +done + +# Each commit should have 4 repetitive tasks +grep -c "\[TDD-" specs/test-feature/commits.md +# Expected: 3 * number_of_commits (RED, GREEN, REFACTOR) +``` + +### Scenario 3: Milestone Generation + +**Purpose**: Verify `/speckit.milestones` creates verification checkpoints + +**Setup**: + +Ensure `commits.md` exists from Scenario 1 + +**Execute**: + +```text +/speckit.milestones +``` + +**Expected Output**: + +- `milestones.md` created in `specs/test-feature/` +- Milestones aligned with user stories (US1, US2) +- Verification criteria derived from spec acceptance scenarios +- P1 stories get separate milestones + +**Verification**: + +```bash +# Check milestones file exists +test -f specs/test-feature/milestones.md && echo "PASS" || echo "FAIL" + +# Check milestone count matches story count +grep -c "^## Milestone" specs/test-feature/milestones.md +# Expected: >= 2 (one per user story minimum) + +# Check verification criteria present +grep -c "\[V0" specs/test-feature/milestones.md +# Expected: >= 4 (multiple criteria per milestone) +``` + +### Scenario 4: Implementation with Commit Boundaries + +**Purpose**: Verify `/speckit.implement` respects commit boundaries + +**Setup**: + +Ensure `tasks.md`, `commits.md`, and `milestones.md` exist + +**Execute**: + +```text +/speckit.implement +``` + +**Expected Behavior**: + +1. Loads all three documents +2. Executes tasks in commit order (C001 before C002) +3. Within each commit, executes TDD cycle: + - RED: Write test (should fail) + - GREEN: Implement (test passes) + - REFACTOR: Clean up + - VERIFY: Run `make check` +4. Creates git commit with planned message after all tasks pass +5. Pauses at milestone boundaries for verification + +**Verification**: + +```bash +# Check git commits created +git log --oneline -5 +# Should see commits matching messages from commits.md + +# Check commit messages follow conventional format +git log --oneline -5 | grep -E "^[a-f0-9]+ (feat|fix|test|refactor|docs|chore)" +``` + +### Scenario 5: Milestone Verification Pause + +**Purpose**: Verify implementation pauses at milestones + +**Setup**: + +Run `/speckit.implement` until first milestone completes + +**Expected Behavior**: + +1. When all commits in Milestone 1 complete +2. Status in `milestones.md` changes to `verification_required` +3. Implementation pauses +4. User prompted with verification criteria +5. User must manually verify and update status + +**Verification**: + +```bash +# Check milestone status changed +grep "Status.*verification_required" specs/test-feature/milestones.md +# Should find at least one milestone in this state + +# Check verification criteria shown to user +grep "\[V0" specs/test-feature/milestones.md | head -5 +# User should see these criteria and check them +``` + +### Scenario 6: Missing Document Error + +**Purpose**: Verify `/speckit.implement` fails gracefully without required documents + +**Setup**: + +```bash +# Remove commits.md +mv specs/test-feature/commits.md specs/test-feature/commits.md.bak +``` + +**Execute**: + +```text +/speckit.implement +``` + +**Expected Output**: + +- Clear error message +- Instruction to run `/speckit.commits` first +- Implementation does not start + +**Verification**: + +```bash +# Restore file +mv specs/test-feature/commits.md.bak specs/test-feature/commits.md +``` + +## Cleanup + +```bash +# Remove test feature +rm -rf specs/test-feature +``` + +## Manual Testing Checklist + +- [ ] `/speckit.commits` generates valid `commits.md` +- [ ] Tasks are grouped by story and file proximity +- [ ] Repetitive tasks appear in every commit +- [ ] `/speckit.milestones` generates valid `milestones.md` +- [ ] Milestones align with user stories +- [ ] Verification criteria match spec scenarios +- [ ] `/speckit.implement` loads all three documents +- [ ] Implementation follows commit order +- [ ] TDD cycle enforced within each commit +- [ ] Git commits created at commit boundaries +- [ ] Implementation pauses at milestones +- [ ] Verification status can be updated +- [ ] Missing documents produce clear errors + +## Performance Notes + +- Commit generation should complete in < 5 seconds for typical task lists +- Milestone generation should complete in < 3 seconds +- Document loading should be instant (file reads only) diff --git a/specs/001-commit-based-tasks/research.md b/specs/001-commit-based-tasks/research.md new file mode 100644 index 0000000000..a8a21e7e98 --- /dev/null +++ b/specs/001-commit-based-tasks/research.md @@ -0,0 +1,244 @@ +# Research: Diverge-Converge Workflow + +**Feature**: 001-commit-based-tasks +**Date**: 2025-12-11 + +## Decision 1: Task Grouping Algorithm + +### Decision + +Use **semantic grouping** based on task relationships and file paths to group tasks into commits. Tasks that operate on the same entity, module, or feature component are grouped together. + +### Rationale + +- Tasks in `tasks.md` already have file path hints (e.g., `src/models/user.py`) +- Tasks referencing the same file or directory naturally belong together +- User stories in specs provide natural grouping boundaries +- This approach is deterministic and explainable to users + +### Alternatives Considered + +1. **Sequential grouping (N tasks per commit)**: Rejected - arbitrary boundaries ignore logical relationships +2. **Single-task commits**: Rejected - too granular, creates noise in git history +3. **AI-based semantic analysis**: Rejected - non-deterministic, harder to test and explain + +### Implementation Approach + +```text +Grouping Rules (in order of priority): +1. Tasks with same [Story] tag → same commit +2. Tasks referencing same file → same commit +3. Tasks in same phase/category → suggest same commit +4. Override: Tasks marked [ATOMIC] → single commit +``` + +## Decision 2: Constitution Parsing for Repetitive Tasks + +### Decision + +Parse constitution for **keyword-triggered repetitive tasks** using section headers and requirement keywords. + +### Rationale + +- Constitution v1.3.0 has clear section headers (e.g., "VII. Test-Driven Development") +- Keywords like "TDD", "lint", "test", "verify" indicate quality requirements +- Each principle has explicit requirements that can be mapped to tasks + +### Detected Repetitive Tasks from Constitution + +| Constitution Section | Trigger | Repetitive Tasks | +|---------------------|---------|------------------| +| VII. TDD | All code changes | 1. Write failing test (RED), 2. Implement (GREEN), 3. Refactor | +| I. Code Quality | Bash scripts | Run `shellcheck` | +| I. Code Quality | Python code | Run `ruff check` and `ruff format --check` | +| I. Code Quality | Markdown | Run `markdownlint-cli2` | +| III. CI/CD | Before commit | Run `make check` | + +### Implementation Approach + +```text +parse-constitution.sh: + Input: .specify/memory/constitution.md + Output: JSON array of repetitive task templates + + { + "tdd": { + "trigger": "code_change", + "tasks": [ + {"order": 1, "name": "Write failing test", "phase": "RED"}, + {"order": 2, "name": "Implement feature", "phase": "GREEN"}, + {"order": 3, "name": "Refactor if needed", "phase": "REFACTOR"}, + {"order": 4, "name": "Verify tests pass", "phase": "VERIFY"} + ] + }, + "lint_bash": { + "trigger": "*.sh", + "tasks": [{"order": 99, "name": "Run shellcheck"}] + } + } +``` + +## Decision 3: Milestone Boundary Detection + +### Decision + +Place milestones at **user story boundaries** from the specification, with each milestone representing a complete, verifiable feature increment. + +### Rationale + +- User stories in specs have acceptance criteria - natural verification points +- Each story represents user-facing value that can be demonstrated +- Aligns with agile milestone concepts +- Clear mapping: 1 user story = 1 milestone (minimum) + +### Alternatives Considered + +1. **Time-based milestones**: Rejected - not meaningful for quality verification +2. **Commit-count milestones (every N commits)**: Rejected - arbitrary, ignores semantic boundaries +3. **File-change milestones**: Rejected - doesn't reflect user value + +### Implementation Approach + +```text +Milestone Generation Rules: +1. Each P1 user story → separate milestone (critical path) +2. P2/P3 stories → can be grouped into shared milestones +3. Milestones include verification criteria from story's acceptance scenarios +4. Each milestone lists its constituent commits +``` + +## Decision 4: Commit Message Generation + +### Decision + +Generate commit messages following **Conventional Commits** format with story references. + +### Rationale + +- Constitution already requires conventional format (`type: description`) +- Consistent with existing project standards +- Enables automated changelog generation +- Story references provide traceability + +### Format Specification + +```text +type(scope): description + +- Task 1 completed +- Task 2 completed + +Story: [Story ID from spec] +``` + +**Types** (from constitution): + +- `feat`: New feature +- `fix`: Bug fix +- `test`: Adding tests (TDD RED phase) +- `refactor`: Code restructuring (TDD REFACTOR phase) +- `docs`: Documentation updates +- `chore`: Maintenance tasks + +### Example + +```text +feat(commits): add task grouping algorithm + +- Implement semantic grouping based on file paths +- Add story-based task clustering +- Create commit boundary detection + +Story: US1 - Group Tasks into Commits +``` + +## Decision 5: File Format for commits.md + +### Decision + +Use **hierarchical Markdown** with YAML-like metadata blocks for machine parseability. + +### Rationale + +- Consistent with existing Spec Kit artifacts (all Markdown) +- Human-readable and editable +- Can be parsed by both bash (grep/sed) and Claude Code +- Supports both automated generation and manual override + +### Format + +```markdown +# Commits: [Feature Name] + +## Commit 1: [Conventional message] + +**Status**: pending | in_progress | completed +**Story**: [Story reference] + +### Non-Repetitive Tasks + +- [ ] [T001] Task description +- [ ] [T002] Task description + +### Repetitive Tasks (from Constitution) + +- [ ] [TDD-RED] Write failing test for [component] +- [ ] [TDD-GREEN] Implement [component] +- [ ] [TDD-REFACTOR] Refactor [component] +- [ ] [LINT] Run make check + +--- + +## Commit 2: [Conventional message] +... +``` + +## Decision 6: File Format for milestones.md + +### Decision + +Use **Markdown with verification checklists** derived from acceptance scenarios. + +### Format + +```markdown +# Milestones: [Feature Name] + +## Milestone 1: [User Story Title] + +**Status**: pending | verification_required | verified | rejected +**Story**: [Story reference] +**Priority**: P1 | P2 | P3 + +### Commits Included + +1. Commit 1: [message] +2. Commit 2: [message] + +### Verification Criteria + +From acceptance scenarios in spec: + +- [ ] Given X, When Y, Then Z (Scenario 1) +- [ ] Given A, When B, Then C (Scenario 2) + +### Manual Verification Notes + +[Space for reviewer comments] + +--- + +## Milestone 2: [User Story Title] +... +``` + +## Summary of Decisions + +| Decision | Choice | Key Rationale | +|----------|--------|---------------| +| Task grouping | Semantic (story + file-based) | Deterministic, meaningful boundaries | +| Constitution parsing | Keyword-triggered templates | Maps directly to constitution sections | +| Milestone boundaries | User story boundaries | Natural verification points | +| Commit messages | Conventional Commits + story ref | Consistent with project standards | +| commits.md format | Hierarchical Markdown | Human and machine readable | +| milestones.md format | Markdown with checklists | Verification criteria from specs | diff --git a/specs/001-commit-based-tasks/tasks.md b/specs/001-commit-based-tasks/tasks.md new file mode 100644 index 0000000000..1bccfa13bd --- /dev/null +++ b/specs/001-commit-based-tasks/tasks.md @@ -0,0 +1,289 @@ +# Tasks: Diverge-Converge Workflow + +**Input**: Design documents from `/specs/001-commit-based-tasks/` +**Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/ + +**Tests**: Tests are included as this feature requires TDD per constitution (Principle VII). + +**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: Can run in parallel (different files, no dependencies) +- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) +- Include exact file paths in descriptions + +## Path Conventions + +- **Slash commands**: `.claude/commands/` +- **Bash scripts**: `.specify/scripts/bash/` +- **Templates**: `.specify/templates/` +- **Tests**: `tests/bash/` + +--- + +## Phase 1: Setup (Shared Infrastructure) + +**Purpose**: Project initialization and template creation + +- [ ] T001 Create commits-template.md for commits.md output `.specify/templates/commits-template.md` +- [ ] T002 [P] Create milestones-template.md for milestones.md output `.specify/templates/milestones-template.md` + +--- + +## Phase 2: Foundational (Blocking Prerequisites) + +**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented + +**CRITICAL**: No user story work can begin until this phase is complete + +- [ ] T003 Write bats test for parse-constitution.sh `tests/bash/test_parse_constitution.bats` +- [ ] T004 Create parse-constitution.sh script to extract repetitive tasks from constitution `.specify/scripts/bash/parse-constitution.sh` +- [ ] T005 Write bats test for enhanced check-prerequisites.sh flags `tests/bash/test_check_prerequisites.bats` +- [ ] T006 Enhance check-prerequisites.sh with --require-commits and --include-commits flags `.specify/scripts/bash/check-prerequisites.sh` +- [ ] T007 [P] Add COMMITS and MILESTONES path helpers to common.sh `.specify/scripts/bash/common.sh` + +**Checkpoint**: Foundation ready - user story implementation can now begin + +--- + +## Phase 3: User Story 1 - Group Tasks into Commits (Priority: P1) + +**Goal**: Create `/speckit.commits` command that groups tasks into logical commits + +**Independent Test**: Run `/speckit.commits` on a tasks.md and verify commits.md contains commit groupings with task assignments + +### Tests for User Story 1 + +> **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** + +- [ ] T008 [US1] Write bats test for task grouping by story tag `tests/bash/test_commits_grouping.bats` +- [ ] T009 [US1] Write bats test for commit message generation `tests/bash/test_commits_grouping.bats` + +### Implementation for User Story 1 + +- [ ] T010 [US1] Create speckit.commits.md slash command with outline structure `.claude/commands/speckit.commits.md` +- [ ] T011 [US1] Implement task parsing logic in speckit.commits.md (read tasks.md, extract task IDs and story refs) `.claude/commands/speckit.commits.md` +- [ ] T012 [US1] Implement semantic grouping algorithm (group by [Story] tag, then by file path) `.claude/commands/speckit.commits.md` +- [ ] T013 [US1] Implement conventional commit message generation for each group `.claude/commands/speckit.commits.md` +- [ ] T014 [US1] Implement commits.md output following contracts/commits-format.md specification `.claude/commands/speckit.commits.md` +- [ ] T015 [US1] Add handoffs to speckit.milestones in command frontmatter `.claude/commands/speckit.commits.md` + +**Checkpoint**: User Story 1 complete - `/speckit.commits` generates commits.md with grouped tasks + +--- + +## Phase 4: User Story 2 - Add Repetitive Tasks from Constitution (Priority: P1) + +**Goal**: `/speckit.commits` automatically adds constitution-driven repetitive tasks to each commit + +**Independent Test**: Run `/speckit.commits` with a constitution requiring TDD and verify each commit includes RED-GREEN-REFACTOR tasks + +### Tests for User Story 2 + +> **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** + +- [ ] T016 [US2] Write bats test for TDD task injection `tests/bash/test_repetitive_tasks.bats` +- [ ] T017 [US2] Write bats test for conditional linting task injection `tests/bash/test_repetitive_tasks.bats` + +### Implementation for User Story 2 + +- [ ] T018 [US2] Integrate parse-constitution.sh output into speckit.commits.md workflow `.claude/commands/speckit.commits.md` +- [ ] T019 [US2] Implement TDD repetitive task injection (RED, GREEN, REFACTOR per commit) `.claude/commands/speckit.commits.md` +- [ ] T020 [US2] Implement conditional linting task injection (shellcheck for .sh, ruff for .py) `.claude/commands/speckit.commits.md` +- [ ] T021 [US2] Implement VERIFY task injection (make check) at end of each commit `.claude/commands/speckit.commits.md` +- [ ] T022 [US2] Update commits.md output to include Repetitive Tasks section per commit `.claude/commands/speckit.commits.md` + +**Checkpoint**: User Story 2 complete - `/speckit.commits` adds constitution-driven repetitive tasks + +--- + +## Phase 5: User Story 3 - Define Milestones for Verification (Priority: P2) + +**Goal**: Create `/speckit.milestones` command that groups commits into milestones with verification criteria + +**Independent Test**: Run `/speckit.milestones` on commits.md and verify milestones.md contains milestone boundaries with verification criteria from spec + +### Tests for User Story 3 + +> **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** + +- [ ] T023 [US3] Write bats test for milestone boundary detection `tests/bash/test_milestones.bats` +- [ ] T024 [US3] Write bats test for verification criteria extraction from spec `tests/bash/test_milestones.bats` + +### Implementation for User Story 3 + +- [ ] T025 [US3] Create speckit.milestones.md slash command with outline structure `.claude/commands/speckit.milestones.md` +- [ ] T026 [US3] Implement commits.md parsing to extract commit IDs and story refs `.claude/commands/speckit.milestones.md` +- [ ] T027 [US3] Implement milestone boundary detection (group commits by user story) `.claude/commands/speckit.milestones.md` +- [ ] T028 [US3] Implement verification criteria extraction from spec.md acceptance scenarios `.claude/commands/speckit.milestones.md` +- [ ] T029 [US3] Implement milestones.md output following contracts/milestones-format.md specification `.claude/commands/speckit.milestones.md` +- [ ] T030 [US3] Add handoffs to speckit.implement in command frontmatter `.claude/commands/speckit.milestones.md` + +**Checkpoint**: User Story 3 complete - `/speckit.milestones` generates milestones.md with verification criteria + +--- + +## Phase 6: User Story 4 - Execute with Commit and Milestone Boundaries (Priority: P2) + +**Goal**: Enhance `/speckit.implement` to load commits.md and milestones.md, execute tasks commit-by-commit, pause at milestones + +**Independent Test**: Run `/speckit.implement` and verify it loads all three documents, creates git commits at boundaries, and pauses at milestones + +### Tests for User Story 4 + +> **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** + +- [ ] T031 [US4] Write bats test for document existence validation `tests/bash/test_implement_enhanced.bats` +- [ ] T032 [US4] Write bats test for commit boundary detection `tests/bash/test_implement_enhanced.bats` + +### Implementation for User Story 4 + +- [ ] T033 [US4] Add document validation to speckit.implement.md (require commits.md, milestones.md) `.claude/commands/speckit.implement.md` +- [ ] T034 [US4] Update check-prerequisites.sh call to use --require-commits --include-commits flags `.claude/commands/speckit.implement.md` +- [ ] T035 [US4] Implement commit-by-commit execution flow (execute tasks grouped by commit) `.claude/commands/speckit.implement.md` +- [ ] T036 [US4] Implement git commit creation at commit boundaries with planned message `.claude/commands/speckit.implement.md` +- [ ] T037 [US4] Implement milestone pause logic (pause and prompt for verification when milestone reached) `.claude/commands/speckit.implement.md` +- [ ] T038 [US4] Implement verification status tracking (update milestones.md status field) `.claude/commands/speckit.implement.md` +- [ ] T039 [US4] Add clear error messages when commits.md or milestones.md missing `.claude/commands/speckit.implement.md` + +**Checkpoint**: User Story 4 complete - `/speckit.implement` respects commit and milestone boundaries + +--- + +## Phase 7: User Story 5 - View Workflow Progress (Priority: P3) + +**Goal**: Visual representation of diverge-converge workflow progress + +**Independent Test**: Run status check mid-implementation and verify it shows current phase, completed items, and next steps + +### Implementation for User Story 5 + +- [ ] T040 [US5] Add progress display section to speckit.implement.md showing commit/milestone status `.claude/commands/speckit.implement.md` +- [ ] T041 [US5] Implement ASCII progress visualization (commits completed, current milestone, remaining) `.claude/commands/speckit.implement.md` +- [ ] T042 [US5] Display verification status for completed milestones (passed/failed/pending) `.claude/commands/speckit.implement.md` + +**Checkpoint**: User Story 5 complete - workflow progress is visible during implementation + +--- + +## Phase 8: Polish & Cross-Cutting Concerns + +**Purpose**: Documentation and cleanup + +- [ ] T043 [P] Update README.md with new commands documentation `README.md` +- [ ] T044 [P] Add command usage examples to each new slash command `.claude/commands/speckit.commits.md`, `.claude/commands/speckit.milestones.md` +- [ ] T045 Run all bats tests to verify implementation `tests/bash/` +- [ ] T046 Run make check to verify linting passes +- [ ] T047 Run quickstart.md validation scenarios `specs/001-commit-based-tasks/quickstart.md` + +--- + +## Dependencies & Execution Order + +### Phase Dependencies + +- **Setup (Phase 1)**: No dependencies - can start immediately +- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories +- **User Stories (Phase 3-7)**: All depend on Foundational phase completion + - US1 and US2 can proceed in parallel (both modify speckit.commits.md but at different aspects) + - US3 depends on US1/US2 (needs commits.md to exist) + - US4 depends on US3 (needs milestones.md to exist) + - US5 depends on US4 (enhances implement command) +- **Polish (Phase 8)**: Depends on all user stories being complete + +### User Story Dependencies + +- **User Story 1 (P1)**: Can start after Foundational - No dependencies on other stories +- **User Story 2 (P1)**: Can start after Foundational - Integrates with US1 (same command) +- **User Story 3 (P2)**: Depends on US1/US2 completion (needs commits.md format finalized) +- **User Story 4 (P2)**: Depends on US3 completion (needs milestones.md) +- **User Story 5 (P3)**: Depends on US4 completion (enhances implement command) + +### Within Each User Story + +- Tests MUST be written and FAIL before implementation (TDD RED) +- Implement to pass tests (TDD GREEN) +- Refactor while tests pass (TDD REFACTOR) +- Run make check before considering story complete + +### Parallel Opportunities + +- T001 and T002 (templates) can run in parallel +- T003/T004 and T005/T006 can run in parallel (different scripts) +- T008/T009 (US1 tests) can run in parallel +- T016/T017 (US2 tests) can run in parallel +- T023/T024 (US3 tests) can run in parallel +- T031/T032 (US4 tests) can run in parallel +- T043/T044 (documentation) can run in parallel + +--- + +## Parallel Example: Foundational Phase + +```bash +# Launch script development in parallel: +Task: "Write bats test for parse-constitution.sh" + "Create parse-constitution.sh" +Task: "Write bats test for check-prerequisites.sh" + "Enhance check-prerequisites.sh" +Task: "Add path helpers to common.sh" +``` + +--- + +## Implementation Strategy + +### MVP First (User Stories 1 + 2 Only) + +1. Complete Phase 1: Setup (templates) +2. Complete Phase 2: Foundational (scripts and tests) +3. Complete Phase 3: User Story 1 (basic commit grouping) +4. Complete Phase 4: User Story 2 (repetitive tasks) +5. **STOP and VALIDATE**: Test `/speckit.commits` independently +6. Can use commits.md manually without milestones.md + +### Incremental Delivery + +1. Complete Setup + Foundational → Foundation ready +2. Add User Story 1 + 2 → `/speckit.commits` works (MVP!) +3. Add User Story 3 → `/speckit.milestones` works +4. Add User Story 4 → `/speckit.implement` enhanced +5. Add User Story 5 → Progress visualization +6. Each story adds value without breaking previous + +--- + +## Summary + +| Metric | Value | +|--------|-------| +| Total Tasks | 47 | +| Setup Phase | 2 tasks | +| Foundational Phase | 5 tasks | +| User Story 1 (P1) | 8 tasks | +| User Story 2 (P1) | 7 tasks | +| User Story 3 (P2) | 8 tasks | +| User Story 4 (P2) | 9 tasks | +| User Story 5 (P3) | 3 tasks | +| Polish Phase | 5 tasks | +| Parallel opportunities | 12 task groups | + +**MVP Scope**: User Stories 1 + 2 (15 tasks after foundational) + +**Independent Test Criteria**: + +- US1: `/speckit.commits` outputs commits.md with grouped tasks +- US2: Each commit includes TDD and linting repetitive tasks +- US3: `/speckit.milestones` outputs milestones.md with verification criteria +- US4: `/speckit.implement` pauses at milestones for verification +- US5: Progress display shows commit/milestone status + +--- + +## Notes + +- [P] tasks = different files, no dependencies +- [Story] label maps task to specific user story for traceability +- Each user story should be independently completable and testable +- Verify tests fail before implementing (TDD RED) +- Run make check after each task group +- Stop at any checkpoint to validate story independently From c67bcab35e7ee18d6bc44e486bae8c45574025ec Mon Sep 17 00:00:00 2001 From: Aniket Date: Thu, 11 Dec 2025 14:55:33 +0530 Subject: [PATCH 6/6] feat(workflow): implement diverge-converge workflow with commits and milestones Add complete implementation of the diverge-converge workflow: - Add /speckit.commits command to group tasks into logical commits with constitution-driven repetitive tasks (TDD, linting, verification) - Add /speckit.milestones command to create verification checkpoints with acceptance criteria extracted from spec.md - Enhance /speckit.implement with commit-by-commit execution, milestone pause points, and progress visualization - Add parse-constitution.sh to extract quality requirements from constitution - Add commits/milestones flags to check-prerequisites.sh (bash + PowerShell) - Create command and output templates for new workflow - Add comprehensive bats tests (78 tests total) - Update all documentation to reflect 8-step workflow - Fix CI test stability by setting SPECIFY_FEATURE env var --- .claude/commands/speckit.commits.md | 189 ++++++++++++++++ .claude/commands/speckit.implement.md | 171 +++++++++++++- .claude/commands/speckit.milestones.md | 221 +++++++++++++++++++ .claude/commands/speckit.tasks.md | 8 +- .specify/scripts/bash/check-prerequisites.sh | 63 +++++- .specify/scripts/bash/common.sh | 2 + .specify/scripts/bash/parse-constitution.sh | 86 ++++++++ .specify/templates/commits-template.md | 53 +++++ .specify/templates/milestones-template.md | 57 +++++ CONTRIBUTING.md | 2 +- README.md | 18 +- docs/quickstart.md | 49 +++- scripts/powershell/check-prerequisites.ps1 | 53 ++++- scripts/powershell/common.ps1 | 2 + spec-driven.md | 87 +++++++- specs/001-commit-based-tasks/tasks.md | 94 ++++---- templates/commands/commits.md | 140 ++++++++++++ templates/commands/implement.md | 18 +- templates/commands/milestones.md | 144 ++++++++++++ templates/commits-template.md | 53 +++++ templates/milestones-template.md | 57 +++++ templates/tasks-template.md | 10 + tests/bash/test_check_prerequisites.bats | 89 ++++++++ tests/bash/test_commits_grouping.bats | 54 +++++ tests/bash/test_implement_enhanced.bats | 94 ++++++++ tests/bash/test_milestones.bats | 65 ++++++ tests/bash/test_parse_constitution.bats | 96 ++++++++ tests/bash/test_repetitive_tasks.bats | 77 +++++++ 28 files changed, 1956 insertions(+), 96 deletions(-) create mode 100644 .claude/commands/speckit.commits.md create mode 100644 .claude/commands/speckit.milestones.md create mode 100755 .specify/scripts/bash/parse-constitution.sh create mode 100644 .specify/templates/commits-template.md create mode 100644 .specify/templates/milestones-template.md create mode 100644 templates/commands/commits.md create mode 100644 templates/commands/milestones.md create mode 100644 templates/commits-template.md create mode 100644 templates/milestones-template.md create mode 100644 tests/bash/test_check_prerequisites.bats create mode 100644 tests/bash/test_commits_grouping.bats create mode 100644 tests/bash/test_implement_enhanced.bats create mode 100644 tests/bash/test_milestones.bats create mode 100644 tests/bash/test_parse_constitution.bats create mode 100644 tests/bash/test_repetitive_tasks.bats diff --git a/.claude/commands/speckit.commits.md b/.claude/commands/speckit.commits.md new file mode 100644 index 0000000000..e322e14333 --- /dev/null +++ b/.claude/commands/speckit.commits.md @@ -0,0 +1,189 @@ +--- +description: Group tasks into logical commits with constitution-driven repetitive tasks. +handoffs: + - label: Create Milestones + agent: speckit.milestones + prompt: Group the commits into milestones with verification criteria + send: true + - label: Implement + agent: speckit.implement + prompt: Execute the implementation following commit boundaries +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. For single quotes in args, use escape syntax. + +2. **Load context**: Read from FEATURE_DIR: + - **Required**: tasks.md (task list with IDs, stories, and file paths) + - **Required**: spec.md (user stories for story references) + - **Required**: `.specify/memory/constitution.md` (for repetitive tasks) + - **Optional**: plan.md (for context on project structure) + +3. **Parse constitution for repetitive tasks**: Run `.specify/scripts/bash/parse-constitution.sh` on the constitution file to get JSON output of required repetitive tasks (TDD, linting, verification). + +4. **Parse tasks.md**: Extract all tasks with their: + - Task ID (T###) + - Priority marker [P#] + - Story reference [US#] if present + - Description and file path + - Phase assignment + +5. **Group tasks into commits** using semantic grouping: + + **Grouping Algorithm** (in priority order): + 1. Tasks with same [Story] tag → same commit + 2. Tasks referencing same file → same commit + 3. Tasks in same phase without story tag → same commit (for Setup/Foundational phases) + 4. Override: Tasks in Setup/Foundational phases without [Story] tag → group by logical unit + + **Rules**: + - Each commit should represent a logical, atomic unit of work + - Commits should be independently testable where possible + - Maximum ~5-7 non-repetitive tasks per commit (split if larger) + +6. **Generate commit messages** for each group: + - Use conventional commit format: `type(scope): description` + - Types: feat, fix, test, refactor, docs, chore + - Scope: derived from primary file path or component + - Description: summarizes what the commit achieves + +7. **Add repetitive tasks** to each commit based on constitution: + - If TDD enabled: Add TDD-RED, TDD-GREEN, TDD-REFACTOR tasks + - If linting enabled: Add appropriate LINT tasks based on file types in commit + - Always add VERIFY task (make check) at end + +8. **Generate commits.md** following the format in `contracts/commits-format.md`: + - Header with metadata (Generated timestamp, Source paths) + - Summary with counts + - Each commit section with: + - Conventional commit message as heading + - ID, Status (pending), Story reference + - Non-Repetitive Tasks (from tasks.md) + - Repetitive Tasks (from constitution) + +9. **Write output**: Save commits.md to FEATURE_DIR + +10. **Report**: Output path to generated commits.md and summary: + - Total commits generated + - Tasks per commit breakdown + - Stories covered + - Repetitive tasks added + +## Grouping Examples + +### Example 1: Story-based grouping + +```text +Input tasks: +- [ ] T010 [US1] Create speckit.commits.md `.claude/commands/speckit.commits.md` +- [ ] T011 [US1] Implement task parsing logic `.claude/commands/speckit.commits.md` +- [ ] T012 [US1] Implement grouping algorithm `.claude/commands/speckit.commits.md` + +Output: Single commit for US1 +## Commit 1: feat(commits): add speckit.commits slash command + +**Story**: US1 +### Non-Repetitive Tasks +- [ ] T010 [US1] Create speckit.commits.md +- [ ] T011 [US1] Implement task parsing logic +- [ ] T012 [US1] Implement grouping algorithm +``` + +### Example 2: File-based grouping (no story tag) + +```text +Input tasks: +- [ ] T001 Create commits-template.md `.specify/templates/commits-template.md` +- [ ] T002 Create milestones-template.md `.specify/templates/milestones-template.md` + +Output: Single commit (same directory/purpose) +## Commit 1: feat(templates): add commits and milestones templates +``` + +### Example 3: Phase-based grouping + +```text +Input tasks (Foundational phase): +- [ ] T003 Write bats test for parse-constitution.sh +- [ ] T004 Create parse-constitution.sh script + +Output: Single commit (related test + implementation) +## Commit 1: feat(constitution): add constitution parser with tests +``` + +## Repetitive Task Injection + +For each commit, add repetitive tasks based on constitution requirements: + +**If constitution has TDD requirements**: + +```markdown +### Repetitive Tasks + +- [ ] [TDD-RED] Write failing test for [primary component in commit] +- [ ] [TDD-GREEN] Implement [primary component] to pass test +- [ ] [TDD-REFACTOR] Refactor [primary component] while tests pass +- [ ] [VERIFY] Run make check +``` + +**If commit contains .sh files and shellcheck required**: + +```markdown +- [ ] [LINT-BASH] Run shellcheck on modified bash scripts +``` + +**If commit contains .py files and ruff required**: + +```markdown +- [ ] [LINT-PYTHON] Run ruff check on modified Python files +``` + +## Output Format + +Follow the exact format specified in `contracts/commits-format.md`. + +## Key Rules + +- Use absolute paths +- Every task ID from tasks.md must appear in exactly one commit +- Commits must be ordered by dependency (Setup → Foundational → User Stories → Polish) +- Validate that all [Story] references exist in spec.md +- Report orphaned tasks (tasks not assigned to any commit) as warnings + +## Usage Examples + +**Basic usage** (groups all tasks in current feature): + +```text +/speckit.commits +``` + +**With specific instructions**: + +```text +/speckit.commits Split the authentication tasks into smaller commits for easier review +``` + +**After updating tasks**: + +```text +/speckit.commits Regenerate commits to include the new validation tasks +``` + +**Workflow**: + +```text +1. /speckit.tasks → Creates tasks.md +2. /speckit.commits → Creates commits.md (this command) +3. /speckit.milestones → Creates milestones.md +4. /speckit.implement → Executes with commit boundaries +``` diff --git a/.claude/commands/speckit.implement.md b/.claude/commands/speckit.implement.md index 41da7b931c..abf0f07e8d 100644 --- a/.claude/commands/speckit.implement.md +++ b/.claude/commands/speckit.implement.md @@ -12,7 +12,24 @@ You **MUST** consider the user input before proceeding (if not empty). ## Outline -1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks --include-commits --include-milestones` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + + **Document Loading Behavior**: + - **Required**: tasks.md (always required) + - **Optional but Recommended**: commits.md (for commit-by-commit execution) + - **Optional but Recommended**: milestones.md (for milestone pause and verification) + + **If commits.md exists**: + - Execute tasks grouped by commit boundaries (not flat list) + - Create git commits at each commit boundary with planned messages + + **If milestones.md exists**: + - Pause at milestone boundaries for manual verification + - Track verification status (pending → verification_required → verified/rejected) + + **If neither exists**: + - Fall back to legacy flat task execution (phase-by-phase) + - Show warning: "For better execution control, run /speckit.commits and /speckit.milestones first" 2. **Check checklists status** (if FEATURE_DIR/checklists/ exists): - Scan all checklist files in the checklists/ directory @@ -103,21 +120,130 @@ You **MUST** consider the user input before proceeding (if not empty). - **Task details**: ID, description, file paths, parallel markers [P] - **Execution flow**: Order and dependency requirements -6. Execute implementation following the task plan: +6. **Commit-by-Commit Execution** (if commits.md exists): + + **Execution Flow**: + + ```text + For each commit in commits.md (in order): + 1. Display commit info: ID, message, tasks count + 2. Execute all Non-Repetitive Tasks in commit + 3. Execute all Repetitive Tasks in commit (TDD-RED, TDD-GREEN, LINT, VERIFY) + 4. If all tasks pass: + - Create git commit with planned message from commits.md + - Update commit status to 'completed' in commits.md + - Check if this commit completes a milestone + 5. If any task fails: + - STOP execution + - Report failure with context + - Do NOT create partial commits + ``` + + **Git Commit Creation**: + + - Use the exact conventional commit message from commits.md + - Stage only files modified during this commit's tasks + - Include commit ID in commit body for traceability + - Example: `git commit -m "feat(commits): add task grouping algorithm" -m "Commit: C002"` + + **Milestone Pause and Verification** (if milestones.md exists): + + ```text + When all commits in a milestone are completed: + 1. Update milestone status from 'pending' to 'verification_required' + 2. Display milestone verification criteria + 3. PAUSE execution and prompt user: + "Milestone [M###] reached: [Title] + Please verify the following criteria: + - [ ] [V001] Given... When... Then... + - [ ] [V002] Given... When... Then... + + Enter 'verify' to continue or 'reject' to rollback" + 4. Wait for user input: + - If 'verify': Update status to 'verified', continue to next milestone + - If 'reject': Update status to 'rejected', halt execution + ``` + + **Verification Status Tracking**: + + - Update milestones.md with status changes in real-time + - Record verification timestamp in 'Verified At' field + - Record verifier in 'Verified By' field (e.g., "user" or "automated") + + **Progress Visualization**: + + Display progress after each commit and at milestone boundaries: + + ```text + ══════════════════════════════════════════════════════════════════ + WORKFLOW PROGRESS + ══════════════════════════════════════════════════════════════════ + + Milestone 1: Group Tasks into Commits [US1] ✓ VERIFIED + ├── [C001] feat(templates): add commits and milestones templates ✓ + ├── [C002] feat(constitution): add constitution parser ✓ + └── [C003] feat(commits): add speckit.commits command ✓ + + Milestone 2: Add Repetitive Tasks [US2] → IN PROGRESS + ├── [C004] feat(commits): add repetitive task injection ✓ + └── [C005] test(commits): add integration tests ◯ (current) + + Milestone 3: Define Milestones [US3] ○ PENDING + ├── [C006] feat(milestones): add speckit.milestones command + └── [C007] test(milestones): add verification tests + + ══════════════════════════════════════════════════════════════════ + Progress: 4/7 commits (57%) | 1/3 milestones verified + Current: [C005] test(commits): add integration tests + Next milestone: "Add Repetitive Tasks" - 1 commit remaining + ══════════════════════════════════════════════════════════════════ + ``` + + **Status Symbols**: + + - ✓ = completed/verified + - ○ = pending (not started) + - ◯ = current (in progress) + - ✗ = failed/rejected + + **Milestone Verification Status Display**: + + ```text + ══════════════════════════════════════════════════════════════════ + MILESTONE VERIFICATION: Add Repetitive Tasks [US2] + ══════════════════════════════════════════════════════════════════ + + Status: VERIFICATION REQUIRED + + Please verify the following criteria: + [ ] [V005] Given a constitution requiring TDD, When commits are + generated, Then each includes RED-GREEN-REFACTOR tasks + [ ] [V006] Given a constitution requiring linting, When commits + are generated, Then each includes "run linter" task + + ══════════════════════════════════════════════════════════════════ + Commands: 'verify' to continue | 'reject' to halt | 'notes' to add + ══════════════════════════════════════════════════════════════════ + ``` + +7. Execute implementation following the task plan (legacy mode if no commits.md): + - **Phase-by-phase execution**: Complete each phase before moving to the next - - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together + - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks - **File-based coordination**: Tasks affecting the same files must run sequentially - **Validation checkpoints**: Verify each phase completion before proceeding -7. Implementation execution rules: +8. Implementation execution rules: + - **Setup first**: Initialize project structure, dependencies, configuration - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios - **Core development**: Implement models, services, CLI commands, endpoints - **Integration work**: Database connections, middleware, logging, external services - **Polish and validation**: Unit tests, performance optimization, documentation -8. Progress tracking and error handling: +9. Progress tracking and error handling: + - Report progress after each completed task - Halt execution if any non-parallel task fails - For parallel tasks [P], continue with successful tasks, report failed ones @@ -125,11 +251,32 @@ You **MUST** consider the user input before proceeding (if not empty). - Suggest next steps if implementation cannot proceed - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. -9. Completion validation: - - Verify all required tasks are completed - - Check that implemented features match the original specification - - Validate that tests pass and coverage meets requirements - - Confirm the implementation follows the technical plan - - Report final status with summary of completed work +10. Completion validation: + + - Verify all required tasks are completed + - Check that implemented features match the original specification + - Validate that tests pass and coverage meets requirements + - Confirm the implementation follows the technical plan + - Report final status with summary of completed work + +## Error Handling + +**Missing Required Files**: + +- If tasks.md is missing: STOP with error "tasks.md not found. Run /speckit.tasks first." + +**Missing Optional Files** (with clear guidance): + +- If commits.md is missing but milestones.md exists: WARN "commits.md not found. Run /speckit.commits first for commit boundaries." +- If milestones.md is missing but commits.md exists: WARN "milestones.md not found. Run /speckit.milestones for verification checkpoints." +- If both are missing: WARN "For structured execution with commit boundaries and verification checkpoints, run /speckit.commits then /speckit.milestones." + +**Verification Rejection**: + +- If user rejects a milestone verification: + 1. Record rejection in milestones.md (status: rejected) + 2. Display which verification criteria failed + 3. Suggest: "Fix the issues and re-run /speckit.implement to resume from this milestone" + 4. Do NOT rollback commits already created (they represent completed work) -Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list. +Note: This command supports both legacy flat execution (tasks.md only) and structured commit-by-commit execution (with commits.md and milestones.md). For best results, run the full workflow: `/speckit.tasks` → `/speckit.commits` → `/speckit.milestones` → `/speckit.implement`. diff --git a/.claude/commands/speckit.milestones.md b/.claude/commands/speckit.milestones.md new file mode 100644 index 0000000000..4432adef4c --- /dev/null +++ b/.claude/commands/speckit.milestones.md @@ -0,0 +1,221 @@ +--- +description: Group commits into milestones with verification criteria from spec.md acceptance scenarios. +handoffs: + - label: Implement + agent: speckit.implement + prompt: Execute the implementation following commit and milestone boundaries + send: true + - label: Review Commits + agent: speckit.commits + prompt: Review or regenerate commit groupings +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json --require-commits --include-commits` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. For single quotes in args, use escape syntax. + +2. **Load context**: Read from FEATURE_DIR: + - **Required**: commits.md (commit groupings with task assignments) + - **Required**: spec.md (user stories and acceptance scenarios for verification criteria) + - **Optional**: tasks.md (for cross-reference validation) + - **Optional**: plan.md (for context on project structure) + +3. **Parse commits.md**: Extract all commits with their: + - Commit ID (C###) + - Commit message + - Story reference [US#] if present + - Status (pending, in_progress, completed) + - Non-repetitive and repetitive tasks + +4. **Parse spec.md**: Extract user stories and their acceptance scenarios: + - User story ID (US#) + - Story title + - Priority (P1, P2, P3) + - Acceptance scenarios in Given/When/Then format + +5. **Group commits into milestones** using story-based boundaries: + + **Grouping Algorithm**: + 1. Each user story maps to one milestone + 2. All commits with the same [Story] reference → same milestone + 3. Setup/Foundational commits (no story ref) → Milestone 0 (Infrastructure) + 4. Polish commits → Final milestone + + **Rules**: + - Each milestone represents a complete user story deliverable + - Milestones are ordered by priority (P1 → P2 → P3) + - Infrastructure milestone (if any) comes first + - Polish milestone comes last + +6. **Extract verification criteria** from spec.md: + + For each milestone: + 1. Find the corresponding user story in spec.md + 2. Extract all acceptance scenarios from that story + 3. Convert to verification checklist format: + - `Given/When/Then` → `- [ ] [V###] Given..., When..., Then...` + 4. Assign sequential verification IDs (V001, V002, etc.) + +7. **Generate milestones.md** following the format in `contracts/milestones-format.md`: + - Header with metadata (Generated timestamp, Source paths) + - Summary with counts + - Each milestone section with: + - User story title as heading + - ID, Status (pending), Story reference, Priority + - Commits Included (list of commit IDs and messages) + - Verification Criteria (from acceptance scenarios) + - Manual Verification Notes section + +8. **Write output**: Save milestones.md to FEATURE_DIR + +9. **Report**: Output path to generated milestones.md and summary: + - Total milestones generated + - Commits per milestone breakdown + - Verification criteria per milestone + - Stories covered + +## Grouping Examples + +### Example 1: Story-based milestone + +```text +Input commits: +- [C001] feat(commits): add speckit.commits slash command [US1] +- [C002] feat(commits): add task grouping algorithm [US1] +- [C003] test(commits): add integration tests [US1] + +Output: Single milestone for US1 +## Milestone 1: Group Tasks into Commits + +**Story**: US1 +**Priority**: P1 + +### Commits Included +1. [C001] feat(commits): add speckit.commits slash command +2. [C002] feat(commits): add task grouping algorithm +3. [C003] test(commits): add integration tests + +### Verification Criteria +- [ ] [V001] Given a completed tasks.md, When I run /speckit.commits, Then commits.md contains commits with grouped tasks +- [ ] [V002] Given tasks that logically belong together, When commits are generated, Then they are grouped into a single commit +``` + +### Example 2: Infrastructure milestone + +```text +Input commits (no story tag): +- [C001] chore(templates): add commits and milestones templates +- [C002] feat(constitution): add constitution parser with tests + +Output: Milestone 0 (Infrastructure) +## Milestone 0: Infrastructure + +**Story**: N/A (Setup/Foundational) +**Priority**: P0 + +### Verification Criteria +- [ ] [V001] All template files exist and have required sections +- [ ] [V002] All infrastructure scripts pass their unit tests +``` + +## Verification Criteria Extraction + +Extract from spec.md acceptance scenarios: + +**Input (spec.md)**: + +```markdown +### User Story 1 - Group Tasks into Commits + +**Acceptance Scenarios**: + +1. **Given** a completed `tasks.md`, **When** I run `/speckit.commits`, **Then** the output `commits.md` contains commits with grouped tasks +2. **Given** tasks that logically belong together (e.g., model + service + endpoint for one feature), **When** commits are generated, **Then** they are grouped into a single commit +``` + +**Output (milestones.md)**: + +```markdown +### Verification Criteria + +> From US1 Acceptance Scenarios + +- [ ] [V001] Given a completed tasks.md, When I run /speckit.commits, Then the output commits.md contains commits with grouped tasks +- [ ] [V002] Given tasks that logically belong together, When commits are generated, Then they are grouped into a single commit +``` + +## Output Format + +Follow the exact format specified in `contracts/milestones-format.md`. + +## Key Rules + +- Use absolute paths in metadata +- Every commit ID from commits.md must appear in exactly one milestone +- Milestones must be ordered by priority (P0 Infrastructure → P1 → P2 → P3 → Polish) +- Validate that all [Story] references exist in spec.md +- Report orphaned commits (commits not assigned to any milestone) as warnings +- Each acceptance scenario becomes one verification criterion +- Verification IDs are globally unique within milestones.md (V001, V002, ... across all milestones) + +## Milestone Status Flow + +```text +pending → verification_required → verified OR rejected + │ │ + └──────────── (during /speckit.implement) ───────────────┘ +``` + +- `pending`: Commits not yet completed +- `verification_required`: All commits in milestone done, awaiting manual review +- `verified`: User confirmed all verification criteria pass +- `rejected`: User found issues, needs fixes before proceeding + +## Usage Examples + +**Basic usage** (creates milestones from commits.md): + +```text +/speckit.milestones +``` + +**With specific instructions**: + +```text +/speckit.milestones Add additional verification criteria for security requirements +``` + +**After updating commits**: + +```text +/speckit.milestones Regenerate milestones to reflect the new commit structure +``` + +**Workflow**: + +```text +1. /speckit.tasks → Creates tasks.md +2. /speckit.commits → Creates commits.md +3. /speckit.milestones → Creates milestones.md (this command) +4. /speckit.implement → Executes with milestone pause points +``` + +**What happens during implementation**: + +```text +/speckit.implement runs... + → Completes commits in Milestone 1 + → PAUSES: "Milestone reached! Please verify criteria..." + → User types 'verify' to continue + → Completes commits in Milestone 2 + → PAUSES again for verification + → ...continues until all milestones verified +``` diff --git a/.claude/commands/speckit.tasks.md b/.claude/commands/speckit.tasks.md index f64e86e7d3..805a801a06 100644 --- a/.claude/commands/speckit.tasks.md +++ b/.claude/commands/speckit.tasks.md @@ -1,13 +1,17 @@ --- description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. -handoffs: +handoffs: + - label: Group into Commits + agent: speckit.commits + prompt: Group tasks into logical commits with constitution-driven repetitive tasks + send: true - label: Analyze For Consistency agent: speckit.analyze prompt: Run a project analysis for consistency send: true - label: Implement Project agent: speckit.implement - prompt: Start the implementation in phases + prompt: Start the implementation in phases (recommended after /speckit.commits and /speckit.milestones) send: true --- diff --git a/.specify/scripts/bash/check-prerequisites.sh b/.specify/scripts/bash/check-prerequisites.sh index f0ed055e1f..e0c13d144a 100755 --- a/.specify/scripts/bash/check-prerequisites.sh +++ b/.specify/scripts/bash/check-prerequisites.sh @@ -11,6 +11,10 @@ # --json Output in JSON format # --require-tasks Require tasks.md to exist (for implementation phase) # --include-tasks Include tasks.md in AVAILABLE_DOCS list +# --require-commits Require commits.md to exist (for commit-aware implementation) +# --include-commits Include commits.md in AVAILABLE_DOCS list +# --require-milestones Require milestones.md to exist (for milestone-aware implementation) +# --include-milestones Include milestones.md in AVAILABLE_DOCS list # --paths-only Only output path variables (no validation) # --help, -h Show help message # @@ -25,6 +29,10 @@ set -e JSON_MODE=false REQUIRE_TASKS=false INCLUDE_TASKS=false +REQUIRE_COMMITS=false +INCLUDE_COMMITS=false +REQUIRE_MILESTONES=false +INCLUDE_MILESTONES=false PATHS_ONLY=false for arg in "$@"; do @@ -38,6 +46,18 @@ for arg in "$@"; do --include-tasks) INCLUDE_TASKS=true ;; + --require-commits) + REQUIRE_COMMITS=true + ;; + --include-commits) + INCLUDE_COMMITS=true + ;; + --require-milestones) + REQUIRE_MILESTONES=true + ;; + --include-milestones) + INCLUDE_MILESTONES=true + ;; --paths-only) PATHS_ONLY=true ;; @@ -51,16 +71,23 @@ OPTIONS: --json Output in JSON format --require-tasks Require tasks.md to exist (for implementation phase) --include-tasks Include tasks.md in AVAILABLE_DOCS list + --require-commits Require commits.md to exist (for commit-aware implementation) + --include-commits Include commits.md in AVAILABLE_DOCS list + --require-milestones Require milestones.md to exist (for milestone-aware implementation) + --include-milestones Include milestones.md in AVAILABLE_DOCS list --paths-only Only output path variables (no prerequisite validation) --help, -h Show this help message EXAMPLES: # Check task prerequisites (plan.md required) ./check-prerequisites.sh --json - + # Check implementation prerequisites (plan.md + tasks.md required) ./check-prerequisites.sh --json --require-tasks --include-tasks - + + # Check commit-aware implementation prerequisites + ./check-prerequisites.sh --json --require-commits --include-commits --include-milestones + # Get feature paths only (no validation) ./check-prerequisites.sh --paths-only @@ -119,6 +146,20 @@ if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then exit 1 fi +# Check for commits.md if required +if $REQUIRE_COMMITS && [[ ! -f "$COMMITS" ]]; then + echo "ERROR: commits.md not found in $FEATURE_DIR" >&2 + echo "Run /speckit.commits first to create the commit groupings." >&2 + exit 1 +fi + +# Check for milestones.md if required +if $REQUIRE_MILESTONES && [[ ! -f "$MILESTONES" ]]; then + echo "ERROR: milestones.md not found in $FEATURE_DIR" >&2 + echo "Run /speckit.milestones first to create the milestones." >&2 + exit 1 +fi + # Build list of available documents docs=() @@ -138,6 +179,16 @@ if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then docs+=("tasks.md") fi +# Include commits.md if requested and it exists +if $INCLUDE_COMMITS && [[ -f "$COMMITS" ]]; then + docs+=("commits.md") +fi + +# Include milestones.md if requested and it exists +if $INCLUDE_MILESTONES && [[ -f "$MILESTONES" ]]; then + docs+=("milestones.md") +fi + # Output results if $JSON_MODE; then # Build JSON array of documents @@ -163,4 +214,12 @@ else if $INCLUDE_TASKS; then check_file "$TASKS" "tasks.md" fi + + if $INCLUDE_COMMITS; then + check_file "$COMMITS" "commits.md" + fi + + if $INCLUDE_MILESTONES; then + check_file "$MILESTONES" "milestones.md" + fi fi diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh index c75d6ca218..0a11098eb5 100755 --- a/.specify/scripts/bash/common.sh +++ b/.specify/scripts/bash/common.sh @@ -150,6 +150,8 @@ FEATURE_DIR='$feature_dir' FEATURE_SPEC='$feature_dir/spec.md' IMPL_PLAN='$feature_dir/plan.md' TASKS='$feature_dir/tasks.md' +COMMITS='$feature_dir/commits.md' +MILESTONES='$feature_dir/milestones.md' RESEARCH='$feature_dir/research.md' DATA_MODEL='$feature_dir/data-model.md' QUICKSTART='$feature_dir/quickstart.md' diff --git a/.specify/scripts/bash/parse-constitution.sh b/.specify/scripts/bash/parse-constitution.sh new file mode 100755 index 0000000000..e47af570a4 --- /dev/null +++ b/.specify/scripts/bash/parse-constitution.sh @@ -0,0 +1,86 @@ +#!/usr/bin/env bash +# parse-constitution.sh - Extract repetitive tasks from constitution +# +# Usage: parse-constitution.sh +# +# Outputs JSON with detected repetitive task templates based on constitution content. +# Used by /speckit.commits to inject quality tasks into each commit. + +set -euo pipefail + +# Show usage if no arguments +if [[ $# -lt 1 ]]; then + echo "Usage: parse-constitution.sh " >&2 + echo " Parses constitution and outputs JSON with repetitive task templates" >&2 + exit 1 +fi + +CONSTITUTION_FILE="$1" + +# Verify file exists +if [[ ! -f "$CONSTITUTION_FILE" ]]; then + echo "ERROR: Constitution file not found: $CONSTITUTION_FILE" >&2 + exit 1 +fi + +# Read constitution content +CONTENT=$(cat "$CONSTITUTION_FILE") + +# Initialize JSON output structure +echo "{" + +# Detect TDD requirements +if echo "$CONTENT" | grep -qi "TDD\|Test-Driven\|Red-Green-Refactor\|RED.*GREEN.*REFACTOR"; then + echo ' "tdd": {' + echo ' "enabled": true,' + echo ' "trigger": "code_change",' + echo ' "tasks": [' + echo ' {"id": "TDD-RED", "order": 1, "name": "Write failing test", "phase": "RED"},' + echo ' {"id": "TDD-GREEN", "order": 2, "name": "Implement to pass test", "phase": "GREEN"},' + echo ' {"id": "TDD-REFACTOR", "order": 3, "name": "Refactor while green", "phase": "REFACTOR"}' + echo ' ]' + echo ' },' +else + echo ' "tdd": {"enabled": false},' +fi + +# Detect linting requirements +echo ' "linting": {' + +# Check for shellcheck/bash linting +if echo "$CONTENT" | grep -qi "shellcheck\|bash.*lint\|shell.*scripts.*MUST"; then + echo ' "bash": {"enabled": true, "tool": "shellcheck", "trigger": "*.sh"},' +else + echo ' "bash": {"enabled": false},' +fi + +# Check for ruff/python linting +if echo "$CONTENT" | grep -qi "ruff\|python.*lint\|Python.*MUST.*lint"; then + echo ' "python": {"enabled": true, "tool": "ruff", "trigger": "*.py"},' +else + echo ' "python": {"enabled": false},' +fi + +# Check for markdown linting +if echo "$CONTENT" | grep -qi "markdownlint\|markdown.*lint\|Markdown.*MUST"; then + echo ' "markdown": {"enabled": true, "tool": "markdownlint-cli2", "trigger": "*.md"}' +else + echo ' "markdown": {"enabled": false}' +fi + +echo ' },' + +# Detect verification requirements (make check) +if echo "$CONTENT" | grep -qi "make check\|MUST pass.*before.*commit\|verification.*loop"; then + echo ' "verify": {' + echo ' "enabled": true,' + echo ' "trigger": "all",' + echo ' "tasks": [' + echo ' {"id": "VERIFY", "order": 99, "name": "Run make check", "command": "make check"}' + echo ' ]' + echo ' }' +else + echo ' "verify": {"enabled": false}' +fi + +echo "}" diff --git a/.specify/templates/commits-template.md b/.specify/templates/commits-template.md new file mode 100644 index 0000000000..2092b1375e --- /dev/null +++ b/.specify/templates/commits-template.md @@ -0,0 +1,53 @@ +# Commits: [FEATURE NAME] + +**Generated**: [TIMESTAMP] +**Source**: [TASKS_PATH] +**Constitution**: [CONSTITUTION_PATH] + +## Summary + +- Total Commits: [COMMIT_COUNT] +- Total Tasks: [NON_REPETITIVE_COUNT] (non-repetitive) + [REPETITIVE_COUNT] (repetitive) +- Stories Covered: [STORY_LIST] + +--- + + + +## Commit [COMMIT_N]: [COMMIT_MESSAGE] + +**ID**: [COMMIT_ID] +**Status**: pending +**Story**: [STORY_REF] +**Git SHA**: + +### Non-Repetitive Tasks + +- [ ] [TASK_ID] [PRIORITY] Task description `file/path.ext` + +### Repetitive Tasks + + + +- [ ] [TDD-RED] Write failing test for [component] +- [ ] [TDD-GREEN] Implement [component] to pass test +- [ ] [TDD-REFACTOR] Refactor [component] if needed +- [ ] [VERIFY] Run make check + +--- + + diff --git a/.specify/templates/milestones-template.md b/.specify/templates/milestones-template.md new file mode 100644 index 0000000000..a774e9ede9 --- /dev/null +++ b/.specify/templates/milestones-template.md @@ -0,0 +1,57 @@ +# Milestones: [FEATURE NAME] + +**Generated**: [TIMESTAMP] +**Source**: [COMMITS_PATH] +**Spec**: [SPEC_PATH] + +## Summary + +- Total Milestones: [MILESTONE_COUNT] +- Total Commits: [COMMIT_COUNT] +- Verification Points: [VERIFICATION_COUNT] + +--- + + + +## Milestone [MILESTONE_N]: [STORY_TITLE] + +**ID**: [MILESTONE_ID] +**Status**: pending +**Story**: [STORY_REF] +**Priority**: [PRIORITY] +**Verified At**: +**Verified By**: + +### Commits Included + +1. [COMMIT_ID] [COMMIT_MESSAGE] + +### Verification Criteria + +> Derived from acceptance scenarios in spec.md + +- [ ] [V001] Given [precondition], When [action], Then [result] + +### Manual Verification Notes + + + +--- + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b42e8fd61..8b09453caf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,7 +57,7 @@ Here are a few things you can do that will increase the likelihood of your pull When working on spec-kit: -1. Test changes with the `specify` CLI commands (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) in your coding agent of choice +1. Test changes with the `specify` CLI commands (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.commits`, `/speckit.milestones`, `/speckit.implement`) in your coding agent of choice 2. Verify templates are working correctly in `templates/` directory 3. Test script functionality in the `scripts/` directory 4. Ensure memory files (`memory/constitution.md`) are updated if major process changes are made diff --git a/README.md b/README.md index 5690eb0971..44fff0885c 100644 --- a/README.md +++ b/README.md @@ -287,13 +287,15 @@ After running `specify init`, your AI coding agent will have access to these sla Essential commands for the Spec-Driven Development workflow: -| Command | Description | -| ----------------------- | ------------------------------------------------------------------------ | -| `/speckit.constitution` | Create or update project governing principles and development guidelines | -| `/speckit.specify` | Define what you want to build (requirements and user stories) | -| `/speckit.plan` | Create technical implementation plans with your chosen tech stack | -| `/speckit.tasks` | Generate actionable task lists for implementation | -| `/speckit.implement` | Execute all tasks to build the feature according to the plan | +| Command | Description | +| ----------------------- | --------------------------------------------------------------------------------------------- | +| `/speckit.constitution` | Create or update project governing principles and development guidelines | +| `/speckit.specify` | Define what you want to build (requirements and user stories) | +| `/speckit.plan` | Create technical implementation plans with your chosen tech stack | +| `/speckit.tasks` | Generate actionable task lists for implementation | +| `/speckit.commits` | Group tasks into logical commits with constitution-driven repetitive tasks (TDD, linting) | +| `/speckit.milestones` | Group commits into milestones with verification criteria for human review checkpoints | +| `/speckit.implement` | Execute all tasks to build the feature, respecting commit and milestone boundaries | #### Optional Commands @@ -430,7 +432,7 @@ Go to the project folder and run your AI agent. In our example, we're using `cla ![Bootstrapping Claude Code environment](./media/bootstrap-claude-code.gif) -You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available. +You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.commits`, `/speckit.milestones`, and `/speckit.implement` commands available. The first step should be establishing your project's governing principles using the `/speckit.constitution` command. This helps ensure consistent decision-making throughout all subsequent development phases: diff --git a/docs/quickstart.md b/docs/quickstart.md index 4d3b863b35..6ba8b22270 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -5,7 +5,7 @@ This guide will help you get started with Spec-Driven Development using Spec Kit > [!NOTE] > All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. -## The 6-Step Process +## The 8-Step Process > [!TIP] > **Context Awareness**: Spec Kit commands automatically detect the active feature based on your current Git branch (e.g., `001-feature-name`). To switch between different specifications, simply switch Git branches. @@ -61,7 +61,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** -- [ ] T008 [US1] Write bats test for task grouping by story tag `tests/bash/test_commits_grouping.bats` -- [ ] T009 [US1] Write bats test for commit message generation `tests/bash/test_commits_grouping.bats` +- [x] T008 [US1] Write bats test for task grouping by story tag `tests/bash/test_commits_grouping.bats` +- [x] T009 [US1] Write bats test for commit message generation `tests/bash/test_commits_grouping.bats` ### Implementation for User Story 1 -- [ ] T010 [US1] Create speckit.commits.md slash command with outline structure `.claude/commands/speckit.commits.md` -- [ ] T011 [US1] Implement task parsing logic in speckit.commits.md (read tasks.md, extract task IDs and story refs) `.claude/commands/speckit.commits.md` -- [ ] T012 [US1] Implement semantic grouping algorithm (group by [Story] tag, then by file path) `.claude/commands/speckit.commits.md` -- [ ] T013 [US1] Implement conventional commit message generation for each group `.claude/commands/speckit.commits.md` -- [ ] T014 [US1] Implement commits.md output following contracts/commits-format.md specification `.claude/commands/speckit.commits.md` -- [ ] T015 [US1] Add handoffs to speckit.milestones in command frontmatter `.claude/commands/speckit.commits.md` +- [x] T010 [US1] Create speckit.commits.md slash command with outline structure `.claude/commands/speckit.commits.md` +- [x] T011 [US1] Implement task parsing logic in speckit.commits.md (read tasks.md, extract task IDs and story refs) `.claude/commands/speckit.commits.md` +- [x] T012 [US1] Implement semantic grouping algorithm (group by [Story] tag, then by file path) `.claude/commands/speckit.commits.md` +- [x] T013 [US1] Implement conventional commit message generation for each group `.claude/commands/speckit.commits.md` +- [x] T014 [US1] Implement commits.md output following contracts/commits-format.md specification `.claude/commands/speckit.commits.md` +- [x] T015 [US1] Add handoffs to speckit.milestones in command frontmatter `.claude/commands/speckit.commits.md` **Checkpoint**: User Story 1 complete - `/speckit.commits` generates commits.md with grouped tasks @@ -83,16 +83,16 @@ > **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** -- [ ] T016 [US2] Write bats test for TDD task injection `tests/bash/test_repetitive_tasks.bats` -- [ ] T017 [US2] Write bats test for conditional linting task injection `tests/bash/test_repetitive_tasks.bats` +- [x] T016 [US2] Write bats test for TDD task injection `tests/bash/test_repetitive_tasks.bats` +- [x] T017 [US2] Write bats test for conditional linting task injection `tests/bash/test_repetitive_tasks.bats` ### Implementation for User Story 2 -- [ ] T018 [US2] Integrate parse-constitution.sh output into speckit.commits.md workflow `.claude/commands/speckit.commits.md` -- [ ] T019 [US2] Implement TDD repetitive task injection (RED, GREEN, REFACTOR per commit) `.claude/commands/speckit.commits.md` -- [ ] T020 [US2] Implement conditional linting task injection (shellcheck for .sh, ruff for .py) `.claude/commands/speckit.commits.md` -- [ ] T021 [US2] Implement VERIFY task injection (make check) at end of each commit `.claude/commands/speckit.commits.md` -- [ ] T022 [US2] Update commits.md output to include Repetitive Tasks section per commit `.claude/commands/speckit.commits.md` +- [x] T018 [US2] Integrate parse-constitution.sh output into speckit.commits.md workflow `.claude/commands/speckit.commits.md` +- [x] T019 [US2] Implement TDD repetitive task injection (RED, GREEN, REFACTOR per commit) `.claude/commands/speckit.commits.md` +- [x] T020 [US2] Implement conditional linting task injection (shellcheck for .sh, ruff for .py) `.claude/commands/speckit.commits.md` +- [x] T021 [US2] Implement VERIFY task injection (make check) at end of each commit `.claude/commands/speckit.commits.md` +- [x] T022 [US2] Update commits.md output to include Repetitive Tasks section per commit `.claude/commands/speckit.commits.md` **Checkpoint**: User Story 2 complete - `/speckit.commits` adds constitution-driven repetitive tasks @@ -108,17 +108,17 @@ > **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** -- [ ] T023 [US3] Write bats test for milestone boundary detection `tests/bash/test_milestones.bats` -- [ ] T024 [US3] Write bats test for verification criteria extraction from spec `tests/bash/test_milestones.bats` +- [x] T023 [US3] Write bats test for milestone boundary detection `tests/bash/test_milestones.bats` +- [x] T024 [US3] Write bats test for verification criteria extraction from spec `tests/bash/test_milestones.bats` ### Implementation for User Story 3 -- [ ] T025 [US3] Create speckit.milestones.md slash command with outline structure `.claude/commands/speckit.milestones.md` -- [ ] T026 [US3] Implement commits.md parsing to extract commit IDs and story refs `.claude/commands/speckit.milestones.md` -- [ ] T027 [US3] Implement milestone boundary detection (group commits by user story) `.claude/commands/speckit.milestones.md` -- [ ] T028 [US3] Implement verification criteria extraction from spec.md acceptance scenarios `.claude/commands/speckit.milestones.md` -- [ ] T029 [US3] Implement milestones.md output following contracts/milestones-format.md specification `.claude/commands/speckit.milestones.md` -- [ ] T030 [US3] Add handoffs to speckit.implement in command frontmatter `.claude/commands/speckit.milestones.md` +- [x] T025 [US3] Create speckit.milestones.md slash command with outline structure `.claude/commands/speckit.milestones.md` +- [x] T026 [US3] Implement commits.md parsing to extract commit IDs and story refs `.claude/commands/speckit.milestones.md` +- [x] T027 [US3] Implement milestone boundary detection (group commits by user story) `.claude/commands/speckit.milestones.md` +- [x] T028 [US3] Implement verification criteria extraction from spec.md acceptance scenarios `.claude/commands/speckit.milestones.md` +- [x] T029 [US3] Implement milestones.md output following contracts/milestones-format.md specification `.claude/commands/speckit.milestones.md` +- [x] T030 [US3] Add handoffs to speckit.implement in command frontmatter `.claude/commands/speckit.milestones.md` **Checkpoint**: User Story 3 complete - `/speckit.milestones` generates milestones.md with verification criteria @@ -134,18 +134,18 @@ > **NOTE: Write these tests FIRST, ensure they FAIL before implementation (TDD RED phase)** -- [ ] T031 [US4] Write bats test for document existence validation `tests/bash/test_implement_enhanced.bats` -- [ ] T032 [US4] Write bats test for commit boundary detection `tests/bash/test_implement_enhanced.bats` +- [x] T031 [US4] Write bats test for document existence validation `tests/bash/test_implement_enhanced.bats` +- [x] T032 [US4] Write bats test for commit boundary detection `tests/bash/test_implement_enhanced.bats` ### Implementation for User Story 4 -- [ ] T033 [US4] Add document validation to speckit.implement.md (require commits.md, milestones.md) `.claude/commands/speckit.implement.md` -- [ ] T034 [US4] Update check-prerequisites.sh call to use --require-commits --include-commits flags `.claude/commands/speckit.implement.md` -- [ ] T035 [US4] Implement commit-by-commit execution flow (execute tasks grouped by commit) `.claude/commands/speckit.implement.md` -- [ ] T036 [US4] Implement git commit creation at commit boundaries with planned message `.claude/commands/speckit.implement.md` -- [ ] T037 [US4] Implement milestone pause logic (pause and prompt for verification when milestone reached) `.claude/commands/speckit.implement.md` -- [ ] T038 [US4] Implement verification status tracking (update milestones.md status field) `.claude/commands/speckit.implement.md` -- [ ] T039 [US4] Add clear error messages when commits.md or milestones.md missing `.claude/commands/speckit.implement.md` +- [x] T033 [US4] Add document validation to speckit.implement.md (require commits.md, milestones.md) `.claude/commands/speckit.implement.md` +- [x] T034 [US4] Update check-prerequisites.sh call to use --require-commits --include-commits flags `.claude/commands/speckit.implement.md` +- [x] T035 [US4] Implement commit-by-commit execution flow (execute tasks grouped by commit) `.claude/commands/speckit.implement.md` +- [x] T036 [US4] Implement git commit creation at commit boundaries with planned message `.claude/commands/speckit.implement.md` +- [x] T037 [US4] Implement milestone pause logic (pause and prompt for verification when milestone reached) `.claude/commands/speckit.implement.md` +- [x] T038 [US4] Implement verification status tracking (update milestones.md status field) `.claude/commands/speckit.implement.md` +- [x] T039 [US4] Add clear error messages when commits.md or milestones.md missing `.claude/commands/speckit.implement.md` **Checkpoint**: User Story 4 complete - `/speckit.implement` respects commit and milestone boundaries @@ -159,9 +159,9 @@ ### Implementation for User Story 5 -- [ ] T040 [US5] Add progress display section to speckit.implement.md showing commit/milestone status `.claude/commands/speckit.implement.md` -- [ ] T041 [US5] Implement ASCII progress visualization (commits completed, current milestone, remaining) `.claude/commands/speckit.implement.md` -- [ ] T042 [US5] Display verification status for completed milestones (passed/failed/pending) `.claude/commands/speckit.implement.md` +- [x] T040 [US5] Add progress display section to speckit.implement.md showing commit/milestone status `.claude/commands/speckit.implement.md` +- [x] T041 [US5] Implement ASCII progress visualization (commits completed, current milestone, remaining) `.claude/commands/speckit.implement.md` +- [x] T042 [US5] Display verification status for completed milestones (passed/failed/pending) `.claude/commands/speckit.implement.md` **Checkpoint**: User Story 5 complete - workflow progress is visible during implementation @@ -171,11 +171,11 @@ **Purpose**: Documentation and cleanup -- [ ] T043 [P] Update README.md with new commands documentation `README.md` -- [ ] T044 [P] Add command usage examples to each new slash command `.claude/commands/speckit.commits.md`, `.claude/commands/speckit.milestones.md` -- [ ] T045 Run all bats tests to verify implementation `tests/bash/` -- [ ] T046 Run make check to verify linting passes -- [ ] T047 Run quickstart.md validation scenarios `specs/001-commit-based-tasks/quickstart.md` +- [x] T043 [P] Update README.md with new commands documentation `README.md` +- [x] T044 [P] Add command usage examples to each new slash command `.claude/commands/speckit.commits.md`, `.claude/commands/speckit.milestones.md` +- [x] T045 Run all bats tests to verify implementation `tests/bash/` +- [x] T046 Run make check to verify linting passes +- [x] T047 Run quickstart.md validation scenarios `specs/001-commit-based-tasks/quickstart.md` --- diff --git a/templates/commands/commits.md b/templates/commands/commits.md new file mode 100644 index 0000000000..0776176e87 --- /dev/null +++ b/templates/commands/commits.md @@ -0,0 +1,140 @@ +--- +description: Group tasks into logical commits with constitution-driven repetitive tasks. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks +handoffs: + - label: Create Milestones + agent: speckit.milestones + prompt: Group the commits into milestones with verification criteria + send: true + - label: Implement + agent: speckit.implement + prompt: Execute the implementation following commit boundaries +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. For single quotes in args, use escape syntax. + +2. **Load context**: Read from FEATURE_DIR: + - **Required**: tasks.md (task list with IDs, stories, and file paths) + - **Required**: spec.md (user stories for story references) + - **Required**: `memory/constitution.md` (for repetitive tasks) + - **Optional**: plan.md (for context on project structure) + +3. **Parse constitution for repetitive tasks**: Run `scripts/bash/parse-constitution.sh` on the constitution file to get JSON output of required repetitive tasks (TDD, linting, verification). + +4. **Parse tasks.md**: Extract all tasks with their: + - Task ID (T###) + - Priority marker [P#] + - Story reference [US#] if present + - Description and file path + - Phase assignment + +5. **Group tasks into commits** using semantic grouping: + + **Grouping Algorithm** (in priority order): + 1. Tasks with same [Story] tag → same commit + 2. Tasks referencing same file → same commit + 3. Tasks in same phase without story tag → same commit (for Setup/Foundational phases) + 4. Override: Tasks in Setup/Foundational phases without [Story] tag → group by logical unit + + **Rules**: + - Each commit should represent a logical, atomic unit of work + - Commits should be independently testable where possible + - Maximum ~5-7 non-repetitive tasks per commit (split if larger) + +6. **Generate commit messages** for each group: + - Use conventional commit format: `type(scope): description` + - Types: feat, fix, test, refactor, docs, chore + - Scope: derived from primary file path or component + - Description: summarizes what the commit achieves + +7. **Add repetitive tasks** to each commit based on constitution: + - If TDD enabled: Add TDD-RED, TDD-GREEN, TDD-REFACTOR tasks + - If linting enabled: Add appropriate LINT tasks based on file types in commit + - Always add VERIFY task (make check) at end + +8. **Generate commits.md** following the format in `contracts/commits-format.md`: + - Header with metadata (Generated timestamp, Source paths) + - Summary with counts + - Each commit section with: + - Conventional commit message as heading + - ID, Status (pending), Story reference + - Non-Repetitive Tasks (from tasks.md) + - Repetitive Tasks (from constitution) + +9. **Write output**: Save commits.md to FEATURE_DIR + +10. **Report**: Output path to generated commits.md and summary: + - Total commits generated + - Tasks per commit breakdown + - Stories covered + - Repetitive tasks added + +## Repetitive Task Injection + +For each commit, add repetitive tasks based on constitution requirements: + +**If constitution has TDD requirements**: + +```markdown +### Repetitive Tasks + +- [ ] [TDD-RED] Write failing test for [primary component in commit] +- [ ] [TDD-GREEN] Implement [primary component] to pass test +- [ ] [TDD-REFACTOR] Refactor [primary component] while tests pass +- [ ] [VERIFY] Run make check +``` + +**If commit contains .sh files and shellcheck required**: + +```markdown +- [ ] [LINT-BASH] Run shellcheck on modified bash scripts +``` + +**If commit contains .py files and ruff required**: + +```markdown +- [ ] [LINT-PYTHON] Run ruff check on modified Python files +``` + +## Key Rules + +- Use absolute paths +- Every task ID from tasks.md must appear in exactly one commit +- Commits must be ordered by dependency (Setup → Foundational → User Stories → Polish) +- Validate that all [Story] references exist in spec.md +- Report orphaned tasks (tasks not assigned to any commit) as warnings + +## Usage Examples + +**Basic usage** (groups all tasks in current feature): + +```text +/speckit.commits +``` + +**With specific instructions**: + +```text +/speckit.commits Split the authentication tasks into smaller commits for easier review +``` + +**Workflow**: + +```text +1. /speckit.tasks → Creates tasks.md +2. /speckit.commits → Creates commits.md (this command) +3. /speckit.milestones → Creates milestones.md +4. /speckit.implement → Executes with commit boundaries +``` diff --git a/templates/commands/implement.md b/templates/commands/implement.md index 39abb1e6c8..92548ba6fc 100644 --- a/templates/commands/implement.md +++ b/templates/commands/implement.md @@ -1,8 +1,8 @@ --- description: Execute the implementation plan by processing and executing all tasks defined in tasks.md scripts: - sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks - ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks --include-commits --include-milestones + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks -IncludeCommits -IncludeMilestones --- ## User Input @@ -51,11 +51,23 @@ You **MUST** consider the user input before proceeding (if not empty). 3. Load and analyze the implementation context: - **REQUIRED**: Read tasks.md for the complete task list and execution plan - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure + - **IF EXISTS**: Read commits.md for commit boundaries and repetitive tasks + - **IF EXISTS**: Read milestones.md for verification checkpoints - **IF EXISTS**: Read data-model.md for entities and relationships - **IF EXISTS**: Read contracts/ for API specifications and test requirements - **IF EXISTS**: Read research.md for technical decisions and constraints - **IF EXISTS**: Read quickstart.md for integration scenarios + **Commit-Aware Execution** (if commits.md exists): + - Execute tasks grouped by commit boundaries + - Create git commits at each boundary with planned messages + - Include commit ID in commit body for traceability + + **Milestone-Aware Execution** (if milestones.md exists): + - Pause at milestone boundaries for human verification + - Display verification criteria from milestones.md + - Wait for user to verify or reject before proceeding + 4. **Project Setup Verification**: - **REQUIRED**: Create/verify ignore files based on actual project setup: @@ -135,4 +147,4 @@ You **MUST** consider the user input before proceeding (if not empty). - Confirm the implementation follows the technical plan - Report final status with summary of completed work -Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list. +Note: This command supports both legacy flat execution (tasks.md only) and structured commit-by-commit execution (with commits.md and milestones.md). For best results, run the full workflow: `/speckit.tasks` → `/speckit.commits` → `/speckit.milestones` → `/speckit.implement`. diff --git a/templates/commands/milestones.md b/templates/commands/milestones.md new file mode 100644 index 0000000000..32f4c4ec93 --- /dev/null +++ b/templates/commands/milestones.md @@ -0,0 +1,144 @@ +--- +description: Group commits into milestones with verification criteria from spec.md acceptance scenarios. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-commits --include-commits + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireCommits -IncludeCommits +handoffs: + - label: Implement + agent: speckit.implement + prompt: Execute the implementation following commit and milestone boundaries + send: true + - label: Review Commits + agent: speckit.commits + prompt: Review or regenerate commit groupings +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. For single quotes in args, use escape syntax. + +2. **Load context**: Read from FEATURE_DIR: + - **Required**: commits.md (commit groupings with task assignments) + - **Required**: spec.md (user stories and acceptance scenarios for verification criteria) + - **Optional**: tasks.md (for cross-reference validation) + - **Optional**: plan.md (for context on project structure) + +3. **Parse commits.md**: Extract all commits with their: + - Commit ID (C###) + - Commit message + - Story reference [US#] if present + - Status (pending, in_progress, completed) + - Non-repetitive and repetitive tasks + +4. **Parse spec.md**: Extract user stories and their acceptance scenarios: + - User story ID (US#) + - Story title + - Priority (P1, P2, P3) + - Acceptance scenarios in Given/When/Then format + +5. **Group commits into milestones** using story-based boundaries: + + **Grouping Algorithm**: + 1. Each user story maps to one milestone + 2. All commits with the same [Story] reference → same milestone + 3. Setup/Foundational commits (no story ref) → Milestone 0 (Infrastructure) + 4. Polish commits → Final milestone + + **Rules**: + - Each milestone represents a complete user story deliverable + - Milestones are ordered by priority (P1 → P2 → P3) + - Infrastructure milestone (if any) comes first + - Polish milestone comes last + +6. **Extract verification criteria** from spec.md: + + For each milestone: + 1. Find the corresponding user story in spec.md + 2. Extract all acceptance scenarios from that story + 3. Convert to verification checklist format: + - `Given/When/Then` → `- [ ] [V###] Given..., When..., Then...` + 4. Assign sequential verification IDs (V001, V002, etc.) + +7. **Generate milestones.md** following the format in `contracts/milestones-format.md`: + - Header with metadata (Generated timestamp, Source paths) + - Summary with counts + - Each milestone section with: + - User story title as heading + - ID, Status (pending), Story reference, Priority + - Commits Included (list of commit IDs and messages) + - Verification Criteria (from acceptance scenarios) + - Manual Verification Notes section + +8. **Write output**: Save milestones.md to FEATURE_DIR + +9. **Report**: Output path to generated milestones.md and summary: + - Total milestones generated + - Commits per milestone breakdown + - Verification criteria per milestone + - Stories covered + +## Key Rules + +- Use absolute paths in metadata +- Every commit ID from commits.md must appear in exactly one milestone +- Milestones must be ordered by priority (P0 Infrastructure → P1 → P2 → P3 → Polish) +- Validate that all [Story] references exist in spec.md +- Report orphaned commits (commits not assigned to any milestone) as warnings +- Each acceptance scenario becomes one verification criterion +- Verification IDs are globally unique within milestones.md (V001, V002, ... across all milestones) + +## Milestone Status Flow + +```text +pending → verification_required → verified OR rejected + │ │ + └──────────── (during /speckit.implement) ───────────────┘ +``` + +- `pending`: Commits not yet completed +- `verification_required`: All commits in milestone done, awaiting manual review +- `verified`: User confirmed all verification criteria pass +- `rejected`: User found issues, needs fixes before proceeding + +## Usage Examples + +**Basic usage** (creates milestones from commits.md): + +```text +/speckit.milestones +``` + +**With specific instructions**: + +```text +/speckit.milestones Add additional verification criteria for security requirements +``` + +**Workflow**: + +```text +1. /speckit.tasks → Creates tasks.md +2. /speckit.commits → Creates commits.md +3. /speckit.milestones → Creates milestones.md (this command) +4. /speckit.implement → Executes with milestone pause points +``` + +**What happens during implementation**: + +```text +/speckit.implement runs... + → Completes commits in Milestone 1 + → PAUSES: "Milestone reached! Please verify criteria..." + → User types 'verify' to continue + → Completes commits in Milestone 2 + → PAUSES again for verification + → ...continues until all milestones verified +``` diff --git a/templates/commits-template.md b/templates/commits-template.md new file mode 100644 index 0000000000..2092b1375e --- /dev/null +++ b/templates/commits-template.md @@ -0,0 +1,53 @@ +# Commits: [FEATURE NAME] + +**Generated**: [TIMESTAMP] +**Source**: [TASKS_PATH] +**Constitution**: [CONSTITUTION_PATH] + +## Summary + +- Total Commits: [COMMIT_COUNT] +- Total Tasks: [NON_REPETITIVE_COUNT] (non-repetitive) + [REPETITIVE_COUNT] (repetitive) +- Stories Covered: [STORY_LIST] + +--- + + + +## Commit [COMMIT_N]: [COMMIT_MESSAGE] + +**ID**: [COMMIT_ID] +**Status**: pending +**Story**: [STORY_REF] +**Git SHA**: + +### Non-Repetitive Tasks + +- [ ] [TASK_ID] [PRIORITY] Task description `file/path.ext` + +### Repetitive Tasks + + + +- [ ] [TDD-RED] Write failing test for [component] +- [ ] [TDD-GREEN] Implement [component] to pass test +- [ ] [TDD-REFACTOR] Refactor [component] if needed +- [ ] [VERIFY] Run make check + +--- + + diff --git a/templates/milestones-template.md b/templates/milestones-template.md new file mode 100644 index 0000000000..a774e9ede9 --- /dev/null +++ b/templates/milestones-template.md @@ -0,0 +1,57 @@ +# Milestones: [FEATURE NAME] + +**Generated**: [TIMESTAMP] +**Source**: [COMMITS_PATH] +**Spec**: [SPEC_PATH] + +## Summary + +- Total Milestones: [MILESTONE_COUNT] +- Total Commits: [COMMIT_COUNT] +- Verification Points: [VERIFICATION_COUNT] + +--- + + + +## Milestone [MILESTONE_N]: [STORY_TITLE] + +**ID**: [MILESTONE_ID] +**Status**: pending +**Story**: [STORY_REF] +**Priority**: [PRIORITY] +**Verified At**: +**Verified By**: + +### Commits Included + +1. [COMMIT_ID] [COMMIT_MESSAGE] + +### Verification Criteria + +> Derived from acceptance scenarios in spec.md + +- [ ] [V001] Given [precondition], When [action], Then [result] + +### Manual Verification Notes + + + +--- + + diff --git a/templates/tasks-template.md b/templates/tasks-template.md index 60f9be455d..61f11939d3 100644 --- a/templates/tasks-template.md +++ b/templates/tasks-template.md @@ -249,3 +249,13 @@ With multiple developers: - Commit after each task or logical group - Stop at any checkpoint to validate story independently - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence + +--- + +## Next Steps + +After generating `tasks.md`, run the following commands to complete the diverge-converge workflow: + +1. **`/speckit.commits`** - Group tasks into logical commits with constitution-driven repetitive tasks (TDD, linting) +2. **`/speckit.milestones`** - Create verification checkpoints with acceptance criteria from spec.md +3. **`/speckit.implement`** - Execute with commit boundaries and milestone pause points diff --git a/tests/bash/test_check_prerequisites.bats b/tests/bash/test_check_prerequisites.bats new file mode 100644 index 0000000000..48620a13bd --- /dev/null +++ b/tests/bash/test_check_prerequisites.bats @@ -0,0 +1,89 @@ +#!/usr/bin/env bats + +# Tests for check-prerequisites.sh enhanced flags +# Following TDD: These tests are written FIRST, before implementation + +setup() { + # Get the repository root + TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)" + REPO_ROOT="$(cd "$TEST_DIR/../.." && pwd)" + SCRIPT_PATH="$REPO_ROOT/.specify/scripts/bash/check-prerequisites.sh" + + # Use the actual repo's feature directory for testing + # This ensures tests run in the real environment + export TEST_FEATURE_DIR="$REPO_ROOT/specs/001-commit-based-tasks" + + # Set SPECIFY_FEATURE to ensure consistent behavior in CI + # This bypasses git branch detection which may vary in CI environments + export SPECIFY_FEATURE="001-commit-based-tasks" +} + +teardown() { + # Nothing to clean up when using real repo + : +} + +@test "check-prerequisites.sh exists and is executable" { + [ -f "$SCRIPT_PATH" ] + [ -x "$SCRIPT_PATH" ] +} + +@test "check-prerequisites.sh --require-commits fails when commits.md missing" { + # This test checks the error path - commits.md doesn't exist in our test feature yet + # The script should fail when --require-commits is set and commits.md is missing + run "$SCRIPT_PATH" --require-commits 2>&1 + # Either exits with non-zero or outputs error about missing commits.md + [[ "$status" -ne 0 ]] || [[ "$output" =~ "commits.md" ]] +} + +@test "check-prerequisites.sh --include-commits includes commits.md when file exists" { + # First create commits.md in our test feature + echo "# Test Commits" > "$TEST_FEATURE_DIR/commits.md" + + run "$SCRIPT_PATH" --json --include-commits 2>&1 + + [ "$status" -eq 0 ] + # JSON output should include commits.md reference + [[ "$output" =~ "commits.md" ]] + + # Cleanup + rm -f "$TEST_FEATURE_DIR/commits.md" +} + +@test "check-prerequisites.sh --include-milestones includes milestones.md when file exists" { + # First create milestones.md in our test feature + echo "# Test Milestones" > "$TEST_FEATURE_DIR/milestones.md" + + run "$SCRIPT_PATH" --json --include-milestones 2>&1 + + [ "$status" -eq 0 ] + # JSON output should include milestones.md reference + [[ "$output" =~ "milestones.md" ]] + + # Cleanup + rm -f "$TEST_FEATURE_DIR/milestones.md" +} + +@test "check-prerequisites.sh --require-milestones fails when milestones.md missing" { + # This test checks the error path - milestones.md doesn't exist in our test feature yet + run "$SCRIPT_PATH" --require-milestones 2>&1 + # Either exits with non-zero or outputs error about missing milestones.md + [[ "$status" -ne 0 ]] || [[ "$output" =~ "milestones.md" ]] +} + +@test "check-prerequisites.sh combined flags work when files exist" { + # Create both files + echo "# Test Commits" > "$TEST_FEATURE_DIR/commits.md" + echo "# Test Milestones" > "$TEST_FEATURE_DIR/milestones.md" + + run "$SCRIPT_PATH" --json --include-commits --include-milestones 2>&1 + + [ "$status" -eq 0 ] + # Should include both commits and milestones references + [[ "$output" =~ "commits.md" ]] + [[ "$output" =~ "milestones.md" ]] + + # Cleanup + rm -f "$TEST_FEATURE_DIR/commits.md" + rm -f "$TEST_FEATURE_DIR/milestones.md" +} diff --git a/tests/bash/test_commits_grouping.bats b/tests/bash/test_commits_grouping.bats new file mode 100644 index 0000000000..ca3f9b8b30 --- /dev/null +++ b/tests/bash/test_commits_grouping.bats @@ -0,0 +1,54 @@ +#!/usr/bin/env bats + +# Tests for commit grouping logic +# These tests validate the conceptual grouping algorithm used by /speckit.commits +# Note: Slash commands are executed by Claude Code, so these tests focus on +# the supporting infrastructure and file format validation + +setup() { + TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)" + REPO_ROOT="$(cd "$TEST_DIR/../.." && pwd)" + TEST_FEATURE_DIR="$REPO_ROOT/specs/001-commit-based-tasks" +} + +teardown() { + # Cleanup any test artifacts + rm -f "$TEST_FEATURE_DIR/commits.md" 2>/dev/null || true +} + +@test "commits-template.md exists" { + [ -f "$REPO_ROOT/.specify/templates/commits-template.md" ] +} + +@test "commits-template.md contains required sections" { + template="$REPO_ROOT/.specify/templates/commits-template.md" + grep -q "# Commits:" "$template" + grep -q "## Summary" "$template" + grep -q "Non-Repetitive Tasks" "$template" + grep -q "Repetitive Tasks" "$template" +} + +@test "speckit.commits.md slash command exists" { + [ -f "$REPO_ROOT/.claude/commands/speckit.commits.md" ] +} + +@test "speckit.commits.md has required frontmatter" { + command_file="$REPO_ROOT/.claude/commands/speckit.commits.md" + # Check for YAML frontmatter + head -1 "$command_file" | grep -q "^---" + grep -q "description:" "$command_file" +} + +@test "speckit.commits.md references check-prerequisites.sh" { + command_file="$REPO_ROOT/.claude/commands/speckit.commits.md" + grep -q "check-prerequisites.sh" "$command_file" +} + +@test "speckit.commits.md has outline section" { + command_file="$REPO_ROOT/.claude/commands/speckit.commits.md" + grep -q "## Outline" "$command_file" +} + +@test "commits format contract exists" { + [ -f "$TEST_FEATURE_DIR/contracts/commits-format.md" ] +} diff --git a/tests/bash/test_implement_enhanced.bats b/tests/bash/test_implement_enhanced.bats new file mode 100644 index 0000000000..676f8b1738 --- /dev/null +++ b/tests/bash/test_implement_enhanced.bats @@ -0,0 +1,94 @@ +#!/usr/bin/env bats + +# Tests for enhanced /speckit.implement command infrastructure +# These tests validate the commit/milestone boundary support in implement command + +setup() { + TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)" + REPO_ROOT="$(cd "$TEST_DIR/../.." && pwd)" + TEST_FEATURE_DIR="$REPO_ROOT/specs/001-commit-based-tasks" +} + +teardown() { + # Cleanup any test artifacts + : +} + +# T031: Document existence validation tests +@test "speckit.implement.md slash command exists" { + [ -f "$REPO_ROOT/.claude/commands/speckit.implement.md" ] +} + +@test "speckit.implement.md has required frontmatter" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + head -1 "$command_file" | grep -q "^---" + grep -q "description:" "$command_file" +} + +@test "speckit.implement.md documents commits.md requirement" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q -i "commits.md" "$command_file" +} + +@test "speckit.implement.md documents milestones.md requirement" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q -i "milestones.md" "$command_file" +} + +@test "speckit.implement.md references check-prerequisites.sh with commit flags" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + # Should use --require-commits or --include-commits + grep -q "require-commits\|include-commits" "$command_file" +} + +@test "speckit.implement.md references check-prerequisites.sh with milestone flags" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + # Should use --require-milestones or --include-milestones + grep -q "require-milestones\|include-milestones" "$command_file" +} + +# T032: Commit boundary detection tests +@test "speckit.implement.md documents commit boundary execution" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q -i "commit.*boundary\|boundary.*commit\|commit-by-commit" "$command_file" +} + +@test "speckit.implement.md documents milestone pause behavior" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q -i "pause.*milestone\|milestone.*pause\|verification" "$command_file" +} + +@test "speckit.implement.md documents git commit creation" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q -i "git commit\|create commit\|commit.*created" "$command_file" +} + +@test "speckit.implement.md documents verification status tracking" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q -i "status.*track\|verification.*status\|milestone.*status" "$command_file" +} + +@test "speckit.implement.md has outline section" { + command_file="$REPO_ROOT/.claude/commands/speckit.implement.md" + grep -q "## Outline" "$command_file" +} + +@test "check-prerequisites.sh supports --require-commits flag" { + script="$REPO_ROOT/.specify/scripts/bash/check-prerequisites.sh" + grep -q "\-\-require-commits" "$script" +} + +@test "check-prerequisites.sh supports --include-commits flag" { + script="$REPO_ROOT/.specify/scripts/bash/check-prerequisites.sh" + grep -q "\-\-include-commits" "$script" +} + +@test "check-prerequisites.sh supports --require-milestones flag" { + script="$REPO_ROOT/.specify/scripts/bash/check-prerequisites.sh" + grep -q "\-\-require-milestones" "$script" +} + +@test "check-prerequisites.sh supports --include-milestones flag" { + script="$REPO_ROOT/.specify/scripts/bash/check-prerequisites.sh" + grep -q "\-\-include-milestones" "$script" +} diff --git a/tests/bash/test_milestones.bats b/tests/bash/test_milestones.bats new file mode 100644 index 0000000000..bc76edf8c9 --- /dev/null +++ b/tests/bash/test_milestones.bats @@ -0,0 +1,65 @@ +#!/usr/bin/env bats + +# Tests for milestone generation logic +# These tests validate the /speckit.milestones command infrastructure + +setup() { + TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)" + REPO_ROOT="$(cd "$TEST_DIR/../.." && pwd)" + TEST_FEATURE_DIR="$REPO_ROOT/specs/001-commit-based-tasks" +} + +teardown() { + # Cleanup any test artifacts + rm -f "$TEST_FEATURE_DIR/milestones.md" 2>/dev/null || true +} + +@test "milestones-template.md exists" { + [ -f "$REPO_ROOT/.specify/templates/milestones-template.md" ] +} + +@test "milestones-template.md contains required sections" { + template="$REPO_ROOT/.specify/templates/milestones-template.md" + grep -q "# Milestones:" "$template" + grep -q "## Summary" "$template" + grep -q "Verification Criteria" "$template" + grep -q "Commits Included" "$template" +} + +@test "speckit.milestones.md slash command exists" { + [ -f "$REPO_ROOT/.claude/commands/speckit.milestones.md" ] +} + +@test "speckit.milestones.md has required frontmatter" { + command_file="$REPO_ROOT/.claude/commands/speckit.milestones.md" + head -1 "$command_file" | grep -q "^---" + grep -q "description:" "$command_file" +} + +@test "speckit.milestones.md references check-prerequisites.sh" { + command_file="$REPO_ROOT/.claude/commands/speckit.milestones.md" + grep -q "check-prerequisites.sh" "$command_file" +} + +@test "speckit.milestones.md has outline section" { + command_file="$REPO_ROOT/.claude/commands/speckit.milestones.md" + grep -q "## Outline" "$command_file" +} + +@test "speckit.milestones.md documents verification criteria extraction" { + command_file="$REPO_ROOT/.claude/commands/speckit.milestones.md" + grep -q -i "verification" "$command_file" + grep -q -i "spec.md" "$command_file" +} + +@test "milestones format contract exists" { + [ -f "$TEST_FEATURE_DIR/contracts/milestones-format.md" ] +} + +@test "milestones format contract defines verification status values" { + contract="$TEST_FEATURE_DIR/contracts/milestones-format.md" + grep -q "pending" "$contract" + grep -q "verification_required" "$contract" + grep -q "verified" "$contract" + grep -q "rejected" "$contract" +} diff --git a/tests/bash/test_parse_constitution.bats b/tests/bash/test_parse_constitution.bats new file mode 100644 index 0000000000..9b353eb143 --- /dev/null +++ b/tests/bash/test_parse_constitution.bats @@ -0,0 +1,96 @@ +#!/usr/bin/env bats + +# Tests for parse-constitution.sh script +# Following TDD: These tests are written FIRST, before implementation + +setup() { + # Get the repository root + REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../.." && pwd)" + SCRIPT_PATH="$REPO_ROOT/.specify/scripts/bash/parse-constitution.sh" + TEST_CONSTITUTION="$BATS_TEST_TMPDIR/test_constitution.md" + + # Create a test constitution file with known content + cat > "$TEST_CONSTITUTION" << 'EOF' +# Test Constitution + +## Core Principles + +### VII. Test-Driven Development (TDD) + +All new code MUST follow the **Red-Green-Refactor** workflow. + +**Requirements**: + +- **RED**: Write a failing test BEFORE writing implementation code +- **GREEN**: Write the minimum code necessary to make the test pass +- **REFACTOR**: Clean up the code while keeping all tests green +- `make check` MUST pass before any commit is created + +### I. Code Quality Through Linting + +**Requirements**: + +- Python code MUST be linted with `ruff` +- Shell scripts (bash) MUST be linted with `shellcheck` +- Markdown MUST pass `markdownlint-cli2` + +### III. CI/CD Enforcement + +- **`make check` MUST pass locally before any commit is created** +EOF +} + +teardown() { + rm -f "$TEST_CONSTITUTION" +} + +@test "parse-constitution.sh exists and is executable" { + [ -f "$SCRIPT_PATH" ] + [ -x "$SCRIPT_PATH" ] +} + +@test "parse-constitution.sh outputs JSON format" { + run "$SCRIPT_PATH" "$TEST_CONSTITUTION" + [ "$status" -eq 0 ] + # Output should be valid JSON (starts with { or [) + [[ "$output" =~ ^\{ ]] || [[ "$output" =~ ^\[ ]] +} + +@test "parse-constitution.sh detects TDD requirements" { + run "$SCRIPT_PATH" "$TEST_CONSTITUTION" + [ "$status" -eq 0 ] + # Should contain TDD-related keys + [[ "$output" =~ "tdd" ]] || [[ "$output" =~ "TDD" ]] +} + +@test "parse-constitution.sh detects linting requirements for bash" { + run "$SCRIPT_PATH" "$TEST_CONSTITUTION" + [ "$status" -eq 0 ] + # Should detect shellcheck requirement + [[ "$output" =~ "shellcheck" ]] || [[ "$output" =~ "bash" ]] || [[ "$output" =~ "LINT" ]] +} + +@test "parse-constitution.sh detects linting requirements for python" { + run "$SCRIPT_PATH" "$TEST_CONSTITUTION" + [ "$status" -eq 0 ] + # Should detect ruff requirement + [[ "$output" =~ "ruff" ]] || [[ "$output" =~ "python" ]] || [[ "$output" =~ "LINT" ]] +} + +@test "parse-constitution.sh detects make check requirement" { + run "$SCRIPT_PATH" "$TEST_CONSTITUTION" + [ "$status" -eq 0 ] + # Should detect make check/verify requirement + [[ "$output" =~ "make check" ]] || [[ "$output" =~ "verify" ]] || [[ "$output" =~ "VERIFY" ]] +} + +@test "parse-constitution.sh handles missing file gracefully" { + run "$SCRIPT_PATH" "/nonexistent/path/constitution.md" + [ "$status" -ne 0 ] +} + +@test "parse-constitution.sh with no arguments shows usage" { + run "$SCRIPT_PATH" + [ "$status" -ne 0 ] + [[ "$output" =~ "Usage" ]] || [[ "$output" =~ "usage" ]] +} diff --git a/tests/bash/test_repetitive_tasks.bats b/tests/bash/test_repetitive_tasks.bats new file mode 100644 index 0000000000..411be18d9e --- /dev/null +++ b/tests/bash/test_repetitive_tasks.bats @@ -0,0 +1,77 @@ +#!/usr/bin/env bats + +# Tests for repetitive task injection from constitution +# Following TDD: These tests validate the constitution parsing outputs +# that are used by /speckit.commits to inject quality tasks + +setup() { + TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)" + REPO_ROOT="$(cd "$TEST_DIR/../.." && pwd)" + PARSE_SCRIPT="$REPO_ROOT/.specify/scripts/bash/parse-constitution.sh" + CONSTITUTION="$REPO_ROOT/.specify/memory/constitution.md" +} + +@test "parse-constitution.sh outputs TDD tasks when TDD section present" { + run "$PARSE_SCRIPT" "$CONSTITUTION" + [ "$status" -eq 0 ] + # Should output TDD-related task templates + [[ "$output" =~ "TDD-RED" ]] || [[ "$output" =~ "Write failing test" ]] +} + +@test "parse-constitution.sh outputs TDD enabled flag" { + run "$PARSE_SCRIPT" "$CONSTITUTION" + [ "$status" -eq 0 ] + # Should indicate TDD is enabled + [[ "$output" =~ '"enabled": true' ]] || [[ "$output" =~ '"enabled":true' ]] +} + +@test "parse-constitution.sh detects shellcheck requirement for bash" { + run "$PARSE_SCRIPT" "$CONSTITUTION" + [ "$status" -eq 0 ] + # Should detect bash linting with shellcheck + [[ "$output" =~ "shellcheck" ]] +} + +@test "parse-constitution.sh detects ruff requirement for python" { + run "$PARSE_SCRIPT" "$CONSTITUTION" + [ "$status" -eq 0 ] + # Should detect python linting with ruff + [[ "$output" =~ "ruff" ]] +} + +@test "parse-constitution.sh detects make check verification requirement" { + run "$PARSE_SCRIPT" "$CONSTITUTION" + [ "$status" -eq 0 ] + # Should detect make check requirement + [[ "$output" =~ "make check" ]] +} + +@test "parse-constitution.sh outputs valid JSON structure" { + run "$PARSE_SCRIPT" "$CONSTITUTION" + [ "$status" -eq 0 ] + # Should have tdd, linting, and verify sections + [[ "$output" =~ '"tdd"' ]] + [[ "$output" =~ '"linting"' ]] + [[ "$output" =~ '"verify"' ]] +} + +@test "speckit.commits.md documents repetitive task injection" { + command_file="$REPO_ROOT/.claude/commands/speckit.commits.md" + # Should document repetitive task injection + grep -q "Repetitive Task" "$command_file" + grep -q "TDD" "$command_file" + grep -q "constitution" "$command_file" +} + +@test "speckit.commits.md references parse-constitution.sh" { + command_file="$REPO_ROOT/.claude/commands/speckit.commits.md" + grep -q "parse-constitution.sh" "$command_file" +} + +@test "commits-template.md has Repetitive Tasks section" { + template="$REPO_ROOT/.specify/templates/commits-template.md" + grep -q "Repetitive Tasks" "$template" + grep -q "TDD-RED" "$template" + grep -q "TDD-GREEN" "$template" + grep -q "VERIFY" "$template" +}