mirror of
https://github.com/sstent/FitTrack_ReportGenerator.git
synced 2025-12-06 08:01:40 +00:00
sync
This commit is contained in:
@@ -1,187 +0,0 @@
|
|||||||
description = "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
|
|
||||||
|
|
||||||
## Operating Constraints
|
|
||||||
|
|
||||||
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
|
|
||||||
|
|
||||||
**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
|
|
||||||
|
|
||||||
## Execution Steps
|
|
||||||
|
|
||||||
### 1. Initialize Analysis Context
|
|
||||||
|
|
||||||
Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
|
|
||||||
|
|
||||||
- SPEC = FEATURE_DIR/spec.md
|
|
||||||
- PLAN = FEATURE_DIR/plan.md
|
|
||||||
- TASKS = FEATURE_DIR/tasks.md
|
|
||||||
|
|
||||||
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
|
|
||||||
|
|
||||||
### 2. Load Artifacts (Progressive Disclosure)
|
|
||||||
|
|
||||||
Load only the minimal necessary context from each artifact:
|
|
||||||
|
|
||||||
**From spec.md:**
|
|
||||||
|
|
||||||
- Overview/Context
|
|
||||||
- Functional Requirements
|
|
||||||
- Non-Functional Requirements
|
|
||||||
- User Stories
|
|
||||||
- Edge Cases (if present)
|
|
||||||
|
|
||||||
**From plan.md:**
|
|
||||||
|
|
||||||
- Architecture/stack choices
|
|
||||||
- Data Model references
|
|
||||||
- Phases
|
|
||||||
- Technical constraints
|
|
||||||
|
|
||||||
**From tasks.md:**
|
|
||||||
|
|
||||||
- Task IDs
|
|
||||||
- Descriptions
|
|
||||||
- Phase grouping
|
|
||||||
- Parallel markers [P]
|
|
||||||
- Referenced file paths
|
|
||||||
|
|
||||||
**From constitution:**
|
|
||||||
|
|
||||||
- Load `.specify/memory/constitution.md` for principle validation
|
|
||||||
|
|
||||||
### 3. Build Semantic Models
|
|
||||||
|
|
||||||
Create internal representations (do not include raw artifacts in output):
|
|
||||||
|
|
||||||
- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
|
|
||||||
- **User story/action inventory**: Discrete user actions with acceptance criteria
|
|
||||||
- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
|
|
||||||
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
|
|
||||||
|
|
||||||
### 4. Detection Passes (Token-Efficient Analysis)
|
|
||||||
|
|
||||||
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
|
|
||||||
|
|
||||||
#### A. Duplication Detection
|
|
||||||
|
|
||||||
- Identify near-duplicate requirements
|
|
||||||
- Mark lower-quality phrasing for consolidation
|
|
||||||
|
|
||||||
#### B. Ambiguity Detection
|
|
||||||
|
|
||||||
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
|
|
||||||
- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
|
|
||||||
|
|
||||||
#### C. Underspecification
|
|
||||||
|
|
||||||
- Requirements with verbs but missing object or measurable outcome
|
|
||||||
- User stories missing acceptance criteria alignment
|
|
||||||
- Tasks referencing files or components not defined in spec/plan
|
|
||||||
|
|
||||||
#### D. Constitution Alignment
|
|
||||||
|
|
||||||
- Any requirement or plan element conflicting with a MUST principle
|
|
||||||
- Missing mandated sections or quality gates from constitution
|
|
||||||
|
|
||||||
#### E. Coverage Gaps
|
|
||||||
|
|
||||||
- Requirements with zero associated tasks
|
|
||||||
- Tasks with no mapped requirement/story
|
|
||||||
- Non-functional requirements not reflected in tasks (e.g., performance, security)
|
|
||||||
|
|
||||||
#### F. Inconsistency
|
|
||||||
|
|
||||||
- Terminology drift (same concept named differently across files)
|
|
||||||
- Data entities referenced in plan but absent in spec (or vice versa)
|
|
||||||
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
|
|
||||||
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
|
|
||||||
|
|
||||||
### 5. Severity Assignment
|
|
||||||
|
|
||||||
Use this heuristic to prioritize findings:
|
|
||||||
|
|
||||||
- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
|
|
||||||
- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
|
|
||||||
- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
|
|
||||||
- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
|
|
||||||
|
|
||||||
### 6. Produce Compact Analysis Report
|
|
||||||
|
|
||||||
Output a Markdown report (no file writes) with the following structure:
|
|
||||||
|
|
||||||
## Specification Analysis Report
|
|
||||||
|
|
||||||
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
|
||||||
|----|----------|----------|-------------|---------|----------------|
|
|
||||||
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
|
|
||||||
|
|
||||||
(Add one row per finding; generate stable IDs prefixed by category initial.)
|
|
||||||
|
|
||||||
**Coverage Summary Table:**
|
|
||||||
|
|
||||||
| Requirement Key | Has Task? | Task IDs | Notes |
|
|
||||||
|-----------------|-----------|----------|-------|
|
|
||||||
|
|
||||||
**Constitution Alignment Issues:** (if any)
|
|
||||||
|
|
||||||
**Unmapped Tasks:** (if any)
|
|
||||||
|
|
||||||
**Metrics:**
|
|
||||||
|
|
||||||
- Total Requirements
|
|
||||||
- Total Tasks
|
|
||||||
- Coverage % (requirements with >=1 task)
|
|
||||||
- Ambiguity Count
|
|
||||||
- Duplication Count
|
|
||||||
- Critical Issues Count
|
|
||||||
|
|
||||||
### 7. Provide Next Actions
|
|
||||||
|
|
||||||
At end of report, output a concise Next Actions block:
|
|
||||||
|
|
||||||
- If CRITICAL issues exist: Recommend resolving before `/implement`
|
|
||||||
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
|
|
||||||
- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
|
|
||||||
|
|
||||||
### 8. Offer Remediation
|
|
||||||
|
|
||||||
Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
|
|
||||||
|
|
||||||
## Operating Principles
|
|
||||||
|
|
||||||
### Context Efficiency
|
|
||||||
|
|
||||||
- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
|
|
||||||
- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
|
|
||||||
- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
|
|
||||||
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
|
|
||||||
|
|
||||||
### Analysis Guidelines
|
|
||||||
|
|
||||||
- **NEVER modify files** (this is read-only analysis)
|
|
||||||
- **NEVER hallucinate missing sections** (if absent, report them accurately)
|
|
||||||
- **Prioritize constitution violations** (these are always CRITICAL)
|
|
||||||
- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
|
|
||||||
- **Report zero issues gracefully** (emit success report with coverage statistics)
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
{{args}}
|
|
||||||
"""
|
|
||||||
@@ -1,290 +0,0 @@
|
|||||||
description = "Generate a custom checklist for the current feature based on user requirements."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Generate a custom checklist for the current feature based on user requirements.
|
|
||||||
---
|
|
||||||
|
|
||||||
## Checklist Purpose: "Unit Tests for English"
|
|
||||||
|
|
||||||
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
|
|
||||||
|
|
||||||
**NOT for verification/testing**:
|
|
||||||
- ❌ NOT "Verify the button clicks correctly"
|
|
||||||
- ❌ NOT "Test error handling works"
|
|
||||||
- ❌ NOT "Confirm the API returns 200"
|
|
||||||
- ❌ NOT checking if code/implementation matches the spec
|
|
||||||
|
|
||||||
**FOR requirements quality validation**:
|
|
||||||
- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
|
|
||||||
- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
|
|
||||||
- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
|
|
||||||
- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
|
|
||||||
- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
|
|
||||||
|
|
||||||
**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Execution Steps
|
|
||||||
|
|
||||||
1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
|
|
||||||
- All file paths must be absolute.
|
|
||||||
|
|
||||||
2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
|
|
||||||
- Be generated from the user's phrasing + extracted signals from spec/plan/tasks
|
|
||||||
- Only ask about information that materially changes checklist content
|
|
||||||
- Be skipped individually if already unambiguous in `$ARGUMENTS`
|
|
||||||
- Prefer precision over breadth
|
|
||||||
|
|
||||||
Generation algorithm:
|
|
||||||
1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
|
|
||||||
2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
|
|
||||||
3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
|
|
||||||
4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
|
|
||||||
5. Formulate questions chosen from these archetypes:
|
|
||||||
- Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
|
|
||||||
- Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
|
|
||||||
- Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
|
|
||||||
- Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
|
|
||||||
- Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
|
|
||||||
- Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
|
|
||||||
|
|
||||||
Question formatting rules:
|
|
||||||
- If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
|
|
||||||
- Limit to A–E options maximum; omit table if a free-form answer is clearer
|
|
||||||
- Never ask the user to restate what they already said
|
|
||||||
- Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
|
|
||||||
|
|
||||||
Defaults when interaction impossible:
|
|
||||||
- Depth: Standard
|
|
||||||
- Audience: Reviewer (PR) if code-related; Author otherwise
|
|
||||||
- Focus: Top 2 relevance clusters
|
|
||||||
|
|
||||||
Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
|
|
||||||
|
|
||||||
3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
|
|
||||||
- Derive checklist theme (e.g., security, review, deploy, ux)
|
|
||||||
- Consolidate explicit must-have items mentioned by user
|
|
||||||
- Map focus selections to category scaffolding
|
|
||||||
- Infer any missing context from spec/plan/tasks (do NOT hallucinate)
|
|
||||||
|
|
||||||
4. **Load feature context**: Read from FEATURE_DIR:
|
|
||||||
- spec.md: Feature requirements and scope
|
|
||||||
- plan.md (if exists): Technical details, dependencies
|
|
||||||
- tasks.md (if exists): Implementation tasks
|
|
||||||
|
|
||||||
**Context Loading Strategy**:
|
|
||||||
- Load only necessary portions relevant to active focus areas (avoid full-file dumping)
|
|
||||||
- Prefer summarizing long sections into concise scenario/requirement bullets
|
|
||||||
- Use progressive disclosure: add follow-on retrieval only if gaps detected
|
|
||||||
- If source docs are large, generate interim summary items instead of embedding raw text
|
|
||||||
|
|
||||||
5. **Generate checklist** - Create "Unit Tests for Requirements":
|
|
||||||
- Create `FEATURE_DIR/checklists/` directory if it doesn't exist
|
|
||||||
- Generate unique checklist filename:
|
|
||||||
- Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
|
|
||||||
- Format: `[domain].md`
|
|
||||||
- If file exists, append to existing file
|
|
||||||
- Number items sequentially starting from CHK001
|
|
||||||
- Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
|
|
||||||
|
|
||||||
**CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
|
|
||||||
Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
|
|
||||||
- **Completeness**: Are all necessary requirements present?
|
|
||||||
- **Clarity**: Are requirements unambiguous and specific?
|
|
||||||
- **Consistency**: Do requirements align with each other?
|
|
||||||
- **Measurability**: Can requirements be objectively verified?
|
|
||||||
- **Coverage**: Are all scenarios/edge cases addressed?
|
|
||||||
|
|
||||||
**Category Structure** - Group items by requirement quality dimensions:
|
|
||||||
- **Requirement Completeness** (Are all necessary requirements documented?)
|
|
||||||
- **Requirement Clarity** (Are requirements specific and unambiguous?)
|
|
||||||
- **Requirement Consistency** (Do requirements align without conflicts?)
|
|
||||||
- **Acceptance Criteria Quality** (Are success criteria measurable?)
|
|
||||||
- **Scenario Coverage** (Are all flows/cases addressed?)
|
|
||||||
- **Edge Case Coverage** (Are boundary conditions defined?)
|
|
||||||
- **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
|
|
||||||
- **Dependencies & Assumptions** (Are they documented and validated?)
|
|
||||||
- **Ambiguities & Conflicts** (What needs clarification?)
|
|
||||||
|
|
||||||
**HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
|
|
||||||
|
|
||||||
❌ **WRONG** (Testing implementation):
|
|
||||||
- "Verify landing page displays 3 episode cards"
|
|
||||||
- "Test hover states work on desktop"
|
|
||||||
- "Confirm logo click navigates home"
|
|
||||||
|
|
||||||
✅ **CORRECT** (Testing requirements quality):
|
|
||||||
- "Are the exact number and layout of featured episodes specified?" [Completeness]
|
|
||||||
- "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
|
|
||||||
- "Are hover state requirements consistent across all interactive elements?" [Consistency]
|
|
||||||
- "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
|
|
||||||
- "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
|
|
||||||
- "Are loading states defined for asynchronous episode data?" [Completeness]
|
|
||||||
- "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
|
|
||||||
|
|
||||||
**ITEM STRUCTURE**:
|
|
||||||
Each item should follow this pattern:
|
|
||||||
- Question format asking about requirement quality
|
|
||||||
- Focus on what's WRITTEN (or not written) in the spec/plan
|
|
||||||
- Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
|
|
||||||
- Reference spec section `[Spec §X.Y]` when checking existing requirements
|
|
||||||
- Use `[Gap]` marker when checking for missing requirements
|
|
||||||
|
|
||||||
**EXAMPLES BY QUALITY DIMENSION**:
|
|
||||||
|
|
||||||
Completeness:
|
|
||||||
- "Are error handling requirements defined for all API failure modes? [Gap]"
|
|
||||||
- "Are accessibility requirements specified for all interactive elements? [Completeness]"
|
|
||||||
- "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
|
|
||||||
|
|
||||||
Clarity:
|
|
||||||
- "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
|
|
||||||
- "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
|
|
||||||
- "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
|
|
||||||
|
|
||||||
Consistency:
|
|
||||||
- "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
|
|
||||||
- "Are card component requirements consistent between landing and detail pages? [Consistency]"
|
|
||||||
|
|
||||||
Coverage:
|
|
||||||
- "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
|
|
||||||
- "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
|
|
||||||
- "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
|
|
||||||
|
|
||||||
Measurability:
|
|
||||||
- "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
|
|
||||||
- "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
|
|
||||||
|
|
||||||
**Scenario Classification & Coverage** (Requirements Quality Focus):
|
|
||||||
- Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
|
|
||||||
- For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
|
|
||||||
- If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
|
|
||||||
- Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
|
|
||||||
|
|
||||||
**Traceability Requirements**:
|
|
||||||
- MINIMUM: ≥80% of items MUST include at least one traceability reference
|
|
||||||
- Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
|
|
||||||
- If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
|
|
||||||
|
|
||||||
**Surface & Resolve Issues** (Requirements Quality Problems):
|
|
||||||
Ask questions about the requirements themselves:
|
|
||||||
- Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
|
|
||||||
- Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
|
|
||||||
- Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
|
|
||||||
- Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
|
|
||||||
- Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
|
|
||||||
|
|
||||||
**Content Consolidation**:
|
|
||||||
- Soft cap: If raw candidate items > 40, prioritize by risk/impact
|
|
||||||
- Merge near-duplicates checking the same requirement aspect
|
|
||||||
- If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
|
|
||||||
|
|
||||||
**🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
|
|
||||||
- ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
|
|
||||||
- ❌ References to code execution, user actions, system behavior
|
|
||||||
- ❌ "Displays correctly", "works properly", "functions as expected"
|
|
||||||
- ❌ "Click", "navigate", "render", "load", "execute"
|
|
||||||
- ❌ Test cases, test plans, QA procedures
|
|
||||||
- ❌ Implementation details (frameworks, APIs, algorithms)
|
|
||||||
|
|
||||||
**✅ REQUIRED PATTERNS** - These test requirements quality:
|
|
||||||
- ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
|
|
||||||
- ✅ "Is [vague term] quantified/clarified with specific criteria?"
|
|
||||||
- ✅ "Are requirements consistent between [section A] and [section B]?"
|
|
||||||
- ✅ "Can [requirement] be objectively measured/verified?"
|
|
||||||
- ✅ "Are [edge cases/scenarios] addressed in requirements?"
|
|
||||||
- ✅ "Does the spec define [missing aspect]?"
|
|
||||||
|
|
||||||
6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
|
|
||||||
|
|
||||||
7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
|
|
||||||
- Focus areas selected
|
|
||||||
- Depth level
|
|
||||||
- Actor/timing
|
|
||||||
- Any explicit user-specified must-have items incorporated
|
|
||||||
|
|
||||||
**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
|
|
||||||
|
|
||||||
- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
|
|
||||||
- Simple, memorable filenames that indicate checklist purpose
|
|
||||||
- Easy identification and navigation in the `checklists/` folder
|
|
||||||
|
|
||||||
To avoid clutter, use descriptive types and clean up obsolete checklists when done.
|
|
||||||
|
|
||||||
## Example Checklist Types & Sample Items
|
|
||||||
|
|
||||||
**UX Requirements Quality:** `ux.md`
|
|
||||||
|
|
||||||
Sample items (testing the requirements, NOT the implementation):
|
|
||||||
- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
|
|
||||||
- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
|
|
||||||
- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
|
|
||||||
- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
|
|
||||||
- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
|
|
||||||
- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
|
|
||||||
|
|
||||||
**API Requirements Quality:** `api.md`
|
|
||||||
|
|
||||||
Sample items:
|
|
||||||
- "Are error response formats specified for all failure scenarios? [Completeness]"
|
|
||||||
- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
|
|
||||||
- "Are authentication requirements consistent across all endpoints? [Consistency]"
|
|
||||||
- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
|
|
||||||
- "Is versioning strategy documented in requirements? [Gap]"
|
|
||||||
|
|
||||||
**Performance Requirements Quality:** `performance.md`
|
|
||||||
|
|
||||||
Sample items:
|
|
||||||
- "Are performance requirements quantified with specific metrics? [Clarity]"
|
|
||||||
- "Are performance targets defined for all critical user journeys? [Coverage]"
|
|
||||||
- "Are performance requirements under different load conditions specified? [Completeness]"
|
|
||||||
- "Can performance requirements be objectively measured? [Measurability]"
|
|
||||||
- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
|
|
||||||
|
|
||||||
**Security Requirements Quality:** `security.md`
|
|
||||||
|
|
||||||
Sample items:
|
|
||||||
- "Are authentication requirements specified for all protected resources? [Coverage]"
|
|
||||||
- "Are data protection requirements defined for sensitive information? [Completeness]"
|
|
||||||
- "Is the threat model documented and requirements aligned to it? [Traceability]"
|
|
||||||
- "Are security requirements consistent with compliance obligations? [Consistency]"
|
|
||||||
- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
|
|
||||||
|
|
||||||
## Anti-Examples: What NOT To Do
|
|
||||||
|
|
||||||
**❌ WRONG - These test implementation, not requirements:**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
|
|
||||||
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
|
|
||||||
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
|
|
||||||
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
|
|
||||||
```
|
|
||||||
|
|
||||||
**✅ CORRECT - These test requirements quality:**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
|
|
||||||
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
|
|
||||||
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
|
|
||||||
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
|
|
||||||
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
|
|
||||||
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key Differences:**
|
|
||||||
- Wrong: Tests if the system works correctly
|
|
||||||
- Correct: Tests if the requirements are written correctly
|
|
||||||
- Wrong: Verification of behavior
|
|
||||||
- Correct: Validation of requirement quality
|
|
||||||
- Wrong: "Does it do X?"
|
|
||||||
- Correct: "Is X clearly specified?"
|
|
||||||
"""
|
|
||||||
@@ -1,166 +0,0 @@
|
|||||||
description = "Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
|
|
||||||
|
|
||||||
Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
|
|
||||||
|
|
||||||
Execution steps:
|
|
||||||
|
|
||||||
1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
|
|
||||||
- `FEATURE_DIR`
|
|
||||||
- `FEATURE_SPEC`
|
|
||||||
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
|
|
||||||
- If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
|
|
||||||
|
|
||||||
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
|
|
||||||
|
|
||||||
Functional Scope & Behavior:
|
|
||||||
- Core user goals & success criteria
|
|
||||||
- Explicit out-of-scope declarations
|
|
||||||
- User roles / personas differentiation
|
|
||||||
|
|
||||||
Domain & Data Model:
|
|
||||||
- Entities, attributes, relationships
|
|
||||||
- Identity & uniqueness rules
|
|
||||||
- Lifecycle/state transitions
|
|
||||||
- Data volume / scale assumptions
|
|
||||||
|
|
||||||
Interaction & UX Flow:
|
|
||||||
- Critical user journeys / sequences
|
|
||||||
- Error/empty/loading states
|
|
||||||
- Accessibility or localization notes
|
|
||||||
|
|
||||||
Non-Functional Quality Attributes:
|
|
||||||
- Performance (latency, throughput targets)
|
|
||||||
- Scalability (horizontal/vertical, limits)
|
|
||||||
- Reliability & availability (uptime, recovery expectations)
|
|
||||||
- Observability (logging, metrics, tracing signals)
|
|
||||||
- Security & privacy (authN/Z, data protection, threat assumptions)
|
|
||||||
- Compliance / regulatory constraints (if any)
|
|
||||||
|
|
||||||
Integration & External Dependencies:
|
|
||||||
- External services/APIs and failure modes
|
|
||||||
- Data import/export formats
|
|
||||||
- Protocol/versioning assumptions
|
|
||||||
|
|
||||||
Edge Cases & Failure Handling:
|
|
||||||
- Negative scenarios
|
|
||||||
- Rate limiting / throttling
|
|
||||||
- Conflict resolution (e.g., concurrent edits)
|
|
||||||
|
|
||||||
Constraints & Tradeoffs:
|
|
||||||
- Technical constraints (language, storage, hosting)
|
|
||||||
- Explicit tradeoffs or rejected alternatives
|
|
||||||
|
|
||||||
Terminology & Consistency:
|
|
||||||
- Canonical glossary terms
|
|
||||||
- Avoided synonyms / deprecated terms
|
|
||||||
|
|
||||||
Completion Signals:
|
|
||||||
- Acceptance criteria testability
|
|
||||||
- Measurable Definition of Done style indicators
|
|
||||||
|
|
||||||
Misc / Placeholders:
|
|
||||||
- TODO markers / unresolved decisions
|
|
||||||
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
|
|
||||||
|
|
||||||
For each category with Partial or Missing status, add a candidate question opportunity unless:
|
|
||||||
- Clarification would not materially change implementation or validation strategy
|
|
||||||
- Information is better deferred to planning phase (note internally)
|
|
||||||
|
|
||||||
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
|
|
||||||
- Maximum of 10 total questions across the whole session.
|
|
||||||
- Each question must be answerable with EITHER:
|
|
||||||
* A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
|
|
||||||
* A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
|
|
||||||
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
|
|
||||||
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
|
|
||||||
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
|
|
||||||
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
|
|
||||||
- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
|
|
||||||
|
|
||||||
4. Sequential questioning loop (interactive):
|
|
||||||
- Present EXACTLY ONE question at a time.
|
|
||||||
- For multiple‑choice questions render options as a Markdown table:
|
|
||||||
|
|
||||||
| Option | Description |
|
|
||||||
|--------|-------------|
|
|
||||||
| A | <Option A description> |
|
|
||||||
| B | <Option B description> |
|
|
||||||
| C | <Option C description> | (add D/E as needed up to 5)
|
|
||||||
| Short | Provide a different short answer (<=5 words) | (Include only if free-form alternative is appropriate)
|
|
||||||
|
|
||||||
- For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
|
|
||||||
- After the user answers:
|
|
||||||
* Validate the answer maps to one option or fits the <=5 word constraint.
|
|
||||||
* If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
|
|
||||||
* Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
|
|
||||||
- Stop asking further questions when:
|
|
||||||
* All critical ambiguities resolved early (remaining queued items become unnecessary), OR
|
|
||||||
* User signals completion ("done", "good", "no more"), OR
|
|
||||||
* You reach 5 asked questions.
|
|
||||||
- Never reveal future queued questions in advance.
|
|
||||||
- If no valid questions exist at start, immediately report no critical ambiguities.
|
|
||||||
|
|
||||||
5. Integration after EACH accepted answer (incremental update approach):
|
|
||||||
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
|
|
||||||
- For the first integrated answer in this session:
|
|
||||||
* Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
|
|
||||||
* Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
|
|
||||||
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
|
|
||||||
- Then immediately apply the clarification to the most appropriate section(s):
|
|
||||||
* Functional ambiguity → Update or add a bullet in Functional Requirements.
|
|
||||||
* User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
|
|
||||||
* Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
|
|
||||||
* Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
|
|
||||||
* Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
|
|
||||||
* Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
|
|
||||||
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
|
|
||||||
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
|
|
||||||
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
|
|
||||||
- Keep each inserted clarification minimal and testable (avoid narrative drift).
|
|
||||||
|
|
||||||
6. Validation (performed after EACH write plus final pass):
|
|
||||||
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
|
|
||||||
- Total asked (accepted) questions ≤ 5.
|
|
||||||
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
|
|
||||||
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
|
|
||||||
- Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
|
|
||||||
- Terminology consistency: same canonical term used across all updated sections.
|
|
||||||
|
|
||||||
7. Write the updated spec back to `FEATURE_SPEC`.
|
|
||||||
|
|
||||||
8. Report completion (after questioning loop ends or early termination):
|
|
||||||
- Number of questions asked & answered.
|
|
||||||
- Path to updated spec.
|
|
||||||
- Sections touched (list names).
|
|
||||||
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
|
|
||||||
- If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
|
|
||||||
- Suggested next command.
|
|
||||||
|
|
||||||
Behavior rules:
|
|
||||||
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
|
|
||||||
- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
|
|
||||||
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
|
|
||||||
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
|
|
||||||
- Respect user early termination signals ("stop", "done", "proceed").
|
|
||||||
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
|
|
||||||
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
|
|
||||||
|
|
||||||
Context for prioritization: {{args}}
|
|
||||||
"""
|
|
||||||
@@ -1,81 +0,0 @@
|
|||||||
description = "Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
|
|
||||||
|
|
||||||
Follow this execution flow:
|
|
||||||
|
|
||||||
1. Load the existing constitution template at `.specify/memory/constitution.md`.
|
|
||||||
- Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
|
|
||||||
**IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
|
|
||||||
|
|
||||||
2. Collect/derive values for placeholders:
|
|
||||||
- If user input (conversation) supplies a value, use it.
|
|
||||||
- Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
|
|
||||||
- For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
|
|
||||||
- `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
|
|
||||||
* MAJOR: Backward incompatible governance/principle removals or redefinitions.
|
|
||||||
* MINOR: New principle/section added or materially expanded guidance.
|
|
||||||
* PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
|
|
||||||
- If version bump type ambiguous, propose reasoning before finalizing.
|
|
||||||
|
|
||||||
3. Draft the updated constitution content:
|
|
||||||
- Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
|
|
||||||
- Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
|
|
||||||
- Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
|
|
||||||
- Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
|
|
||||||
|
|
||||||
4. Consistency propagation checklist (convert prior checklist into active validations):
|
|
||||||
- Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
|
|
||||||
- Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
|
|
||||||
- Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
|
|
||||||
- Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
|
|
||||||
- Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
|
|
||||||
|
|
||||||
5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
|
|
||||||
- Version change: old → new
|
|
||||||
- List of modified principles (old title → new title if renamed)
|
|
||||||
- Added sections
|
|
||||||
- Removed sections
|
|
||||||
- Templates requiring updates (✅ updated / ⚠ pending) with file paths
|
|
||||||
- Follow-up TODOs if any placeholders intentionally deferred.
|
|
||||||
|
|
||||||
6. Validation before final output:
|
|
||||||
- No remaining unexplained bracket tokens.
|
|
||||||
- Version line matches report.
|
|
||||||
- Dates ISO format YYYY-MM-DD.
|
|
||||||
- Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
|
|
||||||
|
|
||||||
7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
|
|
||||||
|
|
||||||
8. Output a final summary to the user with:
|
|
||||||
- New version and bump rationale.
|
|
||||||
- Any files flagged for manual follow-up.
|
|
||||||
- Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
|
|
||||||
|
|
||||||
Formatting & Style Requirements:
|
|
||||||
- Use Markdown headings exactly as in the template (do not demote/promote levels).
|
|
||||||
- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
|
|
||||||
- Keep a single blank line between sections.
|
|
||||||
- Avoid trailing whitespace.
|
|
||||||
|
|
||||||
If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
|
|
||||||
|
|
||||||
If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
|
|
||||||
|
|
||||||
Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
|
|
||||||
"""
|
|
||||||
@@ -1,93 +0,0 @@
|
|||||||
description = "Execute the implementation plan by processing and executing all tasks defined in tasks.md"
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
|
|
||||||
- Scan all checklist files in the checklists/ directory
|
|
||||||
- For each checklist, count:
|
|
||||||
* Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
|
|
||||||
* Completed items: Lines matching `- [X]` or `- [x]`
|
|
||||||
* Incomplete items: Lines matching `- [ ]`
|
|
||||||
- Create a status table:
|
|
||||||
```
|
|
||||||
| Checklist | Total | Completed | Incomplete | Status |
|
|
||||||
|-----------|-------|-----------|------------|--------|
|
|
||||||
| ux.md | 12 | 12 | 0 | ✓ PASS |
|
|
||||||
| test.md | 8 | 5 | 3 | ✗ FAIL |
|
|
||||||
| security.md | 6 | 6 | 0 | ✓ PASS |
|
|
||||||
```
|
|
||||||
- Calculate overall status:
|
|
||||||
* **PASS**: All checklists have 0 incomplete items
|
|
||||||
* **FAIL**: One or more checklists have incomplete items
|
|
||||||
|
|
||||||
- **If any checklist is incomplete**:
|
|
||||||
* Display the table with incomplete item counts
|
|
||||||
* **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
|
|
||||||
* Wait for user response before continuing
|
|
||||||
* If user says "no" or "wait" or "stop", halt execution
|
|
||||||
* If user says "yes" or "proceed" or "continue", proceed to step 3
|
|
||||||
|
|
||||||
- **If all checklists are complete**:
|
|
||||||
* Display the table showing all checklists passed
|
|
||||||
* Automatically proceed to step 3
|
|
||||||
|
|
||||||
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 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
|
|
||||||
|
|
||||||
4. Parse tasks.md structure and extract:
|
|
||||||
- **Task phases**: Setup, Tests, Core, Integration, Polish
|
|
||||||
- **Task dependencies**: Sequential vs parallel execution rules
|
|
||||||
- **Task details**: ID, description, file paths, parallel markers [P]
|
|
||||||
- **Execution flow**: Order and dependency requirements
|
|
||||||
|
|
||||||
5. Execute implementation following the task plan:
|
|
||||||
- **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
|
|
||||||
- **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
|
|
||||||
|
|
||||||
6. 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
|
|
||||||
|
|
||||||
7. 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
|
|
||||||
- Provide clear error messages with context for debugging
|
|
||||||
- Suggest next steps if implementation cannot proceed
|
|
||||||
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
|
|
||||||
|
|
||||||
8. 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
|
|
||||||
|
|
||||||
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.
|
|
||||||
"""
|
|
||||||
@@ -1,84 +0,0 @@
|
|||||||
description = "Execute the implementation planning workflow using the plan template to generate design artifacts."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
|
|
||||||
|
|
||||||
2. **Load context**: Read FEATURE_SPEC and `.specify.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
|
|
||||||
|
|
||||||
3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
|
|
||||||
- Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
|
|
||||||
- Fill Constitution Check section from constitution
|
|
||||||
- Evaluate gates (ERROR if violations unjustified)
|
|
||||||
- Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
|
|
||||||
- Phase 1: Generate data-model.md, contracts/, quickstart.md
|
|
||||||
- Phase 1: Update agent context by running the agent script
|
|
||||||
- Re-evaluate Constitution Check post-design
|
|
||||||
|
|
||||||
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
|
|
||||||
|
|
||||||
## Phases
|
|
||||||
|
|
||||||
### Phase 0: Outline & Research
|
|
||||||
|
|
||||||
1. **Extract unknowns from Technical Context** above:
|
|
||||||
- For each NEEDS CLARIFICATION → research task
|
|
||||||
- For each dependency → best practices task
|
|
||||||
- For each integration → patterns task
|
|
||||||
|
|
||||||
2. **Generate and dispatch research agents**:
|
|
||||||
```
|
|
||||||
For each unknown in Technical Context:
|
|
||||||
Task: "Research {unknown} for {feature context}"
|
|
||||||
For each technology choice:
|
|
||||||
Task: "Find best practices for {tech} in {domain}"
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Consolidate findings** in `research.md` using format:
|
|
||||||
- Decision: [what was chosen]
|
|
||||||
- Rationale: [why chosen]
|
|
||||||
- Alternatives considered: [what else evaluated]
|
|
||||||
|
|
||||||
**Output**: research.md with all NEEDS CLARIFICATION resolved
|
|
||||||
|
|
||||||
### Phase 1: Design & Contracts
|
|
||||||
|
|
||||||
**Prerequisites:** `research.md` complete
|
|
||||||
|
|
||||||
1. **Extract entities from feature spec** → `data-model.md`:
|
|
||||||
- Entity name, fields, relationships
|
|
||||||
- Validation rules from requirements
|
|
||||||
- State transitions if applicable
|
|
||||||
|
|
||||||
2. **Generate API contracts** from functional requirements:
|
|
||||||
- For each user action → endpoint
|
|
||||||
- Use standard REST/GraphQL patterns
|
|
||||||
- Output OpenAPI/GraphQL schema to `/contracts/`
|
|
||||||
|
|
||||||
3. **Agent context update**:
|
|
||||||
- Run `.specify/scripts/bash/update-agent-context.sh gemini`
|
|
||||||
- These scripts detect which AI agent is in use
|
|
||||||
- Update the appropriate agent-specific context file
|
|
||||||
- Add only new technology from current plan
|
|
||||||
- Preserve manual additions between markers
|
|
||||||
|
|
||||||
**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
|
|
||||||
|
|
||||||
## Key rules
|
|
||||||
|
|
||||||
- Use absolute paths
|
|
||||||
- ERROR on gate failures or unresolved clarifications
|
|
||||||
"""
|
|
||||||
@@ -1,212 +0,0 @@
|
|||||||
description = "Create or update the feature specification from a natural language feature description."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Create or update the feature specification from a natural language feature description.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{{args}}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
|
|
||||||
|
|
||||||
Given that feature description, do this:
|
|
||||||
|
|
||||||
1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "{{args}}"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
|
|
||||||
**IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.
|
|
||||||
2. Load `.specify/templates/spec-template.md` to understand required sections.
|
|
||||||
|
|
||||||
3. Follow this execution flow:
|
|
||||||
|
|
||||||
1. Parse user description from Input
|
|
||||||
If empty: ERROR "No feature description provided"
|
|
||||||
2. Extract key concepts from description
|
|
||||||
Identify: actors, actions, data, constraints
|
|
||||||
3. For unclear aspects:
|
|
||||||
- Make informed guesses based on context and industry standards
|
|
||||||
- Only mark with [NEEDS CLARIFICATION: specific question] if:
|
|
||||||
- The choice significantly impacts feature scope or user experience
|
|
||||||
- Multiple reasonable interpretations exist with different implications
|
|
||||||
- No reasonable default exists
|
|
||||||
- **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
|
|
||||||
- Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
|
|
||||||
4. Fill User Scenarios & Testing section
|
|
||||||
If no clear user flow: ERROR "Cannot determine user scenarios"
|
|
||||||
5. Generate Functional Requirements
|
|
||||||
Each requirement must be testable
|
|
||||||
Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
|
|
||||||
6. Define Success Criteria
|
|
||||||
Create measurable, technology-agnostic outcomes
|
|
||||||
Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
|
|
||||||
Each criterion must be verifiable without implementation details
|
|
||||||
7. Identify Key Entities (if data involved)
|
|
||||||
8. Return: SUCCESS (spec ready for planning)
|
|
||||||
|
|
||||||
4. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
|
|
||||||
|
|
||||||
5. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
|
|
||||||
|
|
||||||
a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Specification Quality Checklist: [FEATURE NAME]
|
|
||||||
|
|
||||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
|
||||||
**Created**: [DATE]
|
|
||||||
**Feature**: [Link to spec.md]
|
|
||||||
|
|
||||||
## Content Quality
|
|
||||||
|
|
||||||
- [ ] No implementation details (languages, frameworks, APIs)
|
|
||||||
- [ ] Focused on user value and business needs
|
|
||||||
- [ ] Written for non-technical stakeholders
|
|
||||||
- [ ] All mandatory sections completed
|
|
||||||
|
|
||||||
## Requirement Completeness
|
|
||||||
|
|
||||||
- [ ] No [NEEDS CLARIFICATION] markers remain
|
|
||||||
- [ ] Requirements are testable and unambiguous
|
|
||||||
- [ ] Success criteria are measurable
|
|
||||||
- [ ] Success criteria are technology-agnostic (no implementation details)
|
|
||||||
- [ ] All acceptance scenarios are defined
|
|
||||||
- [ ] Edge cases are identified
|
|
||||||
- [ ] Scope is clearly bounded
|
|
||||||
- [ ] Dependencies and assumptions identified
|
|
||||||
|
|
||||||
## Feature Readiness
|
|
||||||
|
|
||||||
- [ ] All functional requirements have clear acceptance criteria
|
|
||||||
- [ ] User scenarios cover primary flows
|
|
||||||
- [ ] Feature meets measurable outcomes defined in Success Criteria
|
|
||||||
- [ ] No implementation details leak into specification
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
|
|
||||||
```
|
|
||||||
|
|
||||||
b. **Run Validation Check**: Review the spec against each checklist item:
|
|
||||||
- For each item, determine if it passes or fails
|
|
||||||
- Document specific issues found (quote relevant spec sections)
|
|
||||||
|
|
||||||
c. **Handle Validation Results**:
|
|
||||||
|
|
||||||
- **If all items pass**: Mark checklist complete and proceed to step 6
|
|
||||||
|
|
||||||
- **If items fail (excluding [NEEDS CLARIFICATION])**:
|
|
||||||
1. List the failing items and specific issues
|
|
||||||
2. Update the spec to address each issue
|
|
||||||
3. Re-run validation until all items pass (max 3 iterations)
|
|
||||||
4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
|
|
||||||
|
|
||||||
- **If [NEEDS CLARIFICATION] markers remain**:
|
|
||||||
1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
|
|
||||||
2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
|
|
||||||
3. For each clarification needed (max 3), present options to user in this format:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Question [N]: [Topic]
|
|
||||||
|
|
||||||
**Context**: [Quote relevant spec section]
|
|
||||||
|
|
||||||
**What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
|
|
||||||
|
|
||||||
**Suggested Answers**:
|
|
||||||
|
|
||||||
| Option | Answer | Implications |
|
|
||||||
|--------|--------|--------------|
|
|
||||||
| A | [First suggested answer] | [What this means for the feature] |
|
|
||||||
| B | [Second suggested answer] | [What this means for the feature] |
|
|
||||||
| C | [Third suggested answer] | [What this means for the feature] |
|
|
||||||
| Custom | Provide your own answer | [Explain how to provide custom input] |
|
|
||||||
|
|
||||||
**Your choice**: _[Wait for user response]_
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
|
|
||||||
- Use consistent spacing with pipes aligned
|
|
||||||
- Each cell should have spaces around content: `| Content |` not `|Content|`
|
|
||||||
- Header separator must have at least 3 dashes: `|--------|`
|
|
||||||
- Test that the table renders correctly in markdown preview
|
|
||||||
5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
|
|
||||||
6. Present all questions together before waiting for responses
|
|
||||||
7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
|
|
||||||
8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
|
|
||||||
9. Re-run validation after all clarifications are resolved
|
|
||||||
|
|
||||||
d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
|
|
||||||
|
|
||||||
6. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
|
|
||||||
|
|
||||||
**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
|
|
||||||
|
|
||||||
## General Guidelines
|
|
||||||
|
|
||||||
## Quick Guidelines
|
|
||||||
|
|
||||||
- Focus on **WHAT** users need and **WHY**.
|
|
||||||
- Avoid HOW to implement (no tech stack, APIs, code structure).
|
|
||||||
- Written for business stakeholders, not developers.
|
|
||||||
- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
|
|
||||||
|
|
||||||
### Section Requirements
|
|
||||||
|
|
||||||
- **Mandatory sections**: Must be completed for every feature
|
|
||||||
- **Optional sections**: Include only when relevant to the feature
|
|
||||||
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
|
|
||||||
|
|
||||||
### For AI Generation
|
|
||||||
|
|
||||||
When creating this spec from a user prompt:
|
|
||||||
|
|
||||||
1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
|
|
||||||
2. **Document assumptions**: Record reasonable defaults in the Assumptions section
|
|
||||||
3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
|
|
||||||
- Significantly impact feature scope or user experience
|
|
||||||
- Have multiple reasonable interpretations with different implications
|
|
||||||
- Lack any reasonable default
|
|
||||||
4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
|
|
||||||
5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
|
|
||||||
6. **Common areas needing clarification** (only if no reasonable default exists):
|
|
||||||
- Feature scope and boundaries (include/exclude specific use cases)
|
|
||||||
- User types and permissions (if multiple conflicting interpretations possible)
|
|
||||||
- Security/compliance requirements (when legally/financially significant)
|
|
||||||
|
|
||||||
**Examples of reasonable defaults** (don't ask about these):
|
|
||||||
|
|
||||||
- Data retention: Industry-standard practices for the domain
|
|
||||||
- Performance targets: Standard web/mobile app expectations unless specified
|
|
||||||
- Error handling: User-friendly messages with appropriate fallbacks
|
|
||||||
- Authentication method: Standard session-based or OAuth2 for web apps
|
|
||||||
- Integration patterns: RESTful APIs unless specified otherwise
|
|
||||||
|
|
||||||
### Success Criteria Guidelines
|
|
||||||
|
|
||||||
Success criteria must be:
|
|
||||||
|
|
||||||
1. **Measurable**: Include specific metrics (time, percentage, count, rate)
|
|
||||||
2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
|
|
||||||
3. **User-focused**: Describe outcomes from user/business perspective, not system internals
|
|
||||||
4. **Verifiable**: Can be tested/validated without knowing implementation details
|
|
||||||
|
|
||||||
**Good examples**:
|
|
||||||
|
|
||||||
- "Users can complete checkout in under 3 minutes"
|
|
||||||
- "System supports 10,000 concurrent users"
|
|
||||||
- "95% of searches return results in under 1 second"
|
|
||||||
- "Task completion rate improves by 40%"
|
|
||||||
|
|
||||||
**Bad examples** (implementation-focused):
|
|
||||||
|
|
||||||
- "API response time is under 200ms" (too technical, use "Users see results instantly")
|
|
||||||
- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
|
|
||||||
- "React components render efficiently" (framework-specific)
|
|
||||||
- "Redis cache hit rate above 80%" (technology-specific)
|
|
||||||
"""
|
|
||||||
@@ -1,115 +0,0 @@
|
|||||||
description = "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
|
|
||||||
|
|
||||||
2. **Load design documents**: Read from FEATURE_DIR:
|
|
||||||
- **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
|
|
||||||
- **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
|
|
||||||
- Note: Not all projects have all documents. Generate tasks based on what's available.
|
|
||||||
|
|
||||||
3. **Execute task generation workflow** (follow the template structure):
|
|
||||||
- Load plan.md and extract tech stack, libraries, project structure
|
|
||||||
- **Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)**
|
|
||||||
- If data-model.md exists: Extract entities → map to user stories
|
|
||||||
- If contracts/ exists: Each file → map endpoints to user stories
|
|
||||||
- If research.md exists: Extract decisions → generate setup tasks
|
|
||||||
- **Generate tasks ORGANIZED BY USER STORY**:
|
|
||||||
- Setup tasks (shared infrastructure needed by all stories)
|
|
||||||
- **Foundational tasks (prerequisites that must complete before ANY user story can start)**
|
|
||||||
- For each user story (in priority order P1, P2, P3...):
|
|
||||||
- Group all tasks needed to complete JUST that story
|
|
||||||
- Include models, services, endpoints, UI components specific to that story
|
|
||||||
- Mark which tasks are [P] parallelizable
|
|
||||||
- If tests requested: Include tests specific to that story
|
|
||||||
- Polish/Integration tasks (cross-cutting concerns)
|
|
||||||
- **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature spec or user asks for TDD approach
|
|
||||||
- Apply task rules:
|
|
||||||
- Different files = mark [P] for parallel
|
|
||||||
- Same file = sequential (no [P])
|
|
||||||
- If tests requested: Tests before implementation (TDD order)
|
|
||||||
- Number tasks sequentially (T001, T002...)
|
|
||||||
- Generate dependency graph showing user story completion order
|
|
||||||
- Create parallel execution examples per user story
|
|
||||||
- Validate task completeness (each user story has all needed tasks, independently testable)
|
|
||||||
|
|
||||||
4. **Generate tasks.md**: Use `.specify.specify/templates/tasks-template.md` as structure, fill with:
|
|
||||||
- Correct feature name from plan.md
|
|
||||||
- Phase 1: Setup tasks (project initialization)
|
|
||||||
- Phase 2: Foundational tasks (blocking prerequisites for all user stories)
|
|
||||||
- Phase 3+: One phase per user story (in priority order from spec.md)
|
|
||||||
- Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
|
|
||||||
- Clear [Story] labels (US1, US2, US3...) for each task
|
|
||||||
- [P] markers for parallelizable tasks within each story
|
|
||||||
- Checkpoint markers after each story phase
|
|
||||||
- Final Phase: Polish & cross-cutting concerns
|
|
||||||
- Numbered tasks (T001, T002...) in execution order
|
|
||||||
- Clear file paths for each task
|
|
||||||
- Dependencies section showing story completion order
|
|
||||||
- Parallel execution examples per story
|
|
||||||
- Implementation strategy section (MVP first, incremental delivery)
|
|
||||||
|
|
||||||
5. **Report**: Output path to generated tasks.md and summary:
|
|
||||||
- Total task count
|
|
||||||
- Task count per user story
|
|
||||||
- Parallel opportunities identified
|
|
||||||
- Independent test criteria for each story
|
|
||||||
- Suggested MVP scope (typically just User Story 1)
|
|
||||||
|
|
||||||
Context for task generation: {{args}}
|
|
||||||
|
|
||||||
The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
|
|
||||||
|
|
||||||
## Task Generation Rules
|
|
||||||
|
|
||||||
**IMPORTANT**: Tests are optional. Only generate test tasks if the user explicitly requested testing or TDD approach in the feature specification.
|
|
||||||
|
|
||||||
**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
|
|
||||||
|
|
||||||
1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
|
|
||||||
- Each user story (P1, P2, P3...) gets its own phase
|
|
||||||
- Map all related components to their story:
|
|
||||||
- Models needed for that story
|
|
||||||
- Services needed for that story
|
|
||||||
- Endpoints/UI needed for that story
|
|
||||||
- If tests requested: Tests specific to that story
|
|
||||||
- Mark story dependencies (most stories should be independent)
|
|
||||||
|
|
||||||
2. **From Contracts**:
|
|
||||||
- Map each contract/endpoint → to the user story it serves
|
|
||||||
- If tests requested: Each contract → contract test task [P] before implementation in that story's phase
|
|
||||||
|
|
||||||
3. **From Data Model**:
|
|
||||||
- Map each entity → to the user story(ies) that need it
|
|
||||||
- If entity serves multiple stories: Put in earliest story or Setup phase
|
|
||||||
- Relationships → service layer tasks in appropriate story phase
|
|
||||||
|
|
||||||
4. **From Setup/Infrastructure**:
|
|
||||||
- Shared infrastructure → Setup phase (Phase 1)
|
|
||||||
- Foundational/blocking tasks → Foundational phase (Phase 2)
|
|
||||||
- Examples: Database schema setup, authentication framework, core libraries, base configurations
|
|
||||||
- These MUST complete before any user story can be implemented
|
|
||||||
- Story-specific setup → within that story's phase
|
|
||||||
|
|
||||||
5. **Ordering**:
|
|
||||||
- Phase 1: Setup (project initialization)
|
|
||||||
- Phase 2: Foundational (blocking prerequisites - must complete before user stories)
|
|
||||||
- Phase 3+: User Stories in priority order (P1, P2, P3...)
|
|
||||||
- Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
|
|
||||||
- Final Phase: Polish & Cross-Cutting Concerns
|
|
||||||
- Each user story phase should be a complete, independently testable increment
|
|
||||||
"""
|
|
||||||
@@ -1,187 +0,0 @@
|
|||||||
description = "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
|
|
||||||
|
|
||||||
## Operating Constraints
|
|
||||||
|
|
||||||
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
|
|
||||||
|
|
||||||
**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
|
|
||||||
|
|
||||||
## Execution Steps
|
|
||||||
|
|
||||||
### 1. Initialize Analysis Context
|
|
||||||
|
|
||||||
Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
|
|
||||||
|
|
||||||
- SPEC = FEATURE_DIR/spec.md
|
|
||||||
- PLAN = FEATURE_DIR/plan.md
|
|
||||||
- TASKS = FEATURE_DIR/tasks.md
|
|
||||||
|
|
||||||
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
|
|
||||||
|
|
||||||
### 2. Load Artifacts (Progressive Disclosure)
|
|
||||||
|
|
||||||
Load only the minimal necessary context from each artifact:
|
|
||||||
|
|
||||||
**From spec.md:**
|
|
||||||
|
|
||||||
- Overview/Context
|
|
||||||
- Functional Requirements
|
|
||||||
- Non-Functional Requirements
|
|
||||||
- User Stories
|
|
||||||
- Edge Cases (if present)
|
|
||||||
|
|
||||||
**From plan.md:**
|
|
||||||
|
|
||||||
- Architecture/stack choices
|
|
||||||
- Data Model references
|
|
||||||
- Phases
|
|
||||||
- Technical constraints
|
|
||||||
|
|
||||||
**From tasks.md:**
|
|
||||||
|
|
||||||
- Task IDs
|
|
||||||
- Descriptions
|
|
||||||
- Phase grouping
|
|
||||||
- Parallel markers [P]
|
|
||||||
- Referenced file paths
|
|
||||||
|
|
||||||
**From constitution:**
|
|
||||||
|
|
||||||
- Load `.specify/memory/constitution.md` for principle validation
|
|
||||||
|
|
||||||
### 3. Build Semantic Models
|
|
||||||
|
|
||||||
Create internal representations (do not include raw artifacts in output):
|
|
||||||
|
|
||||||
- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
|
|
||||||
- **User story/action inventory**: Discrete user actions with acceptance criteria
|
|
||||||
- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
|
|
||||||
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
|
|
||||||
|
|
||||||
### 4. Detection Passes (Token-Efficient Analysis)
|
|
||||||
|
|
||||||
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
|
|
||||||
|
|
||||||
#### A. Duplication Detection
|
|
||||||
|
|
||||||
- Identify near-duplicate requirements
|
|
||||||
- Mark lower-quality phrasing for consolidation
|
|
||||||
|
|
||||||
#### B. Ambiguity Detection
|
|
||||||
|
|
||||||
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
|
|
||||||
- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
|
|
||||||
|
|
||||||
#### C. Underspecification
|
|
||||||
|
|
||||||
- Requirements with verbs but missing object or measurable outcome
|
|
||||||
- User stories missing acceptance criteria alignment
|
|
||||||
- Tasks referencing files or components not defined in spec/plan
|
|
||||||
|
|
||||||
#### D. Constitution Alignment
|
|
||||||
|
|
||||||
- Any requirement or plan element conflicting with a MUST principle
|
|
||||||
- Missing mandated sections or quality gates from constitution
|
|
||||||
|
|
||||||
#### E. Coverage Gaps
|
|
||||||
|
|
||||||
- Requirements with zero associated tasks
|
|
||||||
- Tasks with no mapped requirement/story
|
|
||||||
- Non-functional requirements not reflected in tasks (e.g., performance, security)
|
|
||||||
|
|
||||||
#### F. Inconsistency
|
|
||||||
|
|
||||||
- Terminology drift (same concept named differently across files)
|
|
||||||
- Data entities referenced in plan but absent in spec (or vice versa)
|
|
||||||
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
|
|
||||||
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
|
|
||||||
|
|
||||||
### 5. Severity Assignment
|
|
||||||
|
|
||||||
Use this heuristic to prioritize findings:
|
|
||||||
|
|
||||||
- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
|
|
||||||
- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
|
|
||||||
- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
|
|
||||||
- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
|
|
||||||
|
|
||||||
### 6. Produce Compact Analysis Report
|
|
||||||
|
|
||||||
Output a Markdown report (no file writes) with the following structure:
|
|
||||||
|
|
||||||
## Specification Analysis Report
|
|
||||||
|
|
||||||
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
|
||||||
|----|----------|----------|-------------|---------|----------------|
|
|
||||||
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
|
|
||||||
|
|
||||||
(Add one row per finding; generate stable IDs prefixed by category initial.)
|
|
||||||
|
|
||||||
**Coverage Summary Table:**
|
|
||||||
|
|
||||||
| Requirement Key | Has Task? | Task IDs | Notes |
|
|
||||||
|-----------------|-----------|----------|-------|
|
|
||||||
|
|
||||||
**Constitution Alignment Issues:** (if any)
|
|
||||||
|
|
||||||
**Unmapped Tasks:** (if any)
|
|
||||||
|
|
||||||
**Metrics:**
|
|
||||||
|
|
||||||
- Total Requirements
|
|
||||||
- Total Tasks
|
|
||||||
- Coverage % (requirements with >=1 task)
|
|
||||||
- Ambiguity Count
|
|
||||||
- Duplication Count
|
|
||||||
- Critical Issues Count
|
|
||||||
|
|
||||||
### 7. Provide Next Actions
|
|
||||||
|
|
||||||
At end of report, output a concise Next Actions block:
|
|
||||||
|
|
||||||
- If CRITICAL issues exist: Recommend resolving before `/implement`
|
|
||||||
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
|
|
||||||
- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
|
|
||||||
|
|
||||||
### 8. Offer Remediation
|
|
||||||
|
|
||||||
Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
|
|
||||||
|
|
||||||
## Operating Principles
|
|
||||||
|
|
||||||
### Context Efficiency
|
|
||||||
|
|
||||||
- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
|
|
||||||
- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
|
|
||||||
- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
|
|
||||||
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
|
|
||||||
|
|
||||||
### Analysis Guidelines
|
|
||||||
|
|
||||||
- **NEVER modify files** (this is read-only analysis)
|
|
||||||
- **NEVER hallucinate missing sections** (if absent, report them accurately)
|
|
||||||
- **Prioritize constitution violations** (these are always CRITICAL)
|
|
||||||
- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
|
|
||||||
- **Report zero issues gracefully** (emit success report with coverage statistics)
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
{{args}}
|
|
||||||
"""
|
|
||||||
@@ -1,290 +0,0 @@
|
|||||||
description = "Generate a custom checklist for the current feature based on user requirements."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Generate a custom checklist for the current feature based on user requirements.
|
|
||||||
---
|
|
||||||
|
|
||||||
## Checklist Purpose: "Unit Tests for English"
|
|
||||||
|
|
||||||
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
|
|
||||||
|
|
||||||
**NOT for verification/testing**:
|
|
||||||
- ❌ NOT "Verify the button clicks correctly"
|
|
||||||
- ❌ NOT "Test error handling works"
|
|
||||||
- ❌ NOT "Confirm the API returns 200"
|
|
||||||
- ❌ NOT checking if code/implementation matches the spec
|
|
||||||
|
|
||||||
**FOR requirements quality validation**:
|
|
||||||
- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
|
|
||||||
- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
|
|
||||||
- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
|
|
||||||
- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
|
|
||||||
- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
|
|
||||||
|
|
||||||
**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Execution Steps
|
|
||||||
|
|
||||||
1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
|
|
||||||
- All file paths must be absolute.
|
|
||||||
|
|
||||||
2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
|
|
||||||
- Be generated from the user's phrasing + extracted signals from spec/plan/tasks
|
|
||||||
- Only ask about information that materially changes checklist content
|
|
||||||
- Be skipped individually if already unambiguous in `$ARGUMENTS`
|
|
||||||
- Prefer precision over breadth
|
|
||||||
|
|
||||||
Generation algorithm:
|
|
||||||
1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
|
|
||||||
2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
|
|
||||||
3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
|
|
||||||
4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
|
|
||||||
5. Formulate questions chosen from these archetypes:
|
|
||||||
- Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
|
|
||||||
- Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
|
|
||||||
- Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
|
|
||||||
- Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
|
|
||||||
- Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
|
|
||||||
- Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
|
|
||||||
|
|
||||||
Question formatting rules:
|
|
||||||
- If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
|
|
||||||
- Limit to A–E options maximum; omit table if a free-form answer is clearer
|
|
||||||
- Never ask the user to restate what they already said
|
|
||||||
- Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
|
|
||||||
|
|
||||||
Defaults when interaction impossible:
|
|
||||||
- Depth: Standard
|
|
||||||
- Audience: Reviewer (PR) if code-related; Author otherwise
|
|
||||||
- Focus: Top 2 relevance clusters
|
|
||||||
|
|
||||||
Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
|
|
||||||
|
|
||||||
3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
|
|
||||||
- Derive checklist theme (e.g., security, review, deploy, ux)
|
|
||||||
- Consolidate explicit must-have items mentioned by user
|
|
||||||
- Map focus selections to category scaffolding
|
|
||||||
- Infer any missing context from spec/plan/tasks (do NOT hallucinate)
|
|
||||||
|
|
||||||
4. **Load feature context**: Read from FEATURE_DIR:
|
|
||||||
- spec.md: Feature requirements and scope
|
|
||||||
- plan.md (if exists): Technical details, dependencies
|
|
||||||
- tasks.md (if exists): Implementation tasks
|
|
||||||
|
|
||||||
**Context Loading Strategy**:
|
|
||||||
- Load only necessary portions relevant to active focus areas (avoid full-file dumping)
|
|
||||||
- Prefer summarizing long sections into concise scenario/requirement bullets
|
|
||||||
- Use progressive disclosure: add follow-on retrieval only if gaps detected
|
|
||||||
- If source docs are large, generate interim summary items instead of embedding raw text
|
|
||||||
|
|
||||||
5. **Generate checklist** - Create "Unit Tests for Requirements":
|
|
||||||
- Create `FEATURE_DIR/checklists/` directory if it doesn't exist
|
|
||||||
- Generate unique checklist filename:
|
|
||||||
- Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
|
|
||||||
- Format: `[domain].md`
|
|
||||||
- If file exists, append to existing file
|
|
||||||
- Number items sequentially starting from CHK001
|
|
||||||
- Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
|
|
||||||
|
|
||||||
**CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
|
|
||||||
Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
|
|
||||||
- **Completeness**: Are all necessary requirements present?
|
|
||||||
- **Clarity**: Are requirements unambiguous and specific?
|
|
||||||
- **Consistency**: Do requirements align with each other?
|
|
||||||
- **Measurability**: Can requirements be objectively verified?
|
|
||||||
- **Coverage**: Are all scenarios/edge cases addressed?
|
|
||||||
|
|
||||||
**Category Structure** - Group items by requirement quality dimensions:
|
|
||||||
- **Requirement Completeness** (Are all necessary requirements documented?)
|
|
||||||
- **Requirement Clarity** (Are requirements specific and unambiguous?)
|
|
||||||
- **Requirement Consistency** (Do requirements align without conflicts?)
|
|
||||||
- **Acceptance Criteria Quality** (Are success criteria measurable?)
|
|
||||||
- **Scenario Coverage** (Are all flows/cases addressed?)
|
|
||||||
- **Edge Case Coverage** (Are boundary conditions defined?)
|
|
||||||
- **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
|
|
||||||
- **Dependencies & Assumptions** (Are they documented and validated?)
|
|
||||||
- **Ambiguities & Conflicts** (What needs clarification?)
|
|
||||||
|
|
||||||
**HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
|
|
||||||
|
|
||||||
❌ **WRONG** (Testing implementation):
|
|
||||||
- "Verify landing page displays 3 episode cards"
|
|
||||||
- "Test hover states work on desktop"
|
|
||||||
- "Confirm logo click navigates home"
|
|
||||||
|
|
||||||
✅ **CORRECT** (Testing requirements quality):
|
|
||||||
- "Are the exact number and layout of featured episodes specified?" [Completeness]
|
|
||||||
- "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
|
|
||||||
- "Are hover state requirements consistent across all interactive elements?" [Consistency]
|
|
||||||
- "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
|
|
||||||
- "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
|
|
||||||
- "Are loading states defined for asynchronous episode data?" [Completeness]
|
|
||||||
- "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
|
|
||||||
|
|
||||||
**ITEM STRUCTURE**:
|
|
||||||
Each item should follow this pattern:
|
|
||||||
- Question format asking about requirement quality
|
|
||||||
- Focus on what's WRITTEN (or not written) in the spec/plan
|
|
||||||
- Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
|
|
||||||
- Reference spec section `[Spec §X.Y]` when checking existing requirements
|
|
||||||
- Use `[Gap]` marker when checking for missing requirements
|
|
||||||
|
|
||||||
**EXAMPLES BY QUALITY DIMENSION**:
|
|
||||||
|
|
||||||
Completeness:
|
|
||||||
- "Are error handling requirements defined for all API failure modes? [Gap]"
|
|
||||||
- "Are accessibility requirements specified for all interactive elements? [Completeness]"
|
|
||||||
- "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
|
|
||||||
|
|
||||||
Clarity:
|
|
||||||
- "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
|
|
||||||
- "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
|
|
||||||
- "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
|
|
||||||
|
|
||||||
Consistency:
|
|
||||||
- "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
|
|
||||||
- "Are card component requirements consistent between landing and detail pages? [Consistency]"
|
|
||||||
|
|
||||||
Coverage:
|
|
||||||
- "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
|
|
||||||
- "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
|
|
||||||
- "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
|
|
||||||
|
|
||||||
Measurability:
|
|
||||||
- "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
|
|
||||||
- "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
|
|
||||||
|
|
||||||
**Scenario Classification & Coverage** (Requirements Quality Focus):
|
|
||||||
- Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
|
|
||||||
- For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
|
|
||||||
- If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
|
|
||||||
- Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
|
|
||||||
|
|
||||||
**Traceability Requirements**:
|
|
||||||
- MINIMUM: ≥80% of items MUST include at least one traceability reference
|
|
||||||
- Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
|
|
||||||
- If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
|
|
||||||
|
|
||||||
**Surface & Resolve Issues** (Requirements Quality Problems):
|
|
||||||
Ask questions about the requirements themselves:
|
|
||||||
- Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
|
|
||||||
- Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
|
|
||||||
- Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
|
|
||||||
- Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
|
|
||||||
- Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
|
|
||||||
|
|
||||||
**Content Consolidation**:
|
|
||||||
- Soft cap: If raw candidate items > 40, prioritize by risk/impact
|
|
||||||
- Merge near-duplicates checking the same requirement aspect
|
|
||||||
- If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
|
|
||||||
|
|
||||||
**🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
|
|
||||||
- ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
|
|
||||||
- ❌ References to code execution, user actions, system behavior
|
|
||||||
- ❌ "Displays correctly", "works properly", "functions as expected"
|
|
||||||
- ❌ "Click", "navigate", "render", "load", "execute"
|
|
||||||
- ❌ Test cases, test plans, QA procedures
|
|
||||||
- ❌ Implementation details (frameworks, APIs, algorithms)
|
|
||||||
|
|
||||||
**✅ REQUIRED PATTERNS** - These test requirements quality:
|
|
||||||
- ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
|
|
||||||
- ✅ "Is [vague term] quantified/clarified with specific criteria?"
|
|
||||||
- ✅ "Are requirements consistent between [section A] and [section B]?"
|
|
||||||
- ✅ "Can [requirement] be objectively measured/verified?"
|
|
||||||
- ✅ "Are [edge cases/scenarios] addressed in requirements?"
|
|
||||||
- ✅ "Does the spec define [missing aspect]?"
|
|
||||||
|
|
||||||
6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
|
|
||||||
|
|
||||||
7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
|
|
||||||
- Focus areas selected
|
|
||||||
- Depth level
|
|
||||||
- Actor/timing
|
|
||||||
- Any explicit user-specified must-have items incorporated
|
|
||||||
|
|
||||||
**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
|
|
||||||
|
|
||||||
- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
|
|
||||||
- Simple, memorable filenames that indicate checklist purpose
|
|
||||||
- Easy identification and navigation in the `checklists/` folder
|
|
||||||
|
|
||||||
To avoid clutter, use descriptive types and clean up obsolete checklists when done.
|
|
||||||
|
|
||||||
## Example Checklist Types & Sample Items
|
|
||||||
|
|
||||||
**UX Requirements Quality:** `ux.md`
|
|
||||||
|
|
||||||
Sample items (testing the requirements, NOT the implementation):
|
|
||||||
- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
|
|
||||||
- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
|
|
||||||
- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
|
|
||||||
- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
|
|
||||||
- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
|
|
||||||
- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
|
|
||||||
|
|
||||||
**API Requirements Quality:** `api.md`
|
|
||||||
|
|
||||||
Sample items:
|
|
||||||
- "Are error response formats specified for all failure scenarios? [Completeness]"
|
|
||||||
- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
|
|
||||||
- "Are authentication requirements consistent across all endpoints? [Consistency]"
|
|
||||||
- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
|
|
||||||
- "Is versioning strategy documented in requirements? [Gap]"
|
|
||||||
|
|
||||||
**Performance Requirements Quality:** `performance.md`
|
|
||||||
|
|
||||||
Sample items:
|
|
||||||
- "Are performance requirements quantified with specific metrics? [Clarity]"
|
|
||||||
- "Are performance targets defined for all critical user journeys? [Coverage]"
|
|
||||||
- "Are performance requirements under different load conditions specified? [Completeness]"
|
|
||||||
- "Can performance requirements be objectively measured? [Measurability]"
|
|
||||||
- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
|
|
||||||
|
|
||||||
**Security Requirements Quality:** `security.md`
|
|
||||||
|
|
||||||
Sample items:
|
|
||||||
- "Are authentication requirements specified for all protected resources? [Coverage]"
|
|
||||||
- "Are data protection requirements defined for sensitive information? [Completeness]"
|
|
||||||
- "Is the threat model documented and requirements aligned to it? [Traceability]"
|
|
||||||
- "Are security requirements consistent with compliance obligations? [Consistency]"
|
|
||||||
- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
|
|
||||||
|
|
||||||
## Anti-Examples: What NOT To Do
|
|
||||||
|
|
||||||
**❌ WRONG - These test implementation, not requirements:**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
|
|
||||||
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
|
|
||||||
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
|
|
||||||
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
|
|
||||||
```
|
|
||||||
|
|
||||||
**✅ CORRECT - These test requirements quality:**
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
|
|
||||||
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
|
|
||||||
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
|
|
||||||
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
|
|
||||||
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
|
|
||||||
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key Differences:**
|
|
||||||
- Wrong: Tests if the system works correctly
|
|
||||||
- Correct: Tests if the requirements are written correctly
|
|
||||||
- Wrong: Verification of behavior
|
|
||||||
- Correct: Validation of requirement quality
|
|
||||||
- Wrong: "Does it do X?"
|
|
||||||
- Correct: "Is X clearly specified?"
|
|
||||||
"""
|
|
||||||
@@ -1,166 +0,0 @@
|
|||||||
description = "Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
|
|
||||||
|
|
||||||
Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
|
|
||||||
|
|
||||||
Execution steps:
|
|
||||||
|
|
||||||
1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
|
|
||||||
- `FEATURE_DIR`
|
|
||||||
- `FEATURE_SPEC`
|
|
||||||
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
|
|
||||||
- If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
|
|
||||||
|
|
||||||
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
|
|
||||||
|
|
||||||
Functional Scope & Behavior:
|
|
||||||
- Core user goals & success criteria
|
|
||||||
- Explicit out-of-scope declarations
|
|
||||||
- User roles / personas differentiation
|
|
||||||
|
|
||||||
Domain & Data Model:
|
|
||||||
- Entities, attributes, relationships
|
|
||||||
- Identity & uniqueness rules
|
|
||||||
- Lifecycle/state transitions
|
|
||||||
- Data volume / scale assumptions
|
|
||||||
|
|
||||||
Interaction & UX Flow:
|
|
||||||
- Critical user journeys / sequences
|
|
||||||
- Error/empty/loading states
|
|
||||||
- Accessibility or localization notes
|
|
||||||
|
|
||||||
Non-Functional Quality Attributes:
|
|
||||||
- Performance (latency, throughput targets)
|
|
||||||
- Scalability (horizontal/vertical, limits)
|
|
||||||
- Reliability & availability (uptime, recovery expectations)
|
|
||||||
- Observability (logging, metrics, tracing signals)
|
|
||||||
- Security & privacy (authN/Z, data protection, threat assumptions)
|
|
||||||
- Compliance / regulatory constraints (if any)
|
|
||||||
|
|
||||||
Integration & External Dependencies:
|
|
||||||
- External services/APIs and failure modes
|
|
||||||
- Data import/export formats
|
|
||||||
- Protocol/versioning assumptions
|
|
||||||
|
|
||||||
Edge Cases & Failure Handling:
|
|
||||||
- Negative scenarios
|
|
||||||
- Rate limiting / throttling
|
|
||||||
- Conflict resolution (e.g., concurrent edits)
|
|
||||||
|
|
||||||
Constraints & Tradeoffs:
|
|
||||||
- Technical constraints (language, storage, hosting)
|
|
||||||
- Explicit tradeoffs or rejected alternatives
|
|
||||||
|
|
||||||
Terminology & Consistency:
|
|
||||||
- Canonical glossary terms
|
|
||||||
- Avoided synonyms / deprecated terms
|
|
||||||
|
|
||||||
Completion Signals:
|
|
||||||
- Acceptance criteria testability
|
|
||||||
- Measurable Definition of Done style indicators
|
|
||||||
|
|
||||||
Misc / Placeholders:
|
|
||||||
- TODO markers / unresolved decisions
|
|
||||||
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
|
|
||||||
|
|
||||||
For each category with Partial or Missing status, add a candidate question opportunity unless:
|
|
||||||
- Clarification would not materially change implementation or validation strategy
|
|
||||||
- Information is better deferred to planning phase (note internally)
|
|
||||||
|
|
||||||
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
|
|
||||||
- Maximum of 10 total questions across the whole session.
|
|
||||||
- Each question must be answerable with EITHER:
|
|
||||||
* A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
|
|
||||||
* A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
|
|
||||||
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
|
|
||||||
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
|
|
||||||
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
|
|
||||||
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
|
|
||||||
- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
|
|
||||||
|
|
||||||
4. Sequential questioning loop (interactive):
|
|
||||||
- Present EXACTLY ONE question at a time.
|
|
||||||
- For multiple‑choice questions render options as a Markdown table:
|
|
||||||
|
|
||||||
| Option | Description |
|
|
||||||
|--------|-------------|
|
|
||||||
| A | <Option A description> |
|
|
||||||
| B | <Option B description> |
|
|
||||||
| C | <Option C description> | (add D/E as needed up to 5)
|
|
||||||
| Short | Provide a different short answer (<=5 words) | (Include only if free-form alternative is appropriate)
|
|
||||||
|
|
||||||
- For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
|
|
||||||
- After the user answers:
|
|
||||||
* Validate the answer maps to one option or fits the <=5 word constraint.
|
|
||||||
* If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
|
|
||||||
* Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
|
|
||||||
- Stop asking further questions when:
|
|
||||||
* All critical ambiguities resolved early (remaining queued items become unnecessary), OR
|
|
||||||
* User signals completion ("done", "good", "no more"), OR
|
|
||||||
* You reach 5 asked questions.
|
|
||||||
- Never reveal future queued questions in advance.
|
|
||||||
- If no valid questions exist at start, immediately report no critical ambiguities.
|
|
||||||
|
|
||||||
5. Integration after EACH accepted answer (incremental update approach):
|
|
||||||
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
|
|
||||||
- For the first integrated answer in this session:
|
|
||||||
* Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
|
|
||||||
* Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
|
|
||||||
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
|
|
||||||
- Then immediately apply the clarification to the most appropriate section(s):
|
|
||||||
* Functional ambiguity → Update or add a bullet in Functional Requirements.
|
|
||||||
* User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
|
|
||||||
* Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
|
|
||||||
* Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
|
|
||||||
* Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
|
|
||||||
* Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
|
|
||||||
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
|
|
||||||
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
|
|
||||||
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
|
|
||||||
- Keep each inserted clarification minimal and testable (avoid narrative drift).
|
|
||||||
|
|
||||||
6. Validation (performed after EACH write plus final pass):
|
|
||||||
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
|
|
||||||
- Total asked (accepted) questions ≤ 5.
|
|
||||||
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
|
|
||||||
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
|
|
||||||
- Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
|
|
||||||
- Terminology consistency: same canonical term used across all updated sections.
|
|
||||||
|
|
||||||
7. Write the updated spec back to `FEATURE_SPEC`.
|
|
||||||
|
|
||||||
8. Report completion (after questioning loop ends or early termination):
|
|
||||||
- Number of questions asked & answered.
|
|
||||||
- Path to updated spec.
|
|
||||||
- Sections touched (list names).
|
|
||||||
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
|
|
||||||
- If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
|
|
||||||
- Suggested next command.
|
|
||||||
|
|
||||||
Behavior rules:
|
|
||||||
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
|
|
||||||
- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
|
|
||||||
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
|
|
||||||
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
|
|
||||||
- Respect user early termination signals ("stop", "done", "proceed").
|
|
||||||
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
|
|
||||||
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
|
|
||||||
|
|
||||||
Context for prioritization: {{args}}
|
|
||||||
"""
|
|
||||||
@@ -1,81 +0,0 @@
|
|||||||
description = "Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
|
|
||||||
|
|
||||||
Follow this execution flow:
|
|
||||||
|
|
||||||
1. Load the existing constitution template at `.specify/memory/constitution.md`.
|
|
||||||
- Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
|
|
||||||
**IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
|
|
||||||
|
|
||||||
2. Collect/derive values for placeholders:
|
|
||||||
- If user input (conversation) supplies a value, use it.
|
|
||||||
- Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
|
|
||||||
- For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
|
|
||||||
- `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
|
|
||||||
* MAJOR: Backward incompatible governance/principle removals or redefinitions.
|
|
||||||
* MINOR: New principle/section added or materially expanded guidance.
|
|
||||||
* PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
|
|
||||||
- If version bump type ambiguous, propose reasoning before finalizing.
|
|
||||||
|
|
||||||
3. Draft the updated constitution content:
|
|
||||||
- Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
|
|
||||||
- Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
|
|
||||||
- Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
|
|
||||||
- Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
|
|
||||||
|
|
||||||
4. Consistency propagation checklist (convert prior checklist into active validations):
|
|
||||||
- Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
|
|
||||||
- Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
|
|
||||||
- Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
|
|
||||||
- Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
|
|
||||||
- Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
|
|
||||||
|
|
||||||
5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
|
|
||||||
- Version change: old → new
|
|
||||||
- List of modified principles (old title → new title if renamed)
|
|
||||||
- Added sections
|
|
||||||
- Removed sections
|
|
||||||
- Templates requiring updates (✅ updated / ⚠ pending) with file paths
|
|
||||||
- Follow-up TODOs if any placeholders intentionally deferred.
|
|
||||||
|
|
||||||
6. Validation before final output:
|
|
||||||
- No remaining unexplained bracket tokens.
|
|
||||||
- Version line matches report.
|
|
||||||
- Dates ISO format YYYY-MM-DD.
|
|
||||||
- Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
|
|
||||||
|
|
||||||
7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
|
|
||||||
|
|
||||||
8. Output a final summary to the user with:
|
|
||||||
- New version and bump rationale.
|
|
||||||
- Any files flagged for manual follow-up.
|
|
||||||
- Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
|
|
||||||
|
|
||||||
Formatting & Style Requirements:
|
|
||||||
- Use Markdown headings exactly as in the template (do not demote/promote levels).
|
|
||||||
- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
|
|
||||||
- Keep a single blank line between sections.
|
|
||||||
- Avoid trailing whitespace.
|
|
||||||
|
|
||||||
If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
|
|
||||||
|
|
||||||
If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
|
|
||||||
|
|
||||||
Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
|
|
||||||
"""
|
|
||||||
@@ -1,93 +0,0 @@
|
|||||||
description = "Execute the implementation plan by processing and executing all tasks defined in tasks.md"
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
|
|
||||||
- Scan all checklist files in the checklists/ directory
|
|
||||||
- For each checklist, count:
|
|
||||||
* Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
|
|
||||||
* Completed items: Lines matching `- [X]` or `- [x]`
|
|
||||||
* Incomplete items: Lines matching `- [ ]`
|
|
||||||
- Create a status table:
|
|
||||||
```
|
|
||||||
| Checklist | Total | Completed | Incomplete | Status |
|
|
||||||
|-----------|-------|-----------|------------|--------|
|
|
||||||
| ux.md | 12 | 12 | 0 | ✓ PASS |
|
|
||||||
| test.md | 8 | 5 | 3 | ✗ FAIL |
|
|
||||||
| security.md | 6 | 6 | 0 | ✓ PASS |
|
|
||||||
```
|
|
||||||
- Calculate overall status:
|
|
||||||
* **PASS**: All checklists have 0 incomplete items
|
|
||||||
* **FAIL**: One or more checklists have incomplete items
|
|
||||||
|
|
||||||
- **If any checklist is incomplete**:
|
|
||||||
* Display the table with incomplete item counts
|
|
||||||
* **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
|
|
||||||
* Wait for user response before continuing
|
|
||||||
* If user says "no" or "wait" or "stop", halt execution
|
|
||||||
* If user says "yes" or "proceed" or "continue", proceed to step 3
|
|
||||||
|
|
||||||
- **If all checklists are complete**:
|
|
||||||
* Display the table showing all checklists passed
|
|
||||||
* Automatically proceed to step 3
|
|
||||||
|
|
||||||
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 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
|
|
||||||
|
|
||||||
4. Parse tasks.md structure and extract:
|
|
||||||
- **Task phases**: Setup, Tests, Core, Integration, Polish
|
|
||||||
- **Task dependencies**: Sequential vs parallel execution rules
|
|
||||||
- **Task details**: ID, description, file paths, parallel markers [P]
|
|
||||||
- **Execution flow**: Order and dependency requirements
|
|
||||||
|
|
||||||
5. Execute implementation following the task plan:
|
|
||||||
- **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
|
|
||||||
- **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
|
|
||||||
|
|
||||||
6. 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
|
|
||||||
|
|
||||||
7. 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
|
|
||||||
- Provide clear error messages with context for debugging
|
|
||||||
- Suggest next steps if implementation cannot proceed
|
|
||||||
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
|
|
||||||
|
|
||||||
8. 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
|
|
||||||
|
|
||||||
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.
|
|
||||||
"""
|
|
||||||
@@ -1,84 +0,0 @@
|
|||||||
description = "Execute the implementation planning workflow using the plan template to generate design artifacts."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
|
|
||||||
|
|
||||||
2. **Load context**: Read FEATURE_SPEC and `.specify.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
|
|
||||||
|
|
||||||
3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
|
|
||||||
- Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
|
|
||||||
- Fill Constitution Check section from constitution
|
|
||||||
- Evaluate gates (ERROR if violations unjustified)
|
|
||||||
- Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
|
|
||||||
- Phase 1: Generate data-model.md, contracts/, quickstart.md
|
|
||||||
- Phase 1: Update agent context by running the agent script
|
|
||||||
- Re-evaluate Constitution Check post-design
|
|
||||||
|
|
||||||
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
|
|
||||||
|
|
||||||
## Phases
|
|
||||||
|
|
||||||
### Phase 0: Outline & Research
|
|
||||||
|
|
||||||
1. **Extract unknowns from Technical Context** above:
|
|
||||||
- For each NEEDS CLARIFICATION → research task
|
|
||||||
- For each dependency → best practices task
|
|
||||||
- For each integration → patterns task
|
|
||||||
|
|
||||||
2. **Generate and dispatch research agents**:
|
|
||||||
```
|
|
||||||
For each unknown in Technical Context:
|
|
||||||
Task: "Research {unknown} for {feature context}"
|
|
||||||
For each technology choice:
|
|
||||||
Task: "Find best practices for {tech} in {domain}"
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Consolidate findings** in `research.md` using format:
|
|
||||||
- Decision: [what was chosen]
|
|
||||||
- Rationale: [why chosen]
|
|
||||||
- Alternatives considered: [what else evaluated]
|
|
||||||
|
|
||||||
**Output**: research.md with all NEEDS CLARIFICATION resolved
|
|
||||||
|
|
||||||
### Phase 1: Design & Contracts
|
|
||||||
|
|
||||||
**Prerequisites:** `research.md` complete
|
|
||||||
|
|
||||||
1. **Extract entities from feature spec** → `data-model.md`:
|
|
||||||
- Entity name, fields, relationships
|
|
||||||
- Validation rules from requirements
|
|
||||||
- State transitions if applicable
|
|
||||||
|
|
||||||
2. **Generate API contracts** from functional requirements:
|
|
||||||
- For each user action → endpoint
|
|
||||||
- Use standard REST/GraphQL patterns
|
|
||||||
- Output OpenAPI/GraphQL schema to `/contracts/`
|
|
||||||
|
|
||||||
3. **Agent context update**:
|
|
||||||
- Run `.specify/scripts/bash/update-agent-context.sh gemini`
|
|
||||||
- These scripts detect which AI agent is in use
|
|
||||||
- Update the appropriate agent-specific context file
|
|
||||||
- Add only new technology from current plan
|
|
||||||
- Preserve manual additions between markers
|
|
||||||
|
|
||||||
**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
|
|
||||||
|
|
||||||
## Key rules
|
|
||||||
|
|
||||||
- Use absolute paths
|
|
||||||
- ERROR on gate failures or unresolved clarifications
|
|
||||||
"""
|
|
||||||
@@ -1,212 +0,0 @@
|
|||||||
description = "Create or update the feature specification from a natural language feature description."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Create or update the feature specification from a natural language feature description.
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Input
|
|
||||||
|
|
||||||
```text
|
|
||||||
$ARGUMENTS
|
|
||||||
```
|
|
||||||
|
|
||||||
You **MUST** consider the user input before proceeding (if not empty).
|
|
||||||
|
|
||||||
## Outline
|
|
||||||
|
|
||||||
The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{{args}}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
|
|
||||||
|
|
||||||
Given that feature description, do this:
|
|
||||||
|
|
||||||
1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "{{args}}"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
|
|
||||||
**IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.
|
|
||||||
2. Load `.specify/templates/spec-template.md` to understand required sections.
|
|
||||||
|
|
||||||
3. Follow this execution flow:
|
|
||||||
|
|
||||||
1. Parse user description from Input
|
|
||||||
If empty: ERROR "No feature description provided"
|
|
||||||
2. Extract key concepts from description
|
|
||||||
Identify: actors, actions, data, constraints
|
|
||||||
3. For unclear aspects:
|
|
||||||
- Make informed guesses based on context and industry standards
|
|
||||||
- Only mark with [NEEDS CLARIFICATION: specific question] if:
|
|
||||||
- The choice significantly impacts feature scope or user experience
|
|
||||||
- Multiple reasonable interpretations exist with different implications
|
|
||||||
- No reasonable default exists
|
|
||||||
- **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
|
|
||||||
- Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
|
|
||||||
4. Fill User Scenarios & Testing section
|
|
||||||
If no clear user flow: ERROR "Cannot determine user scenarios"
|
|
||||||
5. Generate Functional Requirements
|
|
||||||
Each requirement must be testable
|
|
||||||
Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
|
|
||||||
6. Define Success Criteria
|
|
||||||
Create measurable, technology-agnostic outcomes
|
|
||||||
Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
|
|
||||||
Each criterion must be verifiable without implementation details
|
|
||||||
7. Identify Key Entities (if data involved)
|
|
||||||
8. Return: SUCCESS (spec ready for planning)
|
|
||||||
|
|
||||||
4. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
|
|
||||||
|
|
||||||
5. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
|
|
||||||
|
|
||||||
a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Specification Quality Checklist: [FEATURE NAME]
|
|
||||||
|
|
||||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
|
||||||
**Created**: [DATE]
|
|
||||||
**Feature**: [Link to spec.md]
|
|
||||||
|
|
||||||
## Content Quality
|
|
||||||
|
|
||||||
- [ ] No implementation details (languages, frameworks, APIs)
|
|
||||||
- [ ] Focused on user value and business needs
|
|
||||||
- [ ] Written for non-technical stakeholders
|
|
||||||
- [ ] All mandatory sections completed
|
|
||||||
|
|
||||||
## Requirement Completeness
|
|
||||||
|
|
||||||
- [ ] No [NEEDS CLARIFICATION] markers remain
|
|
||||||
- [ ] Requirements are testable and unambiguous
|
|
||||||
- [ ] Success criteria are measurable
|
|
||||||
- [ ] Success criteria are technology-agnostic (no implementation details)
|
|
||||||
- [ ] All acceptance scenarios are defined
|
|
||||||
- [ ] Edge cases are identified
|
|
||||||
- [ ] Scope is clearly bounded
|
|
||||||
- [ ] Dependencies and assumptions identified
|
|
||||||
|
|
||||||
## Feature Readiness
|
|
||||||
|
|
||||||
- [ ] All functional requirements have clear acceptance criteria
|
|
||||||
- [ ] User scenarios cover primary flows
|
|
||||||
- [ ] Feature meets measurable outcomes defined in Success Criteria
|
|
||||||
- [ ] No implementation details leak into specification
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
|
|
||||||
```
|
|
||||||
|
|
||||||
b. **Run Validation Check**: Review the spec against each checklist item:
|
|
||||||
- For each item, determine if it passes or fails
|
|
||||||
- Document specific issues found (quote relevant spec sections)
|
|
||||||
|
|
||||||
c. **Handle Validation Results**:
|
|
||||||
|
|
||||||
- **If all items pass**: Mark checklist complete and proceed to step 6
|
|
||||||
|
|
||||||
- **If items fail (excluding [NEEDS CLARIFICATION])**:
|
|
||||||
1. List the failing items and specific issues
|
|
||||||
2. Update the spec to address each issue
|
|
||||||
3. Re-run validation until all items pass (max 3 iterations)
|
|
||||||
4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
|
|
||||||
|
|
||||||
- **If [NEEDS CLARIFICATION] markers remain**:
|
|
||||||
1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
|
|
||||||
2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
|
|
||||||
3. For each clarification needed (max 3), present options to user in this format:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Question [N]: [Topic]
|
|
||||||
|
|
||||||
**Context**: [Quote relevant spec section]
|
|
||||||
|
|
||||||
**What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
|
|
||||||
|
|
||||||
**Suggested Answers**:
|
|
||||||
|
|
||||||
| Option | Answer | Implications |
|
|
||||||
|--------|--------|--------------|
|
|
||||||
| A | [First suggested answer] | [What this means for the feature] |
|
|
||||||
| B | [Second suggested answer] | [What this means for the feature] |
|
|
||||||
| C | [Third suggested answer] | [What this means for the feature] |
|
|
||||||
| Custom | Provide your own answer | [Explain how to provide custom input] |
|
|
||||||
|
|
||||||
**Your choice**: _[Wait for user response]_
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
|
|
||||||
- Use consistent spacing with pipes aligned
|
|
||||||
- Each cell should have spaces around content: `| Content |` not `|Content|`
|
|
||||||
- Header separator must have at least 3 dashes: `|--------|`
|
|
||||||
- Test that the table renders correctly in markdown preview
|
|
||||||
5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
|
|
||||||
6. Present all questions together before waiting for responses
|
|
||||||
7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
|
|
||||||
8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
|
|
||||||
9. Re-run validation after all clarifications are resolved
|
|
||||||
|
|
||||||
d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
|
|
||||||
|
|
||||||
6. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
|
|
||||||
|
|
||||||
**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
|
|
||||||
|
|
||||||
## General Guidelines
|
|
||||||
|
|
||||||
## Quick Guidelines
|
|
||||||
|
|
||||||
- Focus on **WHAT** users need and **WHY**.
|
|
||||||
- Avoid HOW to implement (no tech stack, APIs, code structure).
|
|
||||||
- Written for business stakeholders, not developers.
|
|
||||||
- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
|
|
||||||
|
|
||||||
### Section Requirements
|
|
||||||
|
|
||||||
- **Mandatory sections**: Must be completed for every feature
|
|
||||||
- **Optional sections**: Include only when relevant to the feature
|
|
||||||
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
|
|
||||||
|
|
||||||
### For AI Generation
|
|
||||||
|
|
||||||
When creating this spec from a user prompt:
|
|
||||||
|
|
||||||
1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
|
|
||||||
2. **Document assumptions**: Record reasonable defaults in the Assumptions section
|
|
||||||
3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
|
|
||||||
- Significantly impact feature scope or user experience
|
|
||||||
- Have multiple reasonable interpretations with different implications
|
|
||||||
- Lack any reasonable default
|
|
||||||
4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
|
|
||||||
5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
|
|
||||||
6. **Common areas needing clarification** (only if no reasonable default exists):
|
|
||||||
- Feature scope and boundaries (include/exclude specific use cases)
|
|
||||||
- User types and permissions (if multiple conflicting interpretations possible)
|
|
||||||
- Security/compliance requirements (when legally/financially significant)
|
|
||||||
|
|
||||||
**Examples of reasonable defaults** (don't ask about these):
|
|
||||||
|
|
||||||
- Data retention: Industry-standard practices for the domain
|
|
||||||
- Performance targets: Standard web/mobile app expectations unless specified
|
|
||||||
- Error handling: User-friendly messages with appropriate fallbacks
|
|
||||||
- Authentication method: Standard session-based or OAuth2 for web apps
|
|
||||||
- Integration patterns: RESTful APIs unless specified otherwise
|
|
||||||
|
|
||||||
### Success Criteria Guidelines
|
|
||||||
|
|
||||||
Success criteria must be:
|
|
||||||
|
|
||||||
1. **Measurable**: Include specific metrics (time, percentage, count, rate)
|
|
||||||
2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
|
|
||||||
3. **User-focused**: Describe outcomes from user/business perspective, not system internals
|
|
||||||
4. **Verifiable**: Can be tested/validated without knowing implementation details
|
|
||||||
|
|
||||||
**Good examples**:
|
|
||||||
|
|
||||||
- "Users can complete checkout in under 3 minutes"
|
|
||||||
- "System supports 10,000 concurrent users"
|
|
||||||
- "95% of searches return results in under 1 second"
|
|
||||||
- "Task completion rate improves by 40%"
|
|
||||||
|
|
||||||
**Bad examples** (implementation-focused):
|
|
||||||
|
|
||||||
- "API response time is under 200ms" (too technical, use "Users see results instantly")
|
|
||||||
- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
|
|
||||||
- "React components render efficiently" (framework-specific)
|
|
||||||
- "Redis cache hit rate above 80%" (technology-specific)
|
|
||||||
"""
|
|
||||||
@@ -1,115 +0,0 @@
|
|||||||
description = "Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts."
|
|
||||||
|
|
||||||
prompt = """
|
|
||||||
---
|
|
||||||
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
|
|
||||||
|
|
||||||
2. **Load design documents**: Read from FEATURE_DIR:
|
|
||||||
- **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
|
|
||||||
- **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
|
|
||||||
- Note: Not all projects have all documents. Generate tasks based on what's available.
|
|
||||||
|
|
||||||
3. **Execute task generation workflow** (follow the template structure):
|
|
||||||
- Load plan.md and extract tech stack, libraries, project structure
|
|
||||||
- **Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)**
|
|
||||||
- If data-model.md exists: Extract entities → map to user stories
|
|
||||||
- If contracts/ exists: Each file → map endpoints to user stories
|
|
||||||
- If research.md exists: Extract decisions → generate setup tasks
|
|
||||||
- **Generate tasks ORGANIZED BY USER STORY**:
|
|
||||||
- Setup tasks (shared infrastructure needed by all stories)
|
|
||||||
- **Foundational tasks (prerequisites that must complete before ANY user story can start)**
|
|
||||||
- For each user story (in priority order P1, P2, P3...):
|
|
||||||
- Group all tasks needed to complete JUST that story
|
|
||||||
- Include models, services, endpoints, UI components specific to that story
|
|
||||||
- Mark which tasks are [P] parallelizable
|
|
||||||
- If tests requested: Include tests specific to that story
|
|
||||||
- Polish/Integration tasks (cross-cutting concerns)
|
|
||||||
- **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature spec or user asks for TDD approach
|
|
||||||
- Apply task rules:
|
|
||||||
- Different files = mark [P] for parallel
|
|
||||||
- Same file = sequential (no [P])
|
|
||||||
- If tests requested: Tests before implementation (TDD order)
|
|
||||||
- Number tasks sequentially (T001, T002...)
|
|
||||||
- Generate dependency graph showing user story completion order
|
|
||||||
- Create parallel execution examples per user story
|
|
||||||
- Validate task completeness (each user story has all needed tasks, independently testable)
|
|
||||||
|
|
||||||
4. **Generate tasks.md**: Use `.specify.specify/templates/tasks-template.md` as structure, fill with:
|
|
||||||
- Correct feature name from plan.md
|
|
||||||
- Phase 1: Setup tasks (project initialization)
|
|
||||||
- Phase 2: Foundational tasks (blocking prerequisites for all user stories)
|
|
||||||
- Phase 3+: One phase per user story (in priority order from spec.md)
|
|
||||||
- Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
|
|
||||||
- Clear [Story] labels (US1, US2, US3...) for each task
|
|
||||||
- [P] markers for parallelizable tasks within each story
|
|
||||||
- Checkpoint markers after each story phase
|
|
||||||
- Final Phase: Polish & cross-cutting concerns
|
|
||||||
- Numbered tasks (T001, T002...) in execution order
|
|
||||||
- Clear file paths for each task
|
|
||||||
- Dependencies section showing story completion order
|
|
||||||
- Parallel execution examples per story
|
|
||||||
- Implementation strategy section (MVP first, incremental delivery)
|
|
||||||
|
|
||||||
5. **Report**: Output path to generated tasks.md and summary:
|
|
||||||
- Total task count
|
|
||||||
- Task count per user story
|
|
||||||
- Parallel opportunities identified
|
|
||||||
- Independent test criteria for each story
|
|
||||||
- Suggested MVP scope (typically just User Story 1)
|
|
||||||
|
|
||||||
Context for task generation: {{args}}
|
|
||||||
|
|
||||||
The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
|
|
||||||
|
|
||||||
## Task Generation Rules
|
|
||||||
|
|
||||||
**IMPORTANT**: Tests are optional. Only generate test tasks if the user explicitly requested testing or TDD approach in the feature specification.
|
|
||||||
|
|
||||||
**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
|
|
||||||
|
|
||||||
1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
|
|
||||||
- Each user story (P1, P2, P3...) gets its own phase
|
|
||||||
- Map all related components to their story:
|
|
||||||
- Models needed for that story
|
|
||||||
- Services needed for that story
|
|
||||||
- Endpoints/UI needed for that story
|
|
||||||
- If tests requested: Tests specific to that story
|
|
||||||
- Mark story dependencies (most stories should be independent)
|
|
||||||
|
|
||||||
2. **From Contracts**:
|
|
||||||
- Map each contract/endpoint → to the user story it serves
|
|
||||||
- If tests requested: Each contract → contract test task [P] before implementation in that story's phase
|
|
||||||
|
|
||||||
3. **From Data Model**:
|
|
||||||
- Map each entity → to the user story(ies) that need it
|
|
||||||
- If entity serves multiple stories: Put in earliest story or Setup phase
|
|
||||||
- Relationships → service layer tasks in appropriate story phase
|
|
||||||
|
|
||||||
4. **From Setup/Infrastructure**:
|
|
||||||
- Shared infrastructure → Setup phase (Phase 1)
|
|
||||||
- Foundational/blocking tasks → Foundational phase (Phase 2)
|
|
||||||
- Examples: Database schema setup, authentication framework, core libraries, base configurations
|
|
||||||
- These MUST complete before any user story can be implemented
|
|
||||||
- Story-specific setup → within that story's phase
|
|
||||||
|
|
||||||
5. **Ordering**:
|
|
||||||
- Phase 1: Setup (project initialization)
|
|
||||||
- Phase 2: Foundational (blocking prerequisites - must complete before user stories)
|
|
||||||
- Phase 3+: User Stories in priority order (P1, P2, P3...)
|
|
||||||
- Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
|
|
||||||
- Final Phase: Polish & Cross-Cutting Concerns
|
|
||||||
- Each user story phase should be a complete, independently testable increment
|
|
||||||
"""
|
|
||||||
@@ -1,44 +0,0 @@
|
|||||||
<!--
|
|
||||||
Sync Impact Report:
|
|
||||||
- Version change: None (initial creation) -> 1.0.0
|
|
||||||
- List of modified principles: All (initial population)
|
|
||||||
- Added sections: All (initial population)
|
|
||||||
- Removed sections: None
|
|
||||||
- Templates requiring updates:
|
|
||||||
- .specify/templates/plan-template.md: ⚠ pending (Constitution Check section needs update)
|
|
||||||
- .specify/templates/spec-template.md: ⚠ pending (Implicit alignment with principles needs review)
|
|
||||||
- .specify/templates/tasks-template.md: ⚠ pending (Test-First principle alignment needs review)
|
|
||||||
- Follow-up TODOs: TODO(RATIFICATION_DATE)
|
|
||||||
-->
|
|
||||||
# FitTrack Report Generator Constitution
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
### I. Library-First
|
|
||||||
Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries
|
|
||||||
|
|
||||||
### II. CLI Interface
|
|
||||||
Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats
|
|
||||||
|
|
||||||
### III. Test-First (NON-NEGOTIABLE)
|
|
||||||
TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced
|
|
||||||
|
|
||||||
### IV. Integration Testing
|
|
||||||
Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas
|
|
||||||
|
|
||||||
### V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity
|
|
||||||
Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles
|
|
||||||
|
|
||||||
## Additional Constraints
|
|
||||||
|
|
||||||
Technology stack requirements, compliance standards, deployment policies, etc.
|
|
||||||
|
|
||||||
## Development Workflow
|
|
||||||
|
|
||||||
Code review requirements, testing gates, deployment approval process, etc.
|
|
||||||
|
|
||||||
## Governance
|
|
||||||
|
|
||||||
All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance
|
|
||||||
|
|
||||||
**Version**: 1.0.0 | **Ratified**: TODO(RATIFICATION_DATE) | **Last Amended**: 2025-10-09
|
|
||||||
@@ -1,166 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
|
|
||||||
# Consolidated prerequisite checking script
|
|
||||||
#
|
|
||||||
# This script provides unified prerequisite checking for Spec-Driven Development workflow.
|
|
||||||
# It replaces the functionality previously spread across multiple scripts.
|
|
||||||
#
|
|
||||||
# Usage: ./check-prerequisites.sh [OPTIONS]
|
|
||||||
#
|
|
||||||
# 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
|
|
||||||
# --paths-only Only output path variables (no validation)
|
|
||||||
# --help, -h Show help message
|
|
||||||
#
|
|
||||||
# OUTPUTS:
|
|
||||||
# JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
|
|
||||||
# Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
|
|
||||||
# Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
# Parse command line arguments
|
|
||||||
JSON_MODE=false
|
|
||||||
REQUIRE_TASKS=false
|
|
||||||
INCLUDE_TASKS=false
|
|
||||||
PATHS_ONLY=false
|
|
||||||
|
|
||||||
for arg in "$@"; do
|
|
||||||
case "$arg" in
|
|
||||||
--json)
|
|
||||||
JSON_MODE=true
|
|
||||||
;;
|
|
||||||
--require-tasks)
|
|
||||||
REQUIRE_TASKS=true
|
|
||||||
;;
|
|
||||||
--include-tasks)
|
|
||||||
INCLUDE_TASKS=true
|
|
||||||
;;
|
|
||||||
--paths-only)
|
|
||||||
PATHS_ONLY=true
|
|
||||||
;;
|
|
||||||
--help|-h)
|
|
||||||
cat << 'EOF'
|
|
||||||
Usage: check-prerequisites.sh [OPTIONS]
|
|
||||||
|
|
||||||
Consolidated prerequisite checking for Spec-Driven Development workflow.
|
|
||||||
|
|
||||||
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
|
|
||||||
--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
|
|
||||||
|
|
||||||
# Get feature paths only (no validation)
|
|
||||||
./check-prerequisites.sh --paths-only
|
|
||||||
|
|
||||||
EOF
|
|
||||||
exit 0
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
|
|
||||||
exit 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
done
|
|
||||||
|
|
||||||
# Source common functions
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
source "$SCRIPT_DIR/common.sh"
|
|
||||||
|
|
||||||
# Get feature paths and validate branch
|
|
||||||
eval $(get_feature_paths)
|
|
||||||
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
|
|
||||||
|
|
||||||
# If paths-only mode, output paths and exit (support JSON + paths-only combined)
|
|
||||||
if $PATHS_ONLY; then
|
|
||||||
if $JSON_MODE; then
|
|
||||||
# Minimal JSON paths payload (no validation performed)
|
|
||||||
printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
|
|
||||||
"$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
|
|
||||||
else
|
|
||||||
echo "REPO_ROOT: $REPO_ROOT"
|
|
||||||
echo "BRANCH: $CURRENT_BRANCH"
|
|
||||||
echo "FEATURE_DIR: $FEATURE_DIR"
|
|
||||||
echo "FEATURE_SPEC: $FEATURE_SPEC"
|
|
||||||
echo "IMPL_PLAN: $IMPL_PLAN"
|
|
||||||
echo "TASKS: $TASKS"
|
|
||||||
fi
|
|
||||||
exit 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Validate required directories and files
|
|
||||||
if [[ ! -d "$FEATURE_DIR" ]]; then
|
|
||||||
echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
|
|
||||||
echo "Run /speckit.specify first to create the feature structure." >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ ! -f "$IMPL_PLAN" ]]; then
|
|
||||||
echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
|
|
||||||
echo "Run /speckit.plan first to create the implementation plan." >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Check for tasks.md if required
|
|
||||||
if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
|
|
||||||
echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
|
|
||||||
echo "Run /speckit.tasks first to create the task list." >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Build list of available documents
|
|
||||||
docs=()
|
|
||||||
|
|
||||||
# Always check these optional docs
|
|
||||||
[[ -f "$RESEARCH" ]] && docs+=("research.md")
|
|
||||||
[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
|
|
||||||
|
|
||||||
# Check contracts directory (only if it exists and has files)
|
|
||||||
if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
|
|
||||||
docs+=("contracts/")
|
|
||||||
fi
|
|
||||||
|
|
||||||
[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
|
|
||||||
|
|
||||||
# Include tasks.md if requested and it exists
|
|
||||||
if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
|
|
||||||
docs+=("tasks.md")
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Output results
|
|
||||||
if $JSON_MODE; then
|
|
||||||
# Build JSON array of documents
|
|
||||||
if [[ ${#docs[@]} -eq 0 ]]; then
|
|
||||||
json_docs="[]"
|
|
||||||
else
|
|
||||||
json_docs=$(printf '"%s",' "${docs[@]}")
|
|
||||||
json_docs="[${json_docs%,}]"
|
|
||||||
fi
|
|
||||||
|
|
||||||
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
|
|
||||||
else
|
|
||||||
# Text output
|
|
||||||
echo "FEATURE_DIR:$FEATURE_DIR"
|
|
||||||
echo "AVAILABLE_DOCS:"
|
|
||||||
|
|
||||||
# Show status of each potential document
|
|
||||||
check_file "$RESEARCH" "research.md"
|
|
||||||
check_file "$DATA_MODEL" "data-model.md"
|
|
||||||
check_dir "$CONTRACTS_DIR" "contracts/"
|
|
||||||
check_file "$QUICKSTART" "quickstart.md"
|
|
||||||
|
|
||||||
if $INCLUDE_TASKS; then
|
|
||||||
check_file "$TASKS" "tasks.md"
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
@@ -1,113 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
# Common functions and variables for all scripts
|
|
||||||
|
|
||||||
# Get repository root, with fallback for non-git repositories
|
|
||||||
get_repo_root() {
|
|
||||||
if git rev-parse --show-toplevel >/dev/null 2>&1; then
|
|
||||||
git rev-parse --show-toplevel
|
|
||||||
else
|
|
||||||
# Fall back to script location for non-git repos
|
|
||||||
local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
(cd "$script_dir/../../.." && pwd)
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
# Get current branch, with fallback for non-git repositories
|
|
||||||
get_current_branch() {
|
|
||||||
# First check if SPECIFY_FEATURE environment variable is set
|
|
||||||
if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
|
|
||||||
echo "$SPECIFY_FEATURE"
|
|
||||||
return
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Then check git if available
|
|
||||||
if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
|
|
||||||
git rev-parse --abbrev-ref HEAD
|
|
||||||
return
|
|
||||||
fi
|
|
||||||
|
|
||||||
# For non-git repos, try to find the latest feature directory
|
|
||||||
local repo_root=$(get_repo_root)
|
|
||||||
local specs_dir="$repo_root/specs"
|
|
||||||
|
|
||||||
if [[ -d "$specs_dir" ]]; then
|
|
||||||
local latest_feature=""
|
|
||||||
local highest=0
|
|
||||||
|
|
||||||
for dir in "$specs_dir"/*; do
|
|
||||||
if [[ -d "$dir" ]]; then
|
|
||||||
local dirname=$(basename "$dir")
|
|
||||||
if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
|
|
||||||
local number=${BASH_REMATCH[1]}
|
|
||||||
number=$((10#$number))
|
|
||||||
if [[ "$number" -gt "$highest" ]]; then
|
|
||||||
highest=$number
|
|
||||||
latest_feature=$dirname
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
|
|
||||||
if [[ -n "$latest_feature" ]]; then
|
|
||||||
echo "$latest_feature"
|
|
||||||
return
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo "main" # Final fallback
|
|
||||||
}
|
|
||||||
|
|
||||||
# Check if we have git available
|
|
||||||
has_git() {
|
|
||||||
git rev-parse --show-toplevel >/dev/null 2>&1
|
|
||||||
}
|
|
||||||
|
|
||||||
check_feature_branch() {
|
|
||||||
local branch="$1"
|
|
||||||
local has_git_repo="$2"
|
|
||||||
|
|
||||||
# For non-git repos, we can't enforce branch naming but still provide output
|
|
||||||
if [[ "$has_git_repo" != "true" ]]; then
|
|
||||||
echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
|
|
||||||
return 0
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
|
|
||||||
echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
|
|
||||||
echo "Feature branches should be named like: 001-feature-name" >&2
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
return 0
|
|
||||||
}
|
|
||||||
|
|
||||||
get_feature_dir() { echo "$1/specs/$2"; }
|
|
||||||
|
|
||||||
get_feature_paths() {
|
|
||||||
local repo_root=$(get_repo_root)
|
|
||||||
local current_branch=$(get_current_branch)
|
|
||||||
local has_git_repo="false"
|
|
||||||
|
|
||||||
if has_git; then
|
|
||||||
has_git_repo="true"
|
|
||||||
fi
|
|
||||||
|
|
||||||
local feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
|
|
||||||
|
|
||||||
cat <<EOF
|
|
||||||
REPO_ROOT='$repo_root'
|
|
||||||
CURRENT_BRANCH='$current_branch'
|
|
||||||
HAS_GIT='$has_git_repo'
|
|
||||||
FEATURE_DIR='$feature_dir'
|
|
||||||
FEATURE_SPEC='$feature_dir/spec.md'
|
|
||||||
IMPL_PLAN='$feature_dir/plan.md'
|
|
||||||
TASKS='$feature_dir/tasks.md'
|
|
||||||
RESEARCH='$feature_dir/research.md'
|
|
||||||
DATA_MODEL='$feature_dir/data-model.md'
|
|
||||||
QUICKSTART='$feature_dir/quickstart.md'
|
|
||||||
CONTRACTS_DIR='$feature_dir/contracts'
|
|
||||||
EOF
|
|
||||||
}
|
|
||||||
|
|
||||||
check_file() { [[ -f "$1" ]] && echo " ✓ $2" || echo " ✗ $2"; }
|
|
||||||
check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo " ✓ $2" || echo " ✗ $2"; }
|
|
||||||
@@ -1,97 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
JSON_MODE=false
|
|
||||||
ARGS=()
|
|
||||||
for arg in "$@"; do
|
|
||||||
case "$arg" in
|
|
||||||
--json) JSON_MODE=true ;;
|
|
||||||
--help|-h) echo "Usage: $0 [--json] <feature_description>"; exit 0 ;;
|
|
||||||
*) ARGS+=("$arg") ;;
|
|
||||||
esac
|
|
||||||
done
|
|
||||||
|
|
||||||
FEATURE_DESCRIPTION="${ARGS[*]}"
|
|
||||||
if [ -z "$FEATURE_DESCRIPTION" ]; then
|
|
||||||
echo "Usage: $0 [--json] <feature_description>" >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Function to find the repository root by searching for existing project markers
|
|
||||||
find_repo_root() {
|
|
||||||
local dir="$1"
|
|
||||||
while [ "$dir" != "/" ]; do
|
|
||||||
if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
|
|
||||||
echo "$dir"
|
|
||||||
return 0
|
|
||||||
fi
|
|
||||||
dir="$(dirname "$dir")"
|
|
||||||
done
|
|
||||||
return 1
|
|
||||||
}
|
|
||||||
|
|
||||||
# Resolve repository root. Prefer git information when available, but fall back
|
|
||||||
# to searching for repository markers so the workflow still functions in repositories that
|
|
||||||
# were initialised with --no-git.
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
|
|
||||||
if git rev-parse --show-toplevel >/dev/null 2>&1; then
|
|
||||||
REPO_ROOT=$(git rev-parse --show-toplevel)
|
|
||||||
HAS_GIT=true
|
|
||||||
else
|
|
||||||
REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
|
|
||||||
if [ -z "$REPO_ROOT" ]; then
|
|
||||||
echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
HAS_GIT=false
|
|
||||||
fi
|
|
||||||
|
|
||||||
cd "$REPO_ROOT"
|
|
||||||
|
|
||||||
SPECS_DIR="$REPO_ROOT/specs"
|
|
||||||
mkdir -p "$SPECS_DIR"
|
|
||||||
|
|
||||||
HIGHEST=0
|
|
||||||
if [ -d "$SPECS_DIR" ]; then
|
|
||||||
for dir in "$SPECS_DIR"/*; do
|
|
||||||
[ -d "$dir" ] || continue
|
|
||||||
dirname=$(basename "$dir")
|
|
||||||
number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
|
|
||||||
number=$((10#$number))
|
|
||||||
if [ "$number" -gt "$HIGHEST" ]; then HIGHEST=$number; fi
|
|
||||||
done
|
|
||||||
fi
|
|
||||||
|
|
||||||
NEXT=$((HIGHEST + 1))
|
|
||||||
FEATURE_NUM=$(printf "%03d" "$NEXT")
|
|
||||||
|
|
||||||
BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
|
|
||||||
WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
|
|
||||||
BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
|
|
||||||
|
|
||||||
if [ "$HAS_GIT" = true ]; then
|
|
||||||
git checkout -b "$BRANCH_NAME"
|
|
||||||
else
|
|
||||||
>&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
|
|
||||||
fi
|
|
||||||
|
|
||||||
FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
|
|
||||||
mkdir -p "$FEATURE_DIR"
|
|
||||||
|
|
||||||
TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
|
|
||||||
SPEC_FILE="$FEATURE_DIR/spec.md"
|
|
||||||
if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
|
|
||||||
|
|
||||||
# Set the SPECIFY_FEATURE environment variable for the current session
|
|
||||||
export SPECIFY_FEATURE="$BRANCH_NAME"
|
|
||||||
|
|
||||||
if $JSON_MODE; then
|
|
||||||
printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
|
|
||||||
else
|
|
||||||
echo "BRANCH_NAME: $BRANCH_NAME"
|
|
||||||
echo "SPEC_FILE: $SPEC_FILE"
|
|
||||||
echo "FEATURE_NUM: $FEATURE_NUM"
|
|
||||||
echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
|
|
||||||
fi
|
|
||||||
@@ -1,60 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
# Parse command line arguments
|
|
||||||
JSON_MODE=false
|
|
||||||
ARGS=()
|
|
||||||
|
|
||||||
for arg in "$@"; do
|
|
||||||
case "$arg" in
|
|
||||||
--json)
|
|
||||||
JSON_MODE=true
|
|
||||||
;;
|
|
||||||
--help|-h)
|
|
||||||
echo "Usage: $0 [--json]"
|
|
||||||
echo " --json Output results in JSON format"
|
|
||||||
echo " --help Show this help message"
|
|
||||||
exit 0
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
ARGS+=("$arg")
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
done
|
|
||||||
|
|
||||||
# Get script directory and load common functions
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
source "$SCRIPT_DIR/common.sh"
|
|
||||||
|
|
||||||
# Get all paths and variables from common functions
|
|
||||||
eval $(get_feature_paths)
|
|
||||||
|
|
||||||
# Check if we're on a proper feature branch (only for git repos)
|
|
||||||
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
|
|
||||||
|
|
||||||
# Ensure the feature directory exists
|
|
||||||
mkdir -p "$FEATURE_DIR"
|
|
||||||
|
|
||||||
# Copy plan template if it exists
|
|
||||||
TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
|
|
||||||
if [[ -f "$TEMPLATE" ]]; then
|
|
||||||
cp "$TEMPLATE" "$IMPL_PLAN"
|
|
||||||
echo "Copied plan template to $IMPL_PLAN"
|
|
||||||
else
|
|
||||||
echo "Warning: Plan template not found at $TEMPLATE"
|
|
||||||
# Create a basic plan file if template doesn't exist
|
|
||||||
touch "$IMPL_PLAN"
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Output results
|
|
||||||
if $JSON_MODE; then
|
|
||||||
printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
|
|
||||||
"$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
|
|
||||||
else
|
|
||||||
echo "FEATURE_SPEC: $FEATURE_SPEC"
|
|
||||||
echo "IMPL_PLAN: $IMPL_PLAN"
|
|
||||||
echo "SPECS_DIR: $FEATURE_DIR"
|
|
||||||
echo "BRANCH: $CURRENT_BRANCH"
|
|
||||||
echo "HAS_GIT: $HAS_GIT"
|
|
||||||
fi
|
|
||||||
@@ -1,728 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
|
|
||||||
# Update agent context files with information from plan.md
|
|
||||||
#
|
|
||||||
# This script maintains AI agent context files by parsing feature specifications
|
|
||||||
# and updating agent-specific configuration files with project information.
|
|
||||||
#
|
|
||||||
# MAIN FUNCTIONS:
|
|
||||||
# 1. Environment Validation
|
|
||||||
# - Verifies git repository structure and branch information
|
|
||||||
# - Checks for required plan.md files and templates
|
|
||||||
# - Validates file permissions and accessibility
|
|
||||||
#
|
|
||||||
# 2. Plan Data Extraction
|
|
||||||
# - Parses plan.md files to extract project metadata
|
|
||||||
# - Identifies language/version, frameworks, databases, and project types
|
|
||||||
# - Handles missing or incomplete specification data gracefully
|
|
||||||
#
|
|
||||||
# 3. Agent File Management
|
|
||||||
# - Creates new agent context files from templates when needed
|
|
||||||
# - Updates existing agent files with new project information
|
|
||||||
# - Preserves manual additions and custom configurations
|
|
||||||
# - Supports multiple AI agent formats and directory structures
|
|
||||||
#
|
|
||||||
# 4. Content Generation
|
|
||||||
# - Generates language-specific build/test commands
|
|
||||||
# - Creates appropriate project directory structures
|
|
||||||
# - Updates technology stacks and recent changes sections
|
|
||||||
# - Maintains consistent formatting and timestamps
|
|
||||||
#
|
|
||||||
# 5. Multi-Agent Support
|
|
||||||
# - Handles agent-specific file paths and naming conventions
|
|
||||||
# - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, or Amazon Q Developer CLI
|
|
||||||
# - Can update single agents or all existing agent files
|
|
||||||
# - Creates default Claude file if no agent files exist
|
|
||||||
#
|
|
||||||
# Usage: ./update-agent-context.sh [agent_type]
|
|
||||||
# Agent types: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|q
|
|
||||||
# Leave empty to update all existing agent files
|
|
||||||
|
|
||||||
set -e
|
|
||||||
|
|
||||||
# Enable strict error handling
|
|
||||||
set -u
|
|
||||||
set -o pipefail
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Configuration and Global Variables
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
# Get script directory and load common functions
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
||||||
source "$SCRIPT_DIR/common.sh"
|
|
||||||
|
|
||||||
# Get all paths and variables from common functions
|
|
||||||
eval $(get_feature_paths)
|
|
||||||
|
|
||||||
NEW_PLAN="$IMPL_PLAN" # Alias for compatibility with existing code
|
|
||||||
AGENT_TYPE="${1:-}"
|
|
||||||
|
|
||||||
# Agent-specific file paths
|
|
||||||
CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
|
|
||||||
GEMINI_FILE="$REPO_ROOT/GEMINI.md"
|
|
||||||
COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
|
|
||||||
CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
|
|
||||||
QWEN_FILE="$REPO_ROOT/QWEN.md"
|
|
||||||
AGENTS_FILE="$REPO_ROOT/AGENTS.md"
|
|
||||||
WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
|
|
||||||
KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
|
|
||||||
AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
|
|
||||||
ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
|
|
||||||
Q_FILE="$REPO_ROOT/AGENTS.md"
|
|
||||||
|
|
||||||
# Template file
|
|
||||||
TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
|
|
||||||
|
|
||||||
# Global variables for parsed plan data
|
|
||||||
NEW_LANG=""
|
|
||||||
NEW_FRAMEWORK=""
|
|
||||||
NEW_DB=""
|
|
||||||
NEW_PROJECT_TYPE=""
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Utility Functions
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
log_info() {
|
|
||||||
echo "INFO: $1"
|
|
||||||
}
|
|
||||||
|
|
||||||
log_success() {
|
|
||||||
echo "✓ $1"
|
|
||||||
}
|
|
||||||
|
|
||||||
log_error() {
|
|
||||||
echo "ERROR: $1" >&2
|
|
||||||
}
|
|
||||||
|
|
||||||
log_warning() {
|
|
||||||
echo "WARNING: $1" >&2
|
|
||||||
}
|
|
||||||
|
|
||||||
# Cleanup function for temporary files
|
|
||||||
cleanup() {
|
|
||||||
local exit_code=$?
|
|
||||||
rm -f /tmp/agent_update_*_$$
|
|
||||||
rm -f /tmp/manual_additions_$$
|
|
||||||
exit $exit_code
|
|
||||||
}
|
|
||||||
|
|
||||||
# Set up cleanup trap
|
|
||||||
trap cleanup EXIT INT TERM
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Validation Functions
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
validate_environment() {
|
|
||||||
# Check if we have a current branch/feature (git or non-git)
|
|
||||||
if [[ -z "$CURRENT_BRANCH" ]]; then
|
|
||||||
log_error "Unable to determine current feature"
|
|
||||||
if [[ "$HAS_GIT" == "true" ]]; then
|
|
||||||
log_info "Make sure you're on a feature branch"
|
|
||||||
else
|
|
||||||
log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
|
|
||||||
fi
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Check if plan.md exists
|
|
||||||
if [[ ! -f "$NEW_PLAN" ]]; then
|
|
||||||
log_error "No plan.md found at $NEW_PLAN"
|
|
||||||
log_info "Make sure you're working on a feature with a corresponding spec directory"
|
|
||||||
if [[ "$HAS_GIT" != "true" ]]; then
|
|
||||||
log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
|
|
||||||
fi
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Check if template exists (needed for new files)
|
|
||||||
if [[ ! -f "$TEMPLATE_FILE" ]]; then
|
|
||||||
log_warning "Template file not found at $TEMPLATE_FILE"
|
|
||||||
log_warning "Creating new agent files will fail"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Plan Parsing Functions
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
extract_plan_field() {
|
|
||||||
local field_pattern="$1"
|
|
||||||
local plan_file="$2"
|
|
||||||
|
|
||||||
grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
|
|
||||||
head -1 | \
|
|
||||||
sed "s|^\*\*${field_pattern}\*\*: ||" | \
|
|
||||||
sed 's/^[ \t]*//;s/[ \t]*$//' | \
|
|
||||||
grep -v "NEEDS CLARIFICATION" | \
|
|
||||||
grep -v "^N/A$" || echo ""
|
|
||||||
}
|
|
||||||
|
|
||||||
parse_plan_data() {
|
|
||||||
local plan_file="$1"
|
|
||||||
|
|
||||||
if [[ ! -f "$plan_file" ]]; then
|
|
||||||
log_error "Plan file not found: $plan_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ ! -r "$plan_file" ]]; then
|
|
||||||
log_error "Plan file is not readable: $plan_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
log_info "Parsing plan data from $plan_file"
|
|
||||||
|
|
||||||
NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
|
|
||||||
NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
|
|
||||||
NEW_DB=$(extract_plan_field "Storage" "$plan_file")
|
|
||||||
NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
|
|
||||||
|
|
||||||
# Log what we found
|
|
||||||
if [[ -n "$NEW_LANG" ]]; then
|
|
||||||
log_info "Found language: $NEW_LANG"
|
|
||||||
else
|
|
||||||
log_warning "No language information found in plan"
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -n "$NEW_FRAMEWORK" ]]; then
|
|
||||||
log_info "Found framework: $NEW_FRAMEWORK"
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
|
|
||||||
log_info "Found database: $NEW_DB"
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -n "$NEW_PROJECT_TYPE" ]]; then
|
|
||||||
log_info "Found project type: $NEW_PROJECT_TYPE"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
format_technology_stack() {
|
|
||||||
local lang="$1"
|
|
||||||
local framework="$2"
|
|
||||||
local parts=()
|
|
||||||
|
|
||||||
# Add non-empty parts
|
|
||||||
[[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
|
|
||||||
[[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
|
|
||||||
|
|
||||||
# Join with proper formatting
|
|
||||||
if [[ ${#parts[@]} -eq 0 ]]; then
|
|
||||||
echo ""
|
|
||||||
elif [[ ${#parts[@]} -eq 1 ]]; then
|
|
||||||
echo "${parts[0]}"
|
|
||||||
else
|
|
||||||
# Join multiple parts with " + "
|
|
||||||
local result="${parts[0]}"
|
|
||||||
for ((i=1; i<${#parts[@]}; i++)); do
|
|
||||||
result="$result + ${parts[i]}"
|
|
||||||
done
|
|
||||||
echo "$result"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Template and Content Generation Functions
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
get_project_structure() {
|
|
||||||
local project_type="$1"
|
|
||||||
|
|
||||||
if [[ "$project_type" == *"web"* ]]; then
|
|
||||||
echo "backend/\\nfrontend/\\ntests/"
|
|
||||||
else
|
|
||||||
echo "src/\\ntests/"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
get_commands_for_language() {
|
|
||||||
local lang="$1"
|
|
||||||
|
|
||||||
case "$lang" in
|
|
||||||
*"Python"*)
|
|
||||||
echo "cd src && pytest && ruff check ."
|
|
||||||
;;
|
|
||||||
*"Rust"*)
|
|
||||||
echo "cargo test && cargo clippy"
|
|
||||||
;;
|
|
||||||
*"JavaScript"*|*"TypeScript"*)
|
|
||||||
echo "npm test && npm run lint"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo "# Add commands for $lang"
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
|
|
||||||
get_language_conventions() {
|
|
||||||
local lang="$1"
|
|
||||||
echo "$lang: Follow standard conventions"
|
|
||||||
}
|
|
||||||
|
|
||||||
create_new_agent_file() {
|
|
||||||
local target_file="$1"
|
|
||||||
local temp_file="$2"
|
|
||||||
local project_name="$3"
|
|
||||||
local current_date="$4"
|
|
||||||
|
|
||||||
if [[ ! -f "$TEMPLATE_FILE" ]]; then
|
|
||||||
log_error "Template not found at $TEMPLATE_FILE"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ ! -r "$TEMPLATE_FILE" ]]; then
|
|
||||||
log_error "Template file is not readable: $TEMPLATE_FILE"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
log_info "Creating new agent context file from template..."
|
|
||||||
|
|
||||||
if ! cp "$TEMPLATE_FILE" "$temp_file"; then
|
|
||||||
log_error "Failed to copy template file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Replace template placeholders
|
|
||||||
local project_structure
|
|
||||||
project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
|
|
||||||
|
|
||||||
local commands
|
|
||||||
commands=$(get_commands_for_language "$NEW_LANG")
|
|
||||||
|
|
||||||
local language_conventions
|
|
||||||
language_conventions=$(get_language_conventions "$NEW_LANG")
|
|
||||||
|
|
||||||
# Perform substitutions with error checking using safer approach
|
|
||||||
# Escape special characters for sed by using a different delimiter or escaping
|
|
||||||
local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
|
|
||||||
local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
|
|
||||||
local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
|
|
||||||
|
|
||||||
# Build technology stack and recent change strings conditionally
|
|
||||||
local tech_stack
|
|
||||||
if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
|
|
||||||
tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
|
|
||||||
elif [[ -n "$escaped_lang" ]]; then
|
|
||||||
tech_stack="- $escaped_lang ($escaped_branch)"
|
|
||||||
elif [[ -n "$escaped_framework" ]]; then
|
|
||||||
tech_stack="- $escaped_framework ($escaped_branch)"
|
|
||||||
else
|
|
||||||
tech_stack="- ($escaped_branch)"
|
|
||||||
fi
|
|
||||||
|
|
||||||
local recent_change
|
|
||||||
if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
|
|
||||||
recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
|
|
||||||
elif [[ -n "$escaped_lang" ]]; then
|
|
||||||
recent_change="- $escaped_branch: Added $escaped_lang"
|
|
||||||
elif [[ -n "$escaped_framework" ]]; then
|
|
||||||
recent_change="- $escaped_branch: Added $escaped_framework"
|
|
||||||
else
|
|
||||||
recent_change="- $escaped_branch: Added"
|
|
||||||
fi
|
|
||||||
|
|
||||||
local substitutions=(
|
|
||||||
"s|\[PROJECT NAME\]|$project_name|"
|
|
||||||
"s|\[DATE\]|$current_date|"
|
|
||||||
"s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
|
|
||||||
"s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
|
|
||||||
"s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
|
|
||||||
"s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
|
|
||||||
"s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
|
|
||||||
)
|
|
||||||
|
|
||||||
for substitution in "${substitutions[@]}"; do
|
|
||||||
if ! sed -i.bak -e "$substitution" "$temp_file"; then
|
|
||||||
log_error "Failed to perform substitution: $substitution"
|
|
||||||
rm -f "$temp_file" "$temp_file.bak"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
|
|
||||||
# Convert \n sequences to actual newlines
|
|
||||||
newline=$(printf '\n')
|
|
||||||
sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
|
|
||||||
|
|
||||||
# Clean up backup files
|
|
||||||
rm -f "$temp_file.bak" "$temp_file.bak2"
|
|
||||||
|
|
||||||
return 0
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
update_existing_agent_file() {
|
|
||||||
local target_file="$1"
|
|
||||||
local current_date="$2"
|
|
||||||
|
|
||||||
log_info "Updating existing agent context file..."
|
|
||||||
|
|
||||||
# Use a single temporary file for atomic update
|
|
||||||
local temp_file
|
|
||||||
temp_file=$(mktemp) || {
|
|
||||||
log_error "Failed to create temporary file"
|
|
||||||
return 1
|
|
||||||
}
|
|
||||||
|
|
||||||
# Process the file in one pass
|
|
||||||
local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
|
|
||||||
local new_tech_entries=()
|
|
||||||
local new_change_entry=""
|
|
||||||
|
|
||||||
# Prepare new technology entries
|
|
||||||
if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
|
|
||||||
new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
|
|
||||||
new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Prepare new change entry
|
|
||||||
if [[ -n "$tech_stack" ]]; then
|
|
||||||
new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
|
|
||||||
elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
|
|
||||||
new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Process file line by line
|
|
||||||
local in_tech_section=false
|
|
||||||
local in_changes_section=false
|
|
||||||
local tech_entries_added=false
|
|
||||||
local changes_entries_added=false
|
|
||||||
local existing_changes_count=0
|
|
||||||
|
|
||||||
while IFS= read -r line || [[ -n "$line" ]]; do
|
|
||||||
# Handle Active Technologies section
|
|
||||||
if [[ "$line" == "## Active Technologies" ]]; then
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
in_tech_section=true
|
|
||||||
continue
|
|
||||||
elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
|
|
||||||
# Add new tech entries before closing the section
|
|
||||||
if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
|
|
||||||
printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
|
|
||||||
tech_entries_added=true
|
|
||||||
fi
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
in_tech_section=false
|
|
||||||
continue
|
|
||||||
elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
|
|
||||||
# Add new tech entries before empty line in tech section
|
|
||||||
if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
|
|
||||||
printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
|
|
||||||
tech_entries_added=true
|
|
||||||
fi
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
continue
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Handle Recent Changes section
|
|
||||||
if [[ "$line" == "## Recent Changes" ]]; then
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
# Add new change entry right after the heading
|
|
||||||
if [[ -n "$new_change_entry" ]]; then
|
|
||||||
echo "$new_change_entry" >> "$temp_file"
|
|
||||||
fi
|
|
||||||
in_changes_section=true
|
|
||||||
changes_entries_added=true
|
|
||||||
continue
|
|
||||||
elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
in_changes_section=false
|
|
||||||
continue
|
|
||||||
elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
|
|
||||||
# Keep only first 2 existing changes
|
|
||||||
if [[ $existing_changes_count -lt 2 ]]; then
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
((existing_changes_count++))
|
|
||||||
fi
|
|
||||||
continue
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Update timestamp
|
|
||||||
if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
|
|
||||||
echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
|
|
||||||
else
|
|
||||||
echo "$line" >> "$temp_file"
|
|
||||||
fi
|
|
||||||
done < "$target_file"
|
|
||||||
|
|
||||||
# Post-loop check: if we're still in the Active Technologies section and haven't added new entries
|
|
||||||
if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
|
|
||||||
printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Move temp file to target atomically
|
|
||||||
if ! mv "$temp_file" "$target_file"; then
|
|
||||||
log_error "Failed to update target file"
|
|
||||||
rm -f "$temp_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
return 0
|
|
||||||
}
|
|
||||||
#==============================================================================
|
|
||||||
# Main Agent File Update Function
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
update_agent_file() {
|
|
||||||
local target_file="$1"
|
|
||||||
local agent_name="$2"
|
|
||||||
|
|
||||||
if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
|
|
||||||
log_error "update_agent_file requires target_file and agent_name parameters"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
log_info "Updating $agent_name context file: $target_file"
|
|
||||||
|
|
||||||
local project_name
|
|
||||||
project_name=$(basename "$REPO_ROOT")
|
|
||||||
local current_date
|
|
||||||
current_date=$(date +%Y-%m-%d)
|
|
||||||
|
|
||||||
# Create directory if it doesn't exist
|
|
||||||
local target_dir
|
|
||||||
target_dir=$(dirname "$target_file")
|
|
||||||
if [[ ! -d "$target_dir" ]]; then
|
|
||||||
if ! mkdir -p "$target_dir"; then
|
|
||||||
log_error "Failed to create directory: $target_dir"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ ! -f "$target_file" ]]; then
|
|
||||||
# Create new file from template
|
|
||||||
local temp_file
|
|
||||||
temp_file=$(mktemp) || {
|
|
||||||
log_error "Failed to create temporary file"
|
|
||||||
return 1
|
|
||||||
}
|
|
||||||
|
|
||||||
if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
|
|
||||||
if mv "$temp_file" "$target_file"; then
|
|
||||||
log_success "Created new $agent_name context file"
|
|
||||||
else
|
|
||||||
log_error "Failed to move temporary file to $target_file"
|
|
||||||
rm -f "$temp_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
else
|
|
||||||
log_error "Failed to create new agent file"
|
|
||||||
rm -f "$temp_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
else
|
|
||||||
# Update existing file
|
|
||||||
if [[ ! -r "$target_file" ]]; then
|
|
||||||
log_error "Cannot read existing file: $target_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ ! -w "$target_file" ]]; then
|
|
||||||
log_error "Cannot write to existing file: $target_file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
if update_existing_agent_file "$target_file" "$current_date"; then
|
|
||||||
log_success "Updated existing $agent_name context file"
|
|
||||||
else
|
|
||||||
log_error "Failed to update existing agent file"
|
|
||||||
return 1
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
return 0
|
|
||||||
}
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Agent Selection and Processing
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
update_specific_agent() {
|
|
||||||
local agent_type="$1"
|
|
||||||
|
|
||||||
case "$agent_type" in
|
|
||||||
claude)
|
|
||||||
update_agent_file "$CLAUDE_FILE" "Claude Code"
|
|
||||||
;;
|
|
||||||
gemini)
|
|
||||||
update_agent_file "$GEMINI_FILE" "Gemini CLI"
|
|
||||||
;;
|
|
||||||
copilot)
|
|
||||||
update_agent_file "$COPILOT_FILE" "GitHub Copilot"
|
|
||||||
;;
|
|
||||||
cursor)
|
|
||||||
update_agent_file "$CURSOR_FILE" "Cursor IDE"
|
|
||||||
;;
|
|
||||||
qwen)
|
|
||||||
update_agent_file "$QWEN_FILE" "Qwen Code"
|
|
||||||
;;
|
|
||||||
opencode)
|
|
||||||
update_agent_file "$AGENTS_FILE" "opencode"
|
|
||||||
;;
|
|
||||||
codex)
|
|
||||||
update_agent_file "$AGENTS_FILE" "Codex CLI"
|
|
||||||
;;
|
|
||||||
windsurf)
|
|
||||||
update_agent_file "$WINDSURF_FILE" "Windsurf"
|
|
||||||
;;
|
|
||||||
kilocode)
|
|
||||||
update_agent_file "$KILOCODE_FILE" "Kilo Code"
|
|
||||||
;;
|
|
||||||
auggie)
|
|
||||||
update_agent_file "$AUGGIE_FILE" "Auggie CLI"
|
|
||||||
;;
|
|
||||||
roo)
|
|
||||||
update_agent_file "$ROO_FILE" "Roo Code"
|
|
||||||
;;
|
|
||||||
q)
|
|
||||||
update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
log_error "Unknown agent type '$agent_type'"
|
|
||||||
log_error "Expected: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q"
|
|
||||||
exit 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
}
|
|
||||||
|
|
||||||
update_all_existing_agents() {
|
|
||||||
local found_agent=false
|
|
||||||
|
|
||||||
# Check each possible agent file and update if it exists
|
|
||||||
if [[ -f "$CLAUDE_FILE" ]]; then
|
|
||||||
update_agent_file "$CLAUDE_FILE" "Claude Code"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$GEMINI_FILE" ]]; then
|
|
||||||
update_agent_file "$GEMINI_FILE" "Gemini CLI"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$COPILOT_FILE" ]]; then
|
|
||||||
update_agent_file "$COPILOT_FILE" "GitHub Copilot"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$CURSOR_FILE" ]]; then
|
|
||||||
update_agent_file "$CURSOR_FILE" "Cursor IDE"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$QWEN_FILE" ]]; then
|
|
||||||
update_agent_file "$QWEN_FILE" "Qwen Code"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$AGENTS_FILE" ]]; then
|
|
||||||
update_agent_file "$AGENTS_FILE" "Codex/opencode"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$WINDSURF_FILE" ]]; then
|
|
||||||
update_agent_file "$WINDSURF_FILE" "Windsurf"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$KILOCODE_FILE" ]]; then
|
|
||||||
update_agent_file "$KILOCODE_FILE" "Kilo Code"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$AUGGIE_FILE" ]]; then
|
|
||||||
update_agent_file "$AUGGIE_FILE" "Auggie CLI"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$ROO_FILE" ]]; then
|
|
||||||
update_agent_file "$ROO_FILE" "Roo Code"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -f "$Q_FILE" ]]; then
|
|
||||||
update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
|
|
||||||
found_agent=true
|
|
||||||
fi
|
|
||||||
|
|
||||||
# If no agent files exist, create a default Claude file
|
|
||||||
if [[ "$found_agent" == false ]]; then
|
|
||||||
log_info "No existing agent files found, creating default Claude file..."
|
|
||||||
update_agent_file "$CLAUDE_FILE" "Claude Code"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
print_summary() {
|
|
||||||
echo
|
|
||||||
log_info "Summary of changes:"
|
|
||||||
|
|
||||||
if [[ -n "$NEW_LANG" ]]; then
|
|
||||||
echo " - Added language: $NEW_LANG"
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -n "$NEW_FRAMEWORK" ]]; then
|
|
||||||
echo " - Added framework: $NEW_FRAMEWORK"
|
|
||||||
fi
|
|
||||||
|
|
||||||
if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
|
|
||||||
echo " - Added database: $NEW_DB"
|
|
||||||
fi
|
|
||||||
|
|
||||||
echo
|
|
||||||
log_info "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|q]"
|
|
||||||
}
|
|
||||||
|
|
||||||
#==============================================================================
|
|
||||||
# Main Execution
|
|
||||||
#==============================================================================
|
|
||||||
|
|
||||||
main() {
|
|
||||||
# Validate environment before proceeding
|
|
||||||
validate_environment
|
|
||||||
|
|
||||||
log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
|
|
||||||
|
|
||||||
# Parse the plan file to extract project information
|
|
||||||
if ! parse_plan_data "$NEW_PLAN"; then
|
|
||||||
log_error "Failed to parse plan data"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Process based on agent type argument
|
|
||||||
local success=true
|
|
||||||
|
|
||||||
if [[ -z "$AGENT_TYPE" ]]; then
|
|
||||||
# No specific agent provided - update all existing agent files
|
|
||||||
log_info "No agent specified, updating all existing agent files..."
|
|
||||||
if ! update_all_existing_agents; then
|
|
||||||
success=false
|
|
||||||
fi
|
|
||||||
else
|
|
||||||
# Specific agent provided - update only that agent
|
|
||||||
log_info "Updating specific agent: $AGENT_TYPE"
|
|
||||||
if ! update_specific_agent "$AGENT_TYPE"; then
|
|
||||||
success=false
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Print summary
|
|
||||||
print_summary
|
|
||||||
|
|
||||||
if [[ "$success" == true ]]; then
|
|
||||||
log_success "Agent context update completed successfully"
|
|
||||||
exit 0
|
|
||||||
else
|
|
||||||
log_error "Agent context update completed with errors"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
# Execute main function if script is run directly
|
|
||||||
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
|
|
||||||
main "$@"
|
|
||||||
fi
|
|
||||||
@@ -1,23 +0,0 @@
|
|||||||
# [PROJECT NAME] Development Guidelines
|
|
||||||
|
|
||||||
Auto-generated from all feature plans. Last updated: [DATE]
|
|
||||||
|
|
||||||
## Active Technologies
|
|
||||||
[EXTRACTED FROM ALL PLAN.MD FILES]
|
|
||||||
|
|
||||||
## Project Structure
|
|
||||||
```
|
|
||||||
[ACTUAL STRUCTURE FROM PLANS]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Commands
|
|
||||||
[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
|
|
||||||
|
|
||||||
## Code Style
|
|
||||||
[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
|
|
||||||
|
|
||||||
## Recent Changes
|
|
||||||
[LAST 3 FEATURES AND WHAT THEY ADDED]
|
|
||||||
|
|
||||||
<!-- MANUAL ADDITIONS START -->
|
|
||||||
<!-- MANUAL ADDITIONS END -->
|
|
||||||
@@ -1,40 +0,0 @@
|
|||||||
# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
|
|
||||||
|
|
||||||
**Purpose**: [Brief description of what this checklist covers]
|
|
||||||
**Created**: [DATE]
|
|
||||||
**Feature**: [Link to spec.md or relevant documentation]
|
|
||||||
|
|
||||||
**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
|
|
||||||
|
|
||||||
<!--
|
|
||||||
============================================================================
|
|
||||||
IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
|
|
||||||
|
|
||||||
The /speckit.checklist command MUST replace these with actual items based on:
|
|
||||||
- User's specific checklist request
|
|
||||||
- Feature requirements from spec.md
|
|
||||||
- Technical context from plan.md
|
|
||||||
- Implementation details from tasks.md
|
|
||||||
|
|
||||||
DO NOT keep these sample items in the generated checklist file.
|
|
||||||
============================================================================
|
|
||||||
-->
|
|
||||||
|
|
||||||
## [Category 1]
|
|
||||||
|
|
||||||
- [ ] CHK001 First checklist item with clear action
|
|
||||||
- [ ] CHK002 Second checklist item
|
|
||||||
- [ ] CHK003 Third checklist item
|
|
||||||
|
|
||||||
## [Category 2]
|
|
||||||
|
|
||||||
- [ ] CHK004 Another category item
|
|
||||||
- [ ] CHK005 Item with specific criteria
|
|
||||||
- [ ] CHK006 Final item in this category
|
|
||||||
|
|
||||||
## Notes
|
|
||||||
|
|
||||||
- Check items off as completed: `[x]`
|
|
||||||
- Add comments or findings inline
|
|
||||||
- Link to relevant resources or documentation
|
|
||||||
- Items are numbered sequentially for easy reference
|
|
||||||
@@ -1,104 +0,0 @@
|
|||||||
# Implementation Plan: [FEATURE]
|
|
||||||
|
|
||||||
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
|
|
||||||
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
|
|
||||||
|
|
||||||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
|
|
||||||
|
|
||||||
## Summary
|
|
||||||
|
|
||||||
[Extract from feature spec: primary requirement + technical approach from research]
|
|
||||||
|
|
||||||
## Technical Context
|
|
||||||
|
|
||||||
<!--
|
|
||||||
ACTION REQUIRED: Replace the content in this section with the technical details
|
|
||||||
for the project. The structure here is presented in advisory capacity to guide
|
|
||||||
the iteration process.
|
|
||||||
-->
|
|
||||||
|
|
||||||
**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
|
|
||||||
**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
|
|
||||||
**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
|
|
||||||
**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
|
|
||||||
**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
|
|
||||||
**Project Type**: [single/web/mobile - determines source structure]
|
|
||||||
**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
|
|
||||||
**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
|
|
||||||
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
|
|
||||||
|
|
||||||
## Constitution Check
|
|
||||||
|
|
||||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
||||||
|
|
||||||
[Gates determined based on constitution file]
|
|
||||||
|
|
||||||
## Project Structure
|
|
||||||
|
|
||||||
### Documentation (this feature)
|
|
||||||
|
|
||||||
```
|
|
||||||
specs/[###-feature]/
|
|
||||||
├── plan.md # This file (/speckit.plan command output)
|
|
||||||
├── research.md # Phase 0 output (/speckit.plan command)
|
|
||||||
├── data-model.md # Phase 1 output (/speckit.plan command)
|
|
||||||
├── quickstart.md # Phase 1 output (/speckit.plan command)
|
|
||||||
├── contracts/ # Phase 1 output (/speckit.plan command)
|
|
||||||
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Source Code (repository root)
|
|
||||||
<!--
|
|
||||||
ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
|
|
||||||
for this feature. Delete unused options and expand the chosen structure with
|
|
||||||
real paths (e.g., apps/admin, packages/something). The delivered plan must
|
|
||||||
not include Option labels.
|
|
||||||
-->
|
|
||||||
|
|
||||||
```
|
|
||||||
# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
|
|
||||||
src/
|
|
||||||
├── models/
|
|
||||||
├── services/
|
|
||||||
├── cli/
|
|
||||||
└── lib/
|
|
||||||
|
|
||||||
tests/
|
|
||||||
├── contract/
|
|
||||||
├── integration/
|
|
||||||
└── unit/
|
|
||||||
|
|
||||||
# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
|
|
||||||
backend/
|
|
||||||
├── src/
|
|
||||||
│ ├── models/
|
|
||||||
│ ├── services/
|
|
||||||
│ └── api/
|
|
||||||
└── tests/
|
|
||||||
|
|
||||||
frontend/
|
|
||||||
├── src/
|
|
||||||
│ ├── components/
|
|
||||||
│ ├── pages/
|
|
||||||
│ └── services/
|
|
||||||
└── tests/
|
|
||||||
|
|
||||||
# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
|
|
||||||
api/
|
|
||||||
└── [same as backend above]
|
|
||||||
|
|
||||||
ios/ or android/
|
|
||||||
└── [platform-specific structure: feature modules, UI flows, platform tests]
|
|
||||||
```
|
|
||||||
|
|
||||||
**Structure Decision**: [Document the selected structure and reference the real
|
|
||||||
directories captured above]
|
|
||||||
|
|
||||||
## Complexity Tracking
|
|
||||||
|
|
||||||
*Fill ONLY if Constitution Check has violations that must be justified*
|
|
||||||
|
|
||||||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
||||||
|-----------|------------|-------------------------------------|
|
|
||||||
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
|
|
||||||
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
|
|
||||||
@@ -1,115 +0,0 @@
|
|||||||
# Feature Specification: [FEATURE NAME]
|
|
||||||
|
|
||||||
**Feature Branch**: `[###-feature-name]`
|
|
||||||
**Created**: [DATE]
|
|
||||||
**Status**: Draft
|
|
||||||
**Input**: User description: "$ARGUMENTS"
|
|
||||||
|
|
||||||
## User Scenarios & Testing *(mandatory)*
|
|
||||||
|
|
||||||
<!--
|
|
||||||
IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
|
|
||||||
Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
|
|
||||||
you should still have a viable MVP (Minimum Viable Product) that delivers value.
|
|
||||||
|
|
||||||
Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
|
|
||||||
Think of each story as a standalone slice of functionality that can be:
|
|
||||||
- Developed independently
|
|
||||||
- Tested independently
|
|
||||||
- Deployed independently
|
|
||||||
- Demonstrated to users independently
|
|
||||||
-->
|
|
||||||
|
|
||||||
### User Story 1 - [Brief Title] (Priority: P1)
|
|
||||||
|
|
||||||
[Describe this user journey in plain language]
|
|
||||||
|
|
||||||
**Why this priority**: [Explain the value and why it has this priority level]
|
|
||||||
|
|
||||||
**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
|
|
||||||
|
|
||||||
**Acceptance Scenarios**:
|
|
||||||
|
|
||||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
||||||
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### User Story 2 - [Brief Title] (Priority: P2)
|
|
||||||
|
|
||||||
[Describe this user journey in plain language]
|
|
||||||
|
|
||||||
**Why this priority**: [Explain the value and why it has this priority level]
|
|
||||||
|
|
||||||
**Independent Test**: [Describe how this can be tested independently]
|
|
||||||
|
|
||||||
**Acceptance Scenarios**:
|
|
||||||
|
|
||||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### User Story 3 - [Brief Title] (Priority: P3)
|
|
||||||
|
|
||||||
[Describe this user journey in plain language]
|
|
||||||
|
|
||||||
**Why this priority**: [Explain the value and why it has this priority level]
|
|
||||||
|
|
||||||
**Independent Test**: [Describe how this can be tested independently]
|
|
||||||
|
|
||||||
**Acceptance Scenarios**:
|
|
||||||
|
|
||||||
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[Add more user stories as needed, each with an assigned priority]
|
|
||||||
|
|
||||||
### Edge Cases
|
|
||||||
|
|
||||||
<!--
|
|
||||||
ACTION REQUIRED: The content in this section represents placeholders.
|
|
||||||
Fill them out with the right edge cases.
|
|
||||||
-->
|
|
||||||
|
|
||||||
- What happens when [boundary condition]?
|
|
||||||
- How does system handle [error scenario]?
|
|
||||||
|
|
||||||
## Requirements *(mandatory)*
|
|
||||||
|
|
||||||
<!--
|
|
||||||
ACTION REQUIRED: The content in this section represents placeholders.
|
|
||||||
Fill them out with the right functional requirements.
|
|
||||||
-->
|
|
||||||
|
|
||||||
### Functional Requirements
|
|
||||||
|
|
||||||
- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
|
|
||||||
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
|
|
||||||
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
|
|
||||||
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
|
|
||||||
- **FR-005**: System MUST [behavior, e.g., "log all security events"]
|
|
||||||
|
|
||||||
*Example of marking unclear requirements:*
|
|
||||||
|
|
||||||
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
|
|
||||||
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
|
|
||||||
|
|
||||||
### Key Entities *(include if feature involves data)*
|
|
||||||
|
|
||||||
- **[Entity 1]**: [What it represents, key attributes without implementation]
|
|
||||||
- **[Entity 2]**: [What it represents, relationships to other entities]
|
|
||||||
|
|
||||||
## Success Criteria *(mandatory)*
|
|
||||||
|
|
||||||
<!--
|
|
||||||
ACTION REQUIRED: Define measurable success criteria.
|
|
||||||
These must be technology-agnostic and measurable.
|
|
||||||
-->
|
|
||||||
|
|
||||||
### Measurable Outcomes
|
|
||||||
|
|
||||||
- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
|
|
||||||
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
|
|
||||||
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
|
|
||||||
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
|
|
||||||
@@ -1,250 +0,0 @@
|
|||||||
---
|
|
||||||
description: "Task list template for feature implementation"
|
|
||||||
---
|
|
||||||
|
|
||||||
# Tasks: [FEATURE NAME]
|
|
||||||
|
|
||||||
**Input**: Design documents from `/specs/[###-feature-name]/`
|
|
||||||
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
|
|
||||||
|
|
||||||
**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
|
|
||||||
|
|
||||||
**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
|
|
||||||
- **Single project**: `src/`, `tests/` at repository root
|
|
||||||
- **Web app**: `backend/src/`, `frontend/src/`
|
|
||||||
- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
|
|
||||||
- Paths shown below assume single project - adjust based on plan.md structure
|
|
||||||
|
|
||||||
<!--
|
|
||||||
============================================================================
|
|
||||||
IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
|
|
||||||
|
|
||||||
The /speckit.tasks command MUST replace these with actual tasks based on:
|
|
||||||
- User stories from spec.md (with their priorities P1, P2, P3...)
|
|
||||||
- Feature requirements from plan.md
|
|
||||||
- Entities from data-model.md
|
|
||||||
- Endpoints from contracts/
|
|
||||||
|
|
||||||
Tasks MUST be organized by user story so each story can be:
|
|
||||||
- Implemented independently
|
|
||||||
- Tested independently
|
|
||||||
- Delivered as an MVP increment
|
|
||||||
|
|
||||||
DO NOT keep these sample tasks in the generated tasks.md file.
|
|
||||||
============================================================================
|
|
||||||
-->
|
|
||||||
|
|
||||||
## Phase 1: Setup (Shared Infrastructure)
|
|
||||||
|
|
||||||
**Purpose**: Project initialization and basic structure
|
|
||||||
|
|
||||||
- [ ] T001 Create project structure per implementation plan
|
|
||||||
- [ ] T002 Initialize [language] project with [framework] dependencies
|
|
||||||
- [ ] T003 [P] Configure linting and formatting tools
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
Examples of foundational tasks (adjust based on your project):
|
|
||||||
|
|
||||||
- [ ] T004 Setup database schema and migrations framework
|
|
||||||
- [ ] T005 [P] Implement authentication/authorization framework
|
|
||||||
- [ ] T006 [P] Setup API routing and middleware structure
|
|
||||||
- [ ] T007 Create base models/entities that all stories depend on
|
|
||||||
- [ ] T008 Configure error handling and logging infrastructure
|
|
||||||
- [ ] T009 Setup environment configuration management
|
|
||||||
|
|
||||||
**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
|
|
||||||
|
|
||||||
**Goal**: [Brief description of what this story delivers]
|
|
||||||
|
|
||||||
**Independent Test**: [How to verify this story works on its own]
|
|
||||||
|
|
||||||
### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
|
|
||||||
|
|
||||||
**NOTE: Write these tests FIRST, ensure they FAIL before implementation**
|
|
||||||
|
|
||||||
- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
|
|
||||||
- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
|
|
||||||
|
|
||||||
### Implementation for User Story 1
|
|
||||||
|
|
||||||
- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
|
|
||||||
- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
|
|
||||||
- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
|
|
||||||
- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
|
|
||||||
- [ ] T016 [US1] Add validation and error handling
|
|
||||||
- [ ] T017 [US1] Add logging for user story 1 operations
|
|
||||||
|
|
||||||
**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 4: User Story 2 - [Title] (Priority: P2)
|
|
||||||
|
|
||||||
**Goal**: [Brief description of what this story delivers]
|
|
||||||
|
|
||||||
**Independent Test**: [How to verify this story works on its own]
|
|
||||||
|
|
||||||
### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
|
|
||||||
|
|
||||||
- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
|
|
||||||
- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
|
|
||||||
|
|
||||||
### Implementation for User Story 2
|
|
||||||
|
|
||||||
- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
|
|
||||||
- [ ] T021 [US2] Implement [Service] in src/services/[service].py
|
|
||||||
- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
|
|
||||||
- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
|
|
||||||
|
|
||||||
**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 5: User Story 3 - [Title] (Priority: P3)
|
|
||||||
|
|
||||||
**Goal**: [Brief description of what this story delivers]
|
|
||||||
|
|
||||||
**Independent Test**: [How to verify this story works on its own]
|
|
||||||
|
|
||||||
### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
|
|
||||||
|
|
||||||
- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
|
|
||||||
- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
|
|
||||||
|
|
||||||
### Implementation for User Story 3
|
|
||||||
|
|
||||||
- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
|
|
||||||
- [ ] T027 [US3] Implement [Service] in src/services/[service].py
|
|
||||||
- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
|
|
||||||
|
|
||||||
**Checkpoint**: All user stories should now be independently functional
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[Add more user story phases as needed, following the same pattern]
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase N: Polish & Cross-Cutting Concerns
|
|
||||||
|
|
||||||
**Purpose**: Improvements that affect multiple user stories
|
|
||||||
|
|
||||||
- [ ] TXXX [P] Documentation updates in docs/
|
|
||||||
- [ ] TXXX Code cleanup and refactoring
|
|
||||||
- [ ] TXXX Performance optimization across all stories
|
|
||||||
- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
|
|
||||||
- [ ] TXXX Security hardening
|
|
||||||
- [ ] TXXX Run quickstart.md validation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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+)**: All depend on Foundational phase completion
|
|
||||||
- User stories can then proceed in parallel (if staffed)
|
|
||||||
- Or sequentially in priority order (P1 → P2 → P3)
|
|
||||||
- **Polish (Final Phase)**: Depends on all desired user stories being complete
|
|
||||||
|
|
||||||
### User Story Dependencies
|
|
||||||
|
|
||||||
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
|
|
||||||
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
|
|
||||||
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
|
|
||||||
|
|
||||||
### Within Each User Story
|
|
||||||
|
|
||||||
- Tests (if included) MUST be written and FAIL before implementation
|
|
||||||
- Models before services
|
|
||||||
- Services before endpoints
|
|
||||||
- Core implementation before integration
|
|
||||||
- Story complete before moving to next priority
|
|
||||||
|
|
||||||
### Parallel Opportunities
|
|
||||||
|
|
||||||
- All Setup tasks marked [P] can run in parallel
|
|
||||||
- All Foundational tasks marked [P] can run in parallel (within Phase 2)
|
|
||||||
- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
|
|
||||||
- All tests for a user story marked [P] can run in parallel
|
|
||||||
- Models within a story marked [P] can run in parallel
|
|
||||||
- Different user stories can be worked on in parallel by different team members
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Parallel Example: User Story 1
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Launch all tests for User Story 1 together (if tests requested):
|
|
||||||
Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
|
|
||||||
Task: "Integration test for [user journey] in tests/integration/test_[name].py"
|
|
||||||
|
|
||||||
# Launch all models for User Story 1 together:
|
|
||||||
Task: "Create [Entity1] model in src/models/[entity1].py"
|
|
||||||
Task: "Create [Entity2] model in src/models/[entity2].py"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation Strategy
|
|
||||||
|
|
||||||
### MVP First (User Story 1 Only)
|
|
||||||
|
|
||||||
1. Complete Phase 1: Setup
|
|
||||||
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
|
|
||||||
3. Complete Phase 3: User Story 1
|
|
||||||
4. **STOP and VALIDATE**: Test User Story 1 independently
|
|
||||||
5. Deploy/demo if ready
|
|
||||||
|
|
||||||
### Incremental Delivery
|
|
||||||
|
|
||||||
1. Complete Setup + Foundational → Foundation ready
|
|
||||||
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
|
|
||||||
3. Add User Story 2 → Test independently → Deploy/Demo
|
|
||||||
4. Add User Story 3 → Test independently → Deploy/Demo
|
|
||||||
5. Each story adds value without breaking previous stories
|
|
||||||
|
|
||||||
### Parallel Team Strategy
|
|
||||||
|
|
||||||
With multiple developers:
|
|
||||||
|
|
||||||
1. Team completes Setup + Foundational together
|
|
||||||
2. Once Foundational is done:
|
|
||||||
- Developer A: User Story 1
|
|
||||||
- Developer B: User Story 2
|
|
||||||
- Developer C: User Story 3
|
|
||||||
3. Stories complete and integrate independently
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
|
||||||
- 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
|
|
||||||
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user