From 6e9b6ad9d104e0494d5dc63e43221421649f3eaf Mon Sep 17 00:00:00 2001 From: James Rich Date: Sat, 9 May 2026 20:36:23 -0500 Subject: [PATCH 1/7] chore: add spec-kit configuration and project-tailored templates - Initialize .specify/ with constitution (v1.0.0), customized templates (spec, plan, tasks, checklist), extensions (git, brownfield), and workflow registry - Add speckit agent definitions (.github/agents/speckit.*.agent.md) - Add speckit prompt definitions (.github/prompts/speckit.*.prompt.md) - Add plan-integration marker to copilot-instructions.md - Templates reference actual module structure, Gradle tasks, source paths, ADRs, and KMP conventions - Validated against codebase: all paths, commands, and dependencies verified accurate Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: James Rich --- .github/agents/speckit.analyze.agent.md | 249 +++++++ .../speckit.brownfield.bootstrap.agent.md | 113 +++ .../speckit.brownfield.migrate.agent.md | 128 ++++ .../agents/speckit.brownfield.scan.agent.md | 121 ++++ .../speckit.brownfield.validate.agent.md | 94 +++ .github/agents/speckit.checklist.agent.md | 361 ++++++++++ .github/agents/speckit.clarify.agent.md | 247 +++++++ .github/agents/speckit.constitution.agent.md | 150 ++++ .github/agents/speckit.git.commit.agent.md | 51 ++ .github/agents/speckit.git.feature.agent.md | 70 ++ .../agents/speckit.git.initialize.agent.md | 52 ++ .github/agents/speckit.git.remote.agent.md | 48 ++ .github/agents/speckit.git.validate.agent.md | 52 ++ .github/agents/speckit.implement.agent.md | 199 ++++++ .github/agents/speckit.plan.agent.md | 149 ++++ .github/agents/speckit.specify.agent.md | 327 +++++++++ .github/agents/speckit.tasks.agent.md | 200 ++++++ .github/agents/speckit.taskstoissues.agent.md | 96 +++ .github/copilot-instructions.md | 5 + .github/prompts/speckit.analyze.prompt.md | 3 + .../speckit.brownfield.bootstrap.prompt.md | 3 + .../speckit.brownfield.migrate.prompt.md | 3 + .../prompts/speckit.brownfield.scan.prompt.md | 3 + .../speckit.brownfield.validate.prompt.md | 3 + .github/prompts/speckit.checklist.prompt.md | 3 + .github/prompts/speckit.clarify.prompt.md | 3 + .../prompts/speckit.constitution.prompt.md | 3 + .github/prompts/speckit.git.commit.prompt.md | 3 + .github/prompts/speckit.git.feature.prompt.md | 3 + .../prompts/speckit.git.initialize.prompt.md | 3 + .github/prompts/speckit.git.remote.prompt.md | 3 + .../prompts/speckit.git.validate.prompt.md | 3 + .github/prompts/speckit.implement.prompt.md | 3 + .github/prompts/speckit.plan.prompt.md | 3 + .github/prompts/speckit.specify.prompt.md | 3 + .github/prompts/speckit.tasks.prompt.md | 3 + .../prompts/speckit.taskstoissues.prompt.md | 3 + .specify/extensions.yml | 156 +++++ .specify/extensions/.registry | 40 ++ .specify/extensions/brownfield/CHANGELOG.md | 11 + .specify/extensions/brownfield/LICENSE | 21 + .specify/extensions/brownfield/README.md | 148 ++++ .../commands/speckit.brownfield.bootstrap.md | 110 +++ .../commands/speckit.brownfield.migrate.md | 124 ++++ .../commands/speckit.brownfield.scan.md | 117 ++++ .../commands/speckit.brownfield.validate.md | 91 +++ .specify/extensions/brownfield/extension.yml | 42 ++ .specify/extensions/git/README.md | 100 +++ .../git/commands/speckit.git.commit.md | 48 ++ .../git/commands/speckit.git.feature.md | 67 ++ .../git/commands/speckit.git.initialize.md | 49 ++ .../git/commands/speckit.git.remote.md | 45 ++ .../git/commands/speckit.git.validate.md | 49 ++ .specify/extensions/git/config-template.yml | 62 ++ .specify/extensions/git/extension.yml | 140 ++++ .specify/extensions/git/git-config.yml | 62 ++ .../git/scripts/bash/auto-commit.sh | 140 ++++ .../git/scripts/bash/create-new-feature.sh | 453 ++++++++++++ .../extensions/git/scripts/bash/git-common.sh | 54 ++ .../git/scripts/bash/initialize-repo.sh | 54 ++ .../git/scripts/powershell/auto-commit.ps1 | 169 +++++ .../scripts/powershell/create-new-feature.ps1 | 403 +++++++++++ .../git/scripts/powershell/git-common.ps1 | 51 ++ .../scripts/powershell/initialize-repo.ps1 | 69 ++ .specify/init-options.json | 9 + .specify/integration.json | 15 + .specify/integrations/copilot.manifest.json | 26 + .specify/integrations/speckit.manifest.json | 17 + .specify/memory/constitution.md | 202 ++++++ .specify/scripts/bash/check-prerequisites.sh | 190 ++++++ .specify/scripts/bash/common.sh | 645 ++++++++++++++++++ .specify/scripts/bash/create-new-feature.sh | 413 +++++++++++ .specify/scripts/bash/setup-plan.sh | 75 ++ .specify/scripts/bash/setup-tasks.sh | 96 +++ .specify/templates/checklist-template.md | 99 +++ .specify/templates/constitution-template.md | 50 ++ .specify/templates/plan-template.md | 115 ++++ .specify/templates/spec-template.md | 181 +++++ .specify/templates/tasks-template.md | 223 ++++++ .specify/workflows/speckit/workflow.yml | 63 ++ .specify/workflows/workflow-registry.json | 13 + 81 files changed, 8073 insertions(+) create mode 100644 .github/agents/speckit.analyze.agent.md create mode 100644 .github/agents/speckit.brownfield.bootstrap.agent.md create mode 100644 .github/agents/speckit.brownfield.migrate.agent.md create mode 100644 .github/agents/speckit.brownfield.scan.agent.md create mode 100644 .github/agents/speckit.brownfield.validate.agent.md create mode 100644 .github/agents/speckit.checklist.agent.md create mode 100644 .github/agents/speckit.clarify.agent.md create mode 100644 .github/agents/speckit.constitution.agent.md create mode 100644 .github/agents/speckit.git.commit.agent.md create mode 100644 .github/agents/speckit.git.feature.agent.md create mode 100644 .github/agents/speckit.git.initialize.agent.md create mode 100644 .github/agents/speckit.git.remote.agent.md create mode 100644 .github/agents/speckit.git.validate.agent.md create mode 100644 .github/agents/speckit.implement.agent.md create mode 100644 .github/agents/speckit.plan.agent.md create mode 100644 .github/agents/speckit.specify.agent.md create mode 100644 .github/agents/speckit.tasks.agent.md create mode 100644 .github/agents/speckit.taskstoissues.agent.md create mode 100644 .github/prompts/speckit.analyze.prompt.md create mode 100644 .github/prompts/speckit.brownfield.bootstrap.prompt.md create mode 100644 .github/prompts/speckit.brownfield.migrate.prompt.md create mode 100644 .github/prompts/speckit.brownfield.scan.prompt.md create mode 100644 .github/prompts/speckit.brownfield.validate.prompt.md create mode 100644 .github/prompts/speckit.checklist.prompt.md create mode 100644 .github/prompts/speckit.clarify.prompt.md create mode 100644 .github/prompts/speckit.constitution.prompt.md create mode 100644 .github/prompts/speckit.git.commit.prompt.md create mode 100644 .github/prompts/speckit.git.feature.prompt.md create mode 100644 .github/prompts/speckit.git.initialize.prompt.md create mode 100644 .github/prompts/speckit.git.remote.prompt.md create mode 100644 .github/prompts/speckit.git.validate.prompt.md create mode 100644 .github/prompts/speckit.implement.prompt.md create mode 100644 .github/prompts/speckit.plan.prompt.md create mode 100644 .github/prompts/speckit.specify.prompt.md create mode 100644 .github/prompts/speckit.tasks.prompt.md create mode 100644 .github/prompts/speckit.taskstoissues.prompt.md create mode 100644 .specify/extensions.yml create mode 100644 .specify/extensions/.registry create mode 100644 .specify/extensions/brownfield/CHANGELOG.md create mode 100644 .specify/extensions/brownfield/LICENSE create mode 100644 .specify/extensions/brownfield/README.md create mode 100644 .specify/extensions/brownfield/commands/speckit.brownfield.bootstrap.md create mode 100644 .specify/extensions/brownfield/commands/speckit.brownfield.migrate.md create mode 100644 .specify/extensions/brownfield/commands/speckit.brownfield.scan.md create mode 100644 .specify/extensions/brownfield/commands/speckit.brownfield.validate.md create mode 100644 .specify/extensions/brownfield/extension.yml create mode 100644 .specify/extensions/git/README.md create mode 100644 .specify/extensions/git/commands/speckit.git.commit.md create mode 100644 .specify/extensions/git/commands/speckit.git.feature.md create mode 100644 .specify/extensions/git/commands/speckit.git.initialize.md create mode 100644 .specify/extensions/git/commands/speckit.git.remote.md create mode 100644 .specify/extensions/git/commands/speckit.git.validate.md create mode 100644 .specify/extensions/git/config-template.yml create mode 100644 .specify/extensions/git/extension.yml create mode 100644 .specify/extensions/git/git-config.yml create mode 100755 .specify/extensions/git/scripts/bash/auto-commit.sh create mode 100755 .specify/extensions/git/scripts/bash/create-new-feature.sh create mode 100755 .specify/extensions/git/scripts/bash/git-common.sh create mode 100755 .specify/extensions/git/scripts/bash/initialize-repo.sh create mode 100644 .specify/extensions/git/scripts/powershell/auto-commit.ps1 create mode 100644 .specify/extensions/git/scripts/powershell/create-new-feature.ps1 create mode 100644 .specify/extensions/git/scripts/powershell/git-common.ps1 create mode 100644 .specify/extensions/git/scripts/powershell/initialize-repo.ps1 create mode 100644 .specify/init-options.json create mode 100644 .specify/integration.json create mode 100644 .specify/integrations/copilot.manifest.json create mode 100644 .specify/integrations/speckit.manifest.json create mode 100644 .specify/memory/constitution.md create mode 100755 .specify/scripts/bash/check-prerequisites.sh create mode 100755 .specify/scripts/bash/common.sh create mode 100755 .specify/scripts/bash/create-new-feature.sh create mode 100755 .specify/scripts/bash/setup-plan.sh create mode 100755 .specify/scripts/bash/setup-tasks.sh create mode 100644 .specify/templates/checklist-template.md create mode 100644 .specify/templates/constitution-template.md create mode 100644 .specify/templates/plan-template.md create mode 100644 .specify/templates/spec-template.md create mode 100644 .specify/templates/tasks-template.md create mode 100644 .specify/workflows/speckit/workflow.yml create mode 100644 .specify/workflows/workflow-registry.json diff --git a/.github/agents/speckit.analyze.agent.md b/.github/agents/speckit.analyze.agent.md new file mode 100644 index 0000000..1237e10 --- /dev/null +++ b/.github/agents/speckit.analyze.agent.md @@ -0,0 +1,249 @@ +--- +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). + +## Pre-Execution Checks + +**Check for extension hooks (before analysis)**: +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_analyze` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Goal. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently + +## 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 `/speckit.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 `/speckit.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). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Overview/Context +- Functional Requirements +- Success Criteria (measurable outcomes — e.g., performance, security, availability, user success, business impact) +- 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**: For each Functional Requirement (FR-###) and Success Criterion (SC-###), record a stable key. Use the explicit FR-/SC- identifier as the primary key when present, and optionally also derive an imperative-phrase slug for readability (e.g., "User can upload file" → `user-can-upload-file`). Include only Success Criteria items that require buildable work (e.g., load-testing infrastructure, security audit tooling), and exclude post-launch outcome metrics and business KPIs (e.g., "Reduce support tickets by 50%"). +- **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, ???, ``, 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 +- Success Criteria requiring buildable work (performance, security, availability) not reflected in tasks + +#### 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 `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.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.) + +### 9. Check for extension hooks + +After reporting, check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.after_analyze` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently + +## 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 + +$ARGUMENTS diff --git a/.github/agents/speckit.brownfield.bootstrap.agent.md b/.github/agents/speckit.brownfield.bootstrap.agent.md new file mode 100644 index 0000000..f5949cb --- /dev/null +++ b/.github/agents/speckit.brownfield.bootstrap.agent.md @@ -0,0 +1,113 @@ +--- +description: Generate spec-kit configuration tailored to the existing codebase +--- + + + + +# Bootstrap Spec-Kit + +Generate a customized spec-kit configuration for an existing codebase. Uses the project profile from `/speckit.brownfield.scan` (or performs a scan if none exists) to create a constitution, templates, and agent configuration that match the project's actual architecture, tech stack, and conventions. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). The user may specify preferences (e.g., "strict TDD", "minimal constitution"), a target directory for a monorepo module, or request specific template customizations. + +## Prerequisites + +1. Verify the current directory is a git repository +2. Verify a spec-kit project exists by checking for `.specify/` directory (run `specify init` first if missing) +3. Check if a project profile exists from a previous scan — if not, run a scan first + +## Outline + +1. **Load or generate project profile**: Check if `/speckit.brownfield.scan` has been run: + - If a project profile exists, use it + - If not, perform an inline scan to gather tech stack, architecture, and conventions + - Confirm the profile with the user before proceeding + +2. **Generate constitution**: Create `.specify/memory/constitution.md` tailored to the project: + + The constitution **MUST** include: + - **Project identity**: Name, purpose, primary language(s), architecture pattern + - **Code boundaries**: Which directories contain which types of code (e.g., "frontend code lives in `client/`, backend in `server/`") + - **Naming conventions**: File naming, variable naming, branch naming as detected + - **Testing requirements**: Test framework, test location, coverage expectations + - **Dependency rules**: How modules depend on each other, what imports are allowed + - **Quality gates**: Linting, formatting, CI checks that must pass + + The constitution **MUST NOT**: + - Override existing project standards without user confirmation + - Invent conventions that don't exist in the codebase + - Include generic boilerplate unrelated to the actual project + +3. **Customize spec template**: Modify `.specify/templates/spec-template.md` to reflect the project: + - Add project-specific sections (e.g., "Database Migrations" for projects with ORMs) + - Include architecture-aware requirements (e.g., "Frontend Requirements" and "API Requirements" for full-stack projects) + - Reference actual module paths instead of generic placeholders + +4. **Customize plan template**: Modify `.specify/templates/plan-template.md` to reflect the project: + - Include module-aware implementation sections (e.g., separate phases for frontend/backend) + - Reference actual test frameworks and build tools + - Include project-specific complexity factors + +5. **Customize tasks template**: Modify `.specify/templates/tasks-template.md` to reflect the project: + - Task phases should map to the project's actual module structure + - Include project-specific setup tasks (e.g., database migration, dependency install) + - Reference actual test commands (e.g., `npm test`, `pytest`, `go test ./...`) + +6. **Generate AGENTS.md** (if multi-module): For monorepos and multi-module projects: + - Define agent boundaries per module + - Specify which agent owns which directories + - Set up inter-agent communication rules + +7. **Present changes**: Show the user what will be created or modified: + + ```markdown + # Bootstrap Plan + + | File | Action | Description | + |------|--------|-------------| + | `.specify/memory/constitution.md` | Create | Project-specific constitution with detected conventions | + | `.specify/templates/spec-template.md` | Modify | Add project-specific sections (Database Migrations, API Contract) | + | `.specify/templates/plan-template.md` | Modify | Add module-aware phases (frontend, backend, shared) | + | `.specify/templates/tasks-template.md` | Modify | Add actual test commands and build steps | + | `AGENTS.md` | Create | Agent boundaries for frontend and backend modules | + + Proceed with bootstrap? (confirm before writing) + ``` + +8. **Execute bootstrap**: After user confirmation, write all files. + +9. **Report**: + + ```markdown + # Bootstrap Complete + + | Artifact | Status | + |----------|--------| + | Constitution | ✅ Created — 12 rules from detected conventions | + | Spec template | ✅ Customized — added Database Migrations, API Contract sections | + | Plan template | ✅ Customized — frontend/backend phase split | + | Tasks template | ✅ Customized — actual test commands included | + | AGENTS.md | ✅ Created — 2 agents (frontend, backend) | + + ## Next Steps + - Review `.specify/memory/constitution.md` and adjust any rules + - Run `/speckit.brownfield.validate` to verify configuration matches project + - Run `/speckit.brownfield.migrate` to reverse-engineer specs for existing features + - Start new features with `/speckit.specify` — templates are now project-aware + ``` + +## Rules + +- **Always confirm before writing** — show the bootstrap plan and wait for approval +- **Never overwrite without asking** — if constitution or templates already exist, show a diff and ask +- **Derive from reality** — every constitution rule must trace to something detected in the codebase +- **No invented conventions** — if the project has no consistent pattern for something, say so instead of guessing +- **Respect existing spec-kit setup** — if `.specify/` already has customizations, merge rather than replace +- **Module-aware** — for monorepos, generate configuration that respects module boundaries \ No newline at end of file diff --git a/.github/agents/speckit.brownfield.migrate.agent.md b/.github/agents/speckit.brownfield.migrate.agent.md new file mode 100644 index 0000000..3a6bfa6 --- /dev/null +++ b/.github/agents/speckit.brownfield.migrate.agent.md @@ -0,0 +1,128 @@ +--- +description: Incrementally adopt SDD for existing features with reverse-engineered + specs +--- + + + + +# Migrate Existing Features + +Reverse-engineer spec-kit artifacts (spec.md, plan.md, tasks.md) for features that were built before spec-kit was adopted. This brings existing work into the SDD workflow so teams can track, refine, and extend features using spec-kit commands. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). The user may specify a feature or module to migrate (e.g., "auth system", "payments module"), a branch name, or "all" to migrate everything. + +## Prerequisites + +1. Verify a spec-kit project exists by checking for `.specify/` directory +2. Verify git is available and the project is a git repository +3. Verify the project has existing source code to migrate (not an empty project) +4. Verify constitution exists (recommend running `/speckit.brownfield.bootstrap` first if missing) + +## Outline + +1. **Identify migration targets**: Determine what to migrate based on user input: + + | Input | Action | + |-------|--------| + | Specific feature name | Locate the feature in the codebase by searching for related files, modules, or directories | + | Specific branch name | Analyze the branch's commits and changed files to identify the feature scope | + | Module path | Treat the entire module as a single feature to migrate | + | `all` | List all identifiable features and let the user select which to migrate | + | No input | Show a list of detected features and ask the user to pick one | + +2. **Detect feature boundaries**: For each migration target, determine its scope: + - **Files**: Which source files implement this feature + - **Tests**: Which test files cover this feature + - **Dependencies**: What other modules or services this feature depends on + - **API surface**: Endpoints, functions, or interfaces exposed by this feature + - **Database**: Migrations, models, or schema changes related to this feature + +3. **Reverse-engineer spec.md**: Analyze the code to reconstruct what the feature does: + - **User scenarios**: Infer from test cases, route handlers, and UI components + - **Requirements**: Extract from code behavior, validation rules, and error handling + - **Success criteria**: Derive from test assertions and acceptance patterns + - **Assumptions**: Note any hardcoded values, environment dependencies, or implicit requirements + - Mark the spec as `status: migrated` to distinguish from specs created through the normal workflow + +4. **Reverse-engineer plan.md**: Reconstruct the implementation approach: + - **Technical context**: Actual frameworks, libraries, and patterns used + - **Project structure**: Where the feature's code lives in the project + - **Complexity assessment**: Based on file count, line count, and dependency depth + +5. **Reverse-engineer tasks.md**: Create a task list reflecting what was actually built: + - Each major component or module becomes a task group + - Mark all tasks as `[x]` (completed) since the feature already exists + - Include test tasks based on actual test files found + - Note any gaps: code without tests, features without error handling + +6. **Create feature branch and artifacts**: For each migrated feature: + - Create a feature directory: `specs/{feature-name}/` + - Write `spec.md`, `plan.md`, and `tasks.md` into the feature directory + - Do **not** create a git branch — the feature already exists on its branch or main + +7. **Present migration plan**: Show what will be created before writing: + + ```markdown + # Migration Plan: User Authentication + + ## Detected Scope + | Category | Files | Lines | + |----------|-------|-------| + | Source | 8 files | ~420 lines | + | Tests | 3 files | ~180 lines | + | Migrations | 2 files | ~45 lines | + + ## Artifacts to Generate + | File | Content | + |------|---------| + | `specs/user-auth/spec.md` | 4 user scenarios, 12 requirements, 6 success criteria | + | `specs/user-auth/plan.md` | 3 implementation phases, 8 technical decisions | + | `specs/user-auth/tasks.md` | 14 tasks (all completed), 2 gaps identified | + + ## Gaps Found + - ⚠️ No error handling tests for expired tokens + - ⚠️ No rate limiting on login endpoint + + Proceed with migration? + ``` + +8. **Execute migration**: After user confirmation, write all artifacts. + +9. **Report**: + + ```markdown + # Migration Complete: User Authentication + + | Artifact | Status | + |----------|--------| + | spec.md | ✅ Created — 4 scenarios, 12 requirements | + | plan.md | ✅ Created — 3 phases | + | tasks.md | ✅ Created — 14/14 tasks complete | + + ## Identified Gaps + 1. No error handling tests for expired tokens → consider `/speckit.specify` for a follow-up feature + 2. No rate limiting on login endpoint → consider `/speckit.bugfix.report` to track + + ## Next Steps + - Review generated artifacts in `specs/user-auth/` + - Use `/speckit.refine.update` to adjust any inaccurate specs + - Use `/speckit.specify` for new features — they'll follow the same SDD workflow + - Run `/speckit.brownfield.migrate` again for additional features + ``` + +## Rules + +- **Always confirm before writing** — show the migration plan and wait for user approval +- **Honest assessment** — if the code is unclear or poorly documented, say so in the spec rather than inventing explanations +- **Mark as migrated** — all migrated specs must include `status: migrated` to distinguish from fresh specs +- **Identify gaps** — actively look for missing tests, error handling, or documentation and report them +- **Non-destructive** — never modify existing source code, only create spec artifacts +- **One feature at a time** — for "all" input, migrate features sequentially with confirmation between each +- **Respect constitution** — generated artifacts must follow the project's constitution rules \ No newline at end of file diff --git a/.github/agents/speckit.brownfield.scan.agent.md b/.github/agents/speckit.brownfield.scan.agent.md new file mode 100644 index 0000000..3fbeefe --- /dev/null +++ b/.github/agents/speckit.brownfield.scan.agent.md @@ -0,0 +1,121 @@ +--- +description: Auto-discover project structure, tech stack, frameworks, and architecture + patterns +--- + + + + +# Scan Project + +Analyze an existing codebase to discover its technology stack, architecture patterns, module structure, and coding conventions. This produces a project profile that the bootstrap command uses to generate tailored spec-kit configuration. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). The user may specify a subdirectory to scan (e.g., "backend/"), a focus area (e.g., "only frontend"), or request a specific depth of analysis. + +## Prerequisites + +1. Verify the current directory is a git repository +2. Verify this is an existing project with source code (not an empty repo) + +## Outline + +1. **Detect tech stack**: Identify languages, frameworks, and tools by scanning: + + | Signal | What to Check | + |--------|--------------| + | **Languages** | File extensions (`.py`, `.ts`, `.go`, `.java`, `.rs`, etc.) and their relative proportions | + | **Package managers** | `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle` | + | **Frameworks** | Dependencies in package files (React, Django, Spring, Express, Rails, etc.) | + | **Build tools** | `Makefile`, `webpack.config.js`, `vite.config.ts`, `Dockerfile`, `docker-compose.yml` | + | **CI/CD** | `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`, `Jenkinsfile` | + | **Testing** | Test directories, test frameworks in dependencies (`jest`, `pytest`, `go test`, `JUnit`) | + +2. **Analyze architecture**: Identify the project's structural patterns: + + | Pattern | Indicators | + |---------|-----------| + | **Monolith** | Single source tree, one entry point, shared database config | + | **Monorepo** | Multiple `package.json`/`go.mod` files, workspace config, `packages/` or `apps/` directories | + | **Microservices** | Multiple Dockerfiles, service directories, API gateway config | + | **Frontend + Backend** | Separate `client/`/`server/` or `frontend/`/`backend/` directories | + | **Library/Package** | `setup.py`, `lib/` directory, published package config | + | **MVC** | `models/`, `views/`, `controllers/` directories | + | **Layered** | `domain/`, `application/`, `infrastructure/`, `presentation/` directories | + +3. **Map module structure**: For monorepos and multi-module projects: + - Identify each module/package/service and its purpose + - Detect inter-module dependencies (imports, shared types) + - Note module boundaries (what code belongs where) + - Identify shared libraries or utilities + +4. **Extract conventions**: Detect existing coding patterns: + - **Naming**: File naming (camelCase, kebab-case, snake_case), directory naming + - **Branching**: Existing branch names and patterns from `git branch -a` + - **Commit style**: Recent commit message patterns from `git log --oneline -20` + - **Testing**: Test file location (`__tests__/`, `*_test.go`, `test_*.py`), test naming + - **Documentation**: README structure, inline docs, API docs + +5. **Detect existing governance**: Check for files that indicate existing project standards: + - `CONTRIBUTING.md`, `ARCHITECTURE.md`, `ADR/` (Architecture Decision Records) + - `.editorconfig`, linter configs (`.eslintrc`, `.flake8`, `rustfmt.toml`) + - `CLAUDE.md`, `AGENTS.md`, `.specify/` (existing spec-kit setup) + +6. **Output project profile**: + + ```markdown + # Project Profile + + ## Tech Stack + | Category | Detected | + |----------|----------| + | **Primary language** | TypeScript (68%), Python (32%) | + | **Frontend** | React 18, Vite, TailwindCSS | + | **Backend** | FastAPI, SQLAlchemy, PostgreSQL | + | **Testing** | Jest (frontend), pytest (backend) | + | **CI/CD** | GitHub Actions | + | **Package manager** | npm (frontend), pip (backend) | + + ## Architecture + - **Pattern**: Frontend + Backend (separated) + - **Frontend**: `client/` — React SPA + - **Backend**: `server/` — FastAPI REST API + - **Database**: PostgreSQL (via SQLAlchemy ORM) + + ## Module Map + | Module | Path | Purpose | Dependencies | + |--------|------|---------|-------------| + | Frontend | `client/` | React SPA | Backend API | + | Backend | `server/` | REST API | Database | + | Shared | `shared/` | Type definitions | — | + + ## Conventions + - **File naming**: kebab-case (frontend), snake_case (backend) + - **Branch pattern**: `feat/*`, `fix/*`, `chore/*` + - **Commit style**: Conventional Commits + - **Test location**: `__tests__/` (frontend), `tests/` (backend) + + ## Existing Governance + - ✅ CONTRIBUTING.md + - ✅ .eslintrc.json + - ❌ ARCHITECTURE.md + - ❌ .specify/ (no spec-kit setup) + + ## Recommendations + - Run `/speckit.brownfield.bootstrap` to generate tailored spec-kit configuration + - Constitution should enforce: kebab-case files (frontend), snake_case (backend) + - Feature specs should map to the frontend/backend split + ``` + +## Rules + +- **Read-only** — this command never modifies any files +- **Respect .gitignore** — never scan `node_modules/`, `vendor/`, `dist/`, `.venv/`, or other ignored directories +- **Proportional analysis** — report language percentages based on actual file counts or line counts +- **No assumptions** — only report what is actually detected in the codebase +- **Handle empty results** — if a category has nothing detected, say "Not detected" rather than guessing \ No newline at end of file diff --git a/.github/agents/speckit.brownfield.validate.agent.md b/.github/agents/speckit.brownfield.validate.agent.md new file mode 100644 index 0000000..ec39e2b --- /dev/null +++ b/.github/agents/speckit.brownfield.validate.agent.md @@ -0,0 +1,94 @@ +--- +description: Verify bootstrap output matches actual project structure and conventions +--- + + + + +# Validate Bootstrap + +Verify that the spec-kit configuration generated by `/speckit.brownfield.bootstrap` accurately reflects the actual project structure, conventions, and architecture. Reports mismatches and suggests corrections. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). The user may specify a focus area (e.g., "only constitution", "only templates") or request verbose output. + +## Prerequisites + +1. Verify a spec-kit project exists by checking for `.specify/` directory +2. Verify git is available and the project is a git repository +3. Verify at least one bootstrap artifact exists (constitution, customized templates, or AGENTS.md) + +## Outline + +1. **Validate constitution**: Check `.specify/memory/constitution.md` against the actual codebase: + + | Check | How | + |-------|-----| + | **Language references** | Verify mentioned languages actually exist in the codebase | + | **Directory references** | Verify all referenced paths (`client/`, `server/`, etc.) exist | + | **Framework references** | Verify mentioned frameworks are in dependency files | + | **Naming conventions** | Sample 20 files and check if naming rules match reality | + | **Test location** | Verify test directories mentioned in constitution exist | + | **Branch pattern** | Check if branch naming rules match actual branches in `git branch -a` | + +2. **Validate templates**: Check customized spec/plan/tasks templates: + + | Check | How | + |-------|-----| + | **Module references** | Verify template sections reference actual modules/directories | + | **Test commands** | Verify test commands in tasks template actually work | + | **Build commands** | Verify build commands reference real scripts from package files | + | **Section relevance** | Flag template sections that reference non-existent project aspects | + +3. **Validate AGENTS.md** (if exists): Check agent configuration: + + | Check | How | + |-------|-----| + | **Directory ownership** | Verify each agent's directories exist | + | **No overlaps** | Check that no directory is owned by multiple agents | + | **No orphans** | Check that all source directories are covered by at least one agent | + +4. **Detect drift**: Check if the project has changed since bootstrap: + - New directories or modules added since constitution was generated + - Dependencies added or removed since bootstrap + - New branch patterns that don't match constitution rules + +5. **Output validation report**: + + ```markdown + # Validation Report + + ## Constitution + | Rule | Status | Detail | + |------|--------|--------| + | Primary language: TypeScript | ✅ Pass | 68% of source files | + | Frontend in `client/` | ✅ Pass | Directory exists, contains React code | + | Backend in `server/` | ✅ Pass | Directory exists, contains FastAPI code | + | Test location: `__tests__/` | ⚠️ Drift | Also found tests in `tests/` (not mentioned) | + | Branch pattern: `feat/*` | ✅ Pass | 8/10 recent branches match | + + ## Templates + | Template | Status | Detail | + |----------|--------|--------| + | Spec template | ✅ Pass | All custom sections map to real project aspects | + | Plan template | ⚠️ Drift | References `shared/` module — directory renamed to `common/` | + | Tasks template | ✅ Pass | Test commands verified | + + ## Summary + - **Checks passed**: 9/11 + - **Drift detected**: 2 items + - **Action needed**: Update plan template (`shared/` → `common/`), add `tests/` to constitution + ``` + +## Rules + +- **Read-only** — this command never modifies any files +- **Evidence-based** — every pass/fail must cite specific files or directories as evidence +- **Actionable output** — for every failure or drift, suggest the specific fix +- **Non-blocking** — drift warnings don't mean the configuration is broken, just that it could be improved +- **Respect .gitignore** — never scan ignored directories when validating \ No newline at end of file diff --git a/.github/agents/speckit.checklist.agent.md b/.github/agents/speckit.checklist.agent.md new file mode 100644 index 0000000..93ec785 --- /dev/null +++ b/.github/agents/speckit.checklist.agent.md @@ -0,0 +1,361 @@ +--- +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). + +## Pre-Execution Checks + +**Check for extension hooks (before checklist generation)**: +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_checklist` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Execution Steps. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently + +## 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. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +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` + - File handling behavior: + - If file does NOT exist: Create new file and number items starting from CHK001 + - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016) + - Never delete or replace existing checklist content - always preserve and append + + **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### ` lines with globally incrementing IDs starting at CHK001. + +7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + +**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. 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?" + +## Post-Execution Checks + +**Check for extension hooks (after checklist generation)**: +Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.after_checklist` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently diff --git a/.github/agents/speckit.clarify.agent.md b/.github/agents/speckit.clarify.agent.md new file mode 100644 index 0000000..9de13e1 --- /dev/null +++ b/.github/agents/speckit.clarify.agent.md @@ -0,0 +1,247 @@ +--- +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. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Pre-Execution Checks + +**Check for extension hooks (before clarification)**: +- Check if `.specify/extensions.yml` exists in the project root. +- If it exists, read it and look for entries under the `hooks.before_clarify` key +- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally +- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. +- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: + - If the hook has no `condition` field, or it is null/empty, treat the hook as executable + - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For each executable hook, output the following based on its `optional` flag: + - **Optional hook** (`optional: true`): + ``` + ## Extension Hooks + + **Optional Pre-Hook**: {extension} + Command: `/{command}` + Description: {description} + + Prompt: {prompt} + To execute: `/{command}` + ``` + - **Mandatory hook** (`optional: false`): + ``` + ## Extension Hooks + + **Automatic Pre-Hook**: {extension} + Executing: `/{command}` + EXECUTE_COMMAND: {command} + + Wait for the result of the hook command before proceeding to the Outline. + ``` +- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently + +## 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. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +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 5 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: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |