diff --git a/.github/workflows/community-smoke.yml b/.github/workflows/community-smoke.yml index f957a6f873..bbae56f1df 100644 --- a/.github/workflows/community-smoke.yml +++ b/.github/workflows/community-smoke.yml @@ -47,6 +47,7 @@ jobs: test -f .specify/extensions/arch/extension.yml test -f .specify/extensions/preview/extension.yml + test -f .specify/extensions/discovery/extension.yml test -f .specify/extensions/repository-governance/extension.yml test -f .specify/presets/workflow-preset/preset.yml /tmp/specify-community-smoke-venv/bin/python - <<'PY' @@ -101,6 +102,7 @@ jobs: speckit-preview-high-html; do test -f ".claude/skills/$preview_skill/SKILL.md" done + test -f .claude/skills/speckit-discovery-feasibility/SKILL.md test -f .claude/skills/speckit-repository-governance-refresh/SKILL.md test -f .claude/skills/speckit-specify/SKILL.md test -f .claude/skills/speckit-clarify/SKILL.md @@ -118,7 +120,7 @@ jobs: grep -q "Vertical Planner Agent" .claude/skills/speckit-implement/SKILL.md grep -q "Worker Agent" .claude/skills/speckit-implement/SKILL.md - for extension_id in arch preview repository-governance; do + for extension_id in arch discovery preview repository-governance; do /tmp/specify-community-smoke-venv/bin/specify extension remove "$extension_id" --force test ! -d ".specify/extensions/$extension_id" case "$extension_id" in @@ -137,13 +139,16 @@ jobs: test ! -d ".claude/skills/$preview_skill" done ;; + discovery) + test "$(find .claude/skills -maxdepth 1 -type d -name 'speckit-discovery-*' | wc -l)" -eq 0 + ;; repository-governance) test ! -d .claude/skills/speckit-repository-governance-refresh ;; esac done - for extension_id in arch preview repository-governance; do + for extension_id in arch discovery preview repository-governance; do /tmp/specify-community-smoke-venv/bin/specify extension add "$GITHUB_WORKSPACE/extensions/$extension_id" --dev case "$extension_id" in arch) @@ -163,6 +168,10 @@ jobs: grep -q "evidence-backed" ".claude/skills/$preview_skill/SKILL.md" done ;; + discovery) + test -f .claude/skills/speckit-discovery-feasibility/SKILL.md + grep -q "evidence-backed feasibility study" .claude/skills/speckit-discovery-feasibility/SKILL.md + ;; repository-governance) test -f .claude/skills/speckit-repository-governance-refresh/SKILL.md grep -q "Repository Governance Generate/Update" .claude/skills/speckit-repository-governance-refresh/SKILL.md @@ -170,6 +179,11 @@ jobs: esac done + /tmp/specify-community-smoke-venv/bin/specify extension remove discovery --force + /tmp/specify-community-smoke-venv/bin/specify extension add discovery + test -f .claude/skills/speckit-discovery-feasibility/SKILL.md + test -f .claude/skills/speckit-discovery-decision/SKILL.md + /tmp/specify-community-smoke-venv/bin/specify preset resolve plan-template | tee resolve-plan-template.txt grep -q "workflow-preset" resolve-plan-template.txt grep -q "Composition chain" resolve-plan-template.txt diff --git a/extensions/catalog.json b/extensions/catalog.json index b65a784f01..e3706c1264 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -93,6 +93,30 @@ "ux" ] }, + "discovery": { + "name": "Spec Kit Discovery Extension", + "id": "discovery", + "version": "0.2.0", + "description": "Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation", + "author": "bigsmartben", + "repository": "https://github.com/bigsmartben/spec-kit-discovery", + "license": "MIT", + "bundled": true, + "requires": { + "speckit_version": ">=0.1.0" + }, + "provides": { + "commands": 6 + }, + "tags": [ + "discovery", + "feasibility", + "selection", + "codebase", + "poc", + "decision" + ] + }, "repository-governance": { "name": "Repository Governance", "id": "repository-governance", diff --git a/extensions/discovery/.extensionignore b/extensions/discovery/.extensionignore new file mode 100644 index 0000000000..e694d3e338 --- /dev/null +++ b/extensions/discovery/.extensionignore @@ -0,0 +1,12 @@ +.git/ +.gitignore +.extensionignore + +# Local editor state +.idea/ +.vscode/ + +# Temporary files +*.log +tmp/ +temp/ diff --git a/extensions/discovery/.gitignore b/extensions/discovery/.gitignore new file mode 100644 index 0000000000..84ffb1d8ee --- /dev/null +++ b/extensions/discovery/.gitignore @@ -0,0 +1,16 @@ +.DS_Store +Thumbs.db + +# Local editor state +.idea/ +.vscode/ +*.swp +*.swo + +# Spec Kit local-only config generated by installed extensions +.specify/extensions/**/*-config.local.yml + +# Logs and temporary files +*.log +tmp/ +temp/ diff --git a/extensions/discovery/CATALOG-SUBMISSION.md b/extensions/discovery/CATALOG-SUBMISSION.md new file mode 100644 index 0000000000..ab166d2828 --- /dev/null +++ b/extensions/discovery/CATALOG-SUBMISSION.md @@ -0,0 +1,32 @@ +# Spec Kit Extension Submission + +Extension ID: discovery +Name: Spec Kit Discovery Extension +Version: 0.2.0 +Description: Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation. +Author: bigsmartben +Repository URL: https://github.com/bigsmartben/spec-kit-discovery +Download URL: https://github.com/bigsmartben/spec-kit-discovery/archive/refs/tags/v0.2.0.zip +Documentation URL: https://github.com/bigsmartben/spec-kit-discovery#readme +License: MIT +Required Spec Kit version: >=0.1.0 +Commands count: 6 +Hooks count: 0 +Tags: discovery, feasibility, selection, codebase, poc, decision + +## Key Features + +- Adds `speckit.discovery.feasibility`, `speckit.discovery.techselect`, and `speckit.discovery.codebase`. +- Adds `speckit.discovery.codebase-api-imp` for source-backed implementation overviews. +- Adds `speckit.discovery.poc` for bounded proof-of-concept planning and validation. +- Adds `speckit.discovery.decision` with `type: api|performance|migration|ux|compatibility` routing. +- Keeps outputs focused on evidence, assumptions, unknowns, planning decisions, and validation scope before formal implementation planning. + +## Testing Performed + +- Validated the bundled manifest with `ExtensionManifest`. +- Ran `uv run pytest tests/integrations/test_cli.py -k "community_extensions_and_workflow_preset_auto_installed or no_git_keeps_community_defaults"`. +- Ran `uv run pytest tests/test_arch_templates.py tests/test_presets.py -k "community_smoke_checks_wheel_assets_and_extension_dev_reinstall or init_next_steps_do_not_list_arch_as_core_workflow"`. +- Built the CLI wheel with `uv build --wheel` and verified `specify_cli/core_pack/extensions/discovery/extension.yml` and representative command/template files were included. +- Smoke-tested `specify init`, `specify extension remove discovery --force`, and `specify extension add discovery` in a temporary project. +- Verified release `v0.2.0` installs with `Commands: 6`. diff --git a/extensions/discovery/CHANGELOG.md b/extensions/discovery/CHANGELOG.md new file mode 100644 index 0000000000..41a0e90bf3 --- /dev/null +++ b/extensions/discovery/CHANGELOG.md @@ -0,0 +1,16 @@ +# Changelog + +## [0.2.0] - 2026-06-23 + +### Changed + +- Consolidated API integration, performance, data migration, UX workflow, and compatibility discovery into `speckit.discovery.decision` with type-specific routing. +- Updated documentation to describe the six-command public interface. +- Replaced references to the old API integration command with `/speckit.discovery.decision type: api`. + +## [0.1.0] - 2026-06-23 + +### Added + +- Initial `discovery` extension manifest and usage documentation. +- Added discovery commands for feasibility, technology selection, legacy codebase assessment, implementation overview, proof-of-concept validation, and scenario-specific technical decisions. diff --git a/extensions/discovery/LICENSE b/extensions/discovery/LICENSE new file mode 100644 index 0000000000..7a62eb18f5 --- /dev/null +++ b/extensions/discovery/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 bigsmartben + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/extensions/discovery/README.md b/extensions/discovery/README.md new file mode 100644 index 0000000000..599db126b8 --- /dev/null +++ b/extensions/discovery/README.md @@ -0,0 +1,175 @@ +# Spec Kit Discovery Extension + +`spec-kit-discovery` provides a `discovery` extension for Spec Kit. It adds scope-bounded commands for the technical discovery phase: + +```text +/speckit.discovery.feasibility [goal or idea] [constraints] [success criteria] +/speckit.discovery.techselect [decision to make] [candidate options] [criteria or constraints] +/speckit.discovery.decision type: api|performance|migration|ux|compatibility [scenario] [constraints or risks] +/speckit.discovery.codebase [target area or fuzzy scope] [planned change or integration] [known concerns] +/speckit.discovery.codebase-api-imp [API route, SDK method, topic, command, or capability] [known concern] [source scope] +/speckit.discovery.poc [user stories] [use cases] [core design idea] +``` + +The extension helps teams complete technical discovery before formal planning. `feasibility`, `techselect`, and `codebase` produce decision documents; `decision` evaluates scenario-specific API, performance, migration, UX, and compatibility risks; `codebase-api-imp` explains existing interface implementations from source facts; `poc` creates a bounded-scope experiment that supports feasibility, selection, scenario decision, or legacy-codebase risk decisions. + +Internally, the commands are organized into four capability types: + +- `feasibility`: support a go/no-go continuation decision. +- `techselect`: compare general technology choices. +- `decision`: evaluate scenario-specific API, performance, migration, UX, and compatibility decisions with type-specific risks. +- `codebase`, `codebase-api-imp` (API implementation overview), and `poc`: locate relevant source scope, gather source-backed evidence, record evidence levels and unknowns, explain implemented interface behavior, or run executable validation. + +## Installation + +From a Spec Kit project: + +```bash +specify extension add --dev /path/to/spec-kit-discovery +``` + +From this repository during local development: + +```bash +specify extension add --dev . --force +``` + +After installation, restart or refresh your AI coding agent if the new command does not appear immediately. + +## Commands + +### `speckit.discovery.feasibility` + +Produces an evidence-backed feasibility study. + +Typical output: + +- `feasibility.md` +- decision: `feasible`, `feasible-with-risks`, `not-feasible`, or `inconclusive` + +### `speckit.discovery.techselect` + +Builds a technology selection matrix for candidate tools, libraries, platforms, or architectures. + +Typical output: + +- `tech-selection-matrix.md` +- recommendation, shortlist, or evidence gap + +### `speckit.discovery.decision` + +Evaluates a scenario-specific technical decision before formal planning. Use `type: api`, `type: performance`, `type: migration`, `type: ux`, or `type: compatibility` to select the decision frame and output template. + +Typical output: + +- `api-integration-discovery.md` +- `performance-discovery.md` +- `data-migration-discovery.md` +- `ux-discovery.md` +- `compatibility-discovery.md` +- type-specific `Planning Decision` + +### `speckit.discovery.codebase` + +Assesses legacy codebase risks, reusable assets, constraints, and integration hazards. When the target area is fuzzy, it first narrows likely source areas before using files, symbols, tests, configuration, and observed behavior as evidence for planning. + +Typical output: + +- `legacy-codebase-risk-assessment.md` +- scoped source areas or inspected paths +- source facts with file references +- evidence level per finding +- unknowns and unresolved questions +- risks rated as `low`, `medium`, `high`, or `unknown` + +### `speckit.discovery.codebase-api-imp` + +Explains how an already implemented API or interface works from repository facts. Use it for an HTTP/RPC route, SDK method, message topic, scheduled job, CLI command, or internal capability when engineers need implementation understanding or defect-localization guidance. + +Typical output: + +- `codebase-api-imp.md` +- interface match and source-backed entrance evidence +- service/system-level and module/component-level Mermaid sequence diagrams when evidence supports them +- repository-fact-backed business implementation flowcharts for key branches, dependencies, exceptions, and return paths +- evidence levels: `Proven`, `Framework inferred`, `Runtime dependent`, or `Unknown` + +### `speckit.discovery.poc` + +Creates a bounded-scope PoC plan and, when static evidence is insufficient and execution preconditions are met, a minimum runnable validation plus evidence report and conclusion. + +Minimum input: + +- User stories +- Use cases +- Core design idea + +Example: + +```text +/speckit.discovery.poc US: Readers can search notes by title and body. UC: Search while typing and open a result. Core design idea: Use SQLite FTS5 with a small local index. +``` + +The command produces: + +- `poc-plan.md` +- `poc-result.md` +- `discovery//poc/` minimum validation code or scripts when executable evidence is required +- evidence logs or outputs +- result: `passed`, `failed`, or `inconclusive` + +## Scenario-Specific Technical Decisions + +Use `/speckit.discovery.decision` when the unknown is already tied to a common technical decision situation. The command creates a single-decision discovery document with a type-specific `Planning Decision`, and sets `Evaluation Mode` to either `comparison` or `single-approach-readiness`. + +| Decision type | Use for | Typical output | +|---|---|---| +| `api` | Third-party API, SDK, webhook, service, SaaS platform, or partner integration decisions. | `api-integration-discovery.md` | +| `performance` | Latency, throughput, scalability, resource, capacity, or cost decisions. | `performance-discovery.md` | +| `migration` | Data model, storage, schema, backfill, import/export, or migration decisions. | `data-migration-discovery.md` | +| `ux` | Complex interaction, stateful workflow, accessibility, responsive behavior, or frontend/backend handoff decisions. | `ux-discovery.md` | +| `compatibility` | Browser, OS, device, runtime, framework, API version, or deployment compatibility decisions. | `compatibility-discovery.md` | + +## Repository Structure + +```text +. +├── extension.yml +├── commands/ +│ ├── codebase-api-imp.md +│ ├── codebase.md +│ ├── decision.md +│ ├── feasibility.md +│ ├── poc.md +│ └── techselect.md +├── templates/ +│ ├── api-integration-discovery.md +│ ├── codebase-api-imp.md +│ ├── compatibility-discovery.md +│ ├── data-migration-discovery.md +│ ├── feasibility.md +│ ├── legacy-codebase-risk-assessment.md +│ ├── performance-discovery.md +│ ├── poc-plan.md +│ ├── poc-result.md +│ ├── tech-selection-matrix.md +│ └── ux-discovery.md +├── docs/ +│ └── usage.md +├── CHANGELOG.md +├── LICENSE +└── README.md +``` + +## Development + +Validate the extension from a Spec Kit project with: + +```bash +specify extension add --dev /path/to/spec-kit-discovery --force +specify extension info discovery +``` + +## License + +MIT diff --git a/extensions/discovery/commands/codebase-api-imp.md b/extensions/discovery/commands/codebase-api-imp.md new file mode 100644 index 0000000000..c94478a864 --- /dev/null +++ b/extensions/discovery/commands/codebase-api-imp.md @@ -0,0 +1,68 @@ +--- +name: speckit.discovery.codebase-api-imp +description: Explain an implemented API or interface from repository facts for implementation understanding and defect localization. +argument-hint: "[API route, SDK method, topic, command, or capability] [known concern or suspected defect] [source scope]" +--- + + +You are a codebase API implementation discovery facilitator for Spec Kit projects. Your job is to explain how an already implemented API or interface works from repository facts, so engineers can understand the business flow, identify important branches, and continue defect localization. + + + +Use this command during the Discovery extension workflow when the user needs a source-backed implementation overview for an existing interface, such as an HTTP/RPC route, SDK method, message topic, scheduled job, CLI command, or internal capability entrypoint. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: +- Interface target: route, API name, SDK method, message topic, command, job, or capability description. +- Known concern: suspected defect, failing scenario, confusing branch, dependency concern, or runtime behavior to localize. +- Source scope: repository, module, directory, service, package, or cross-repository roots when known. + +Infer optional fields only from repository context and conversation, and label inferred values as assumptions. If the interface target is absent or too ambiguous to identify candidate entrances, inspect repository structure and search likely entrances before asking one concise clarifying question. + + + +1. Establish the interface target: + - Normalize the target name, route/address/topic/command/method, functional description, known concern, and source scope. + - Treat the current repository as the default analysis scope. + - If multiple candidate entrances match, list up to five candidates with evidence and choose the strongest source-backed match before writing the final overview. + - If a downstream repository or external system is mentioned but source is unavailable, document it only as an external dependency, runtime-dependent boundary, or unknown. + +2. Gather repository facts: + - Locate entrances such as HTTP/RPC handlers, route declarations, public SDK methods, message consumers, scheduled jobs, CLI commands, or internal capability entrypoints. + - Trace only planning-relevant implementation facts: framework wiring, middleware/interceptors, direct calls, async/event edges, data reads/writes, external clients, retries, transactions, exception handling, state transitions, and return mapping. + - Separate repository-proven facts from framework inference, runtime-dependent behavior, assumptions, and unknowns. + - Use lightweight file and line references for important entrances, branches, dependencies, exception paths, and runtime boundaries. + - Do not claim business behavior, callers, branches, DTO fields, tables, downstream internals, retries, exceptions, or return shapes unless repository evidence supports them. + +3. Build the defect-localization hierarchy: + - Use a service/system-level sequence diagram for externally observable interaction among caller/actor, interface boundary, analyzed system, and contract-visible external systems. + - Use a module/component-level sequence diagram for source-backed boundary-crossing collaboration among handlers, middleware, application/domain components, repositories/gateways/clients, brokers, or external systems. + - Use repository-fact-backed flowcharts only when a module/component message needs concrete branch, exception, data/dependency, async, transaction, fallback, runtime-boundary, or return-path detail. + - Keep sequence diagrams abstract. Put branches, loops, retries, decisions, data access, exception mapping, and return details in flowcharts or tables. + +4. Create or update `codebase-api-imp.md` by rendering `templates/codebase-api-imp.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//codebase-api-imp.md`. This command is responsible for implementation understanding and defect-localization evidence only. + +5. Classify each important fact with exactly one evidence level: + - `Proven`: repository-visible fact with file and line evidence. + - `Framework inferred`: source-visible framework configuration, annotation, decorator, registration, or manifest implies behavior, but runtime selection may still vary. + - `Runtime dependent`: requires profile, generated code, live configuration, remote service, broker state, feature flag, or runtime trace. + - `Unknown`: repository evidence is missing, ambiguous, or conflicting. + + + +- Analyze existing implementation only. Do not implement production code, edit tests, change configuration, or call behavior-changing external systems. +- Keep the output useful for understanding and localization, not as raw search dumps or exhaustive call lists. +- Do not use this command for API integration technology selection; use `/speckit.discovery.decision type: api`. +- Do not use this command for broad legacy risk assessment without a target interface; use `/speckit.discovery.codebase`. +- Do not use this command for executable validation; record the gap and recommend `/speckit.discovery.poc`. +- Use Mermaid `sequenceDiagram` and `flowchart TD` only when the repository facts support the diagram content. +- Prefer source-visible names over generic architecture labels. Do not invent missing layers or force a layered architecture onto the codebase. +- Preserve existing file structure and unrelated content. + diff --git a/extensions/discovery/commands/codebase.md b/extensions/discovery/commands/codebase.md new file mode 100644 index 0000000000..c5713ca4c1 --- /dev/null +++ b/extensions/discovery/commands/codebase.md @@ -0,0 +1,85 @@ +--- +name: speckit.discovery.codebase +description: Assess legacy codebase risks, reusable assets, constraints, and integration hazards. +argument-hint: "[target area] [planned change or integration] [known concerns]" +--- + + +You are a legacy codebase assessment facilitator for Spec Kit projects. Your job is to inspect the existing repository, resolve the relevant source scope when it is fuzzy, identify reusable assets and latent technical, operational, and integration risks, and summarize planning-relevant evidence. + + + +Use this command during the Discovery extension workflow when the user needs to understand an existing codebase before making a feasibility, selection, migration, integration, or implementation decision. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: +- Target area: subsystem, feature, module, service, data flow, or integration boundary to assess. +- Planned change or integration: what new work may touch the existing code. +- Known concerns: quality, test gaps, ownership, performance, security, data model, coupling, build instability, or migration risk. + +Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. Treat user-provided descriptions, work notes, or prior analysis as input claims until source evidence verifies them. If the primary target area is absent or ambiguous, inspect repository structure and resolve likely candidate scopes before asking one concise clarifying question. + + + +1. Resolve the assessment scope: + - Extract source-verification targets from the user input: capability, entry point, boundary, logic, data flow, integration, or gap check. + - When the target area is fuzzy, build an open candidate pool instead of trusting the first search result. + - List up to three candidate repositories, modules, directories, or source areas with evidence and unknowns. + - Use confidence labels `high`, `medium`, `low`, or `unknown`; do not assign `high` to keyword-only matches. + - Distinguish scope confidence from behavior proof. A likely source area still needs source-backed verification before it becomes a codebase fact. + +2. Probe available evidence capabilities: + - Repository inventory, manifests, module structure, source roots, tests, and build hooks. + - Indexed search, symbol search, semantic navigation, call resolution, diagnostics, or runtime evidence when available. + - Record capability limits and fall back to source slices, manifests, and search results when stronger tools are unavailable. + +3. Map the relevant codebase area: + - Entry points. + - Modules and dependencies. + - Data models and persistence boundaries. + - External integrations. + - Tests, fixtures, and build hooks. + +4. Normalize source-backed findings: + - Input targets and assumptions. + - Entrances, module boundaries, reusable capabilities, dependency edges, data access, external dependencies, cross-cutting behavior, and unknowns. + - Evidence references with file path, line or symbol when available, and confidence. + - Runtime-dependent behavior that static inspection cannot prove. + +5. Identify planning-relevant outcomes: + - Reusable components. + - Coupling and dependency risks. + - Missing or weak tests. + - Migration hazards. + - Operational risks. + - Security, privacy, or compliance concerns. + - Documentation gaps. + +6. Create or update `legacy-codebase-risk-assessment.md` by rendering `templates/legacy-codebase-risk-assessment.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//legacy-codebase-risk-assessment.md`. This command is responsible for scope resolution, repository inspection, source fact capture, risk classification, follow-up classification, and template field population only. + +7. Rate each risk as: + - `low` + - `medium` + - `high` + - `unknown` + +8. Recommend whether follow-up `/speckit.discovery.poc`, `/speckit.discovery.feasibility`, or `/speckit.discovery.techselect` work is needed before formal planning. + + + +- Ground findings in file paths, code references, tests, or observed behavior whenever possible. +- Separate proven source facts from inferred behavior and assumptions. +- Do not claim runtime truth from static code alone; mark configuration, generated code, remote services, async delivery, and production behavior as runtime-dependent unless observed. +- Keep candidate scope routing, source facts, risk assessment, and planning recommendations distinct. +- Do not rewrite code unless the user explicitly asks for remediation. +- Do not treat old code as bad by default; distinguish stable reuse from real risk. +- Keep the assessment limited to planning-relevant scope and evidence. +- Preserve existing file structure and unrelated content. + diff --git a/extensions/discovery/commands/decision.md b/extensions/discovery/commands/decision.md new file mode 100644 index 0000000000..263f5a56f0 --- /dev/null +++ b/extensions/discovery/commands/decision.md @@ -0,0 +1,95 @@ +--- +name: speckit.discovery.decision +description: Evaluate a scenario-specific technical decision for API, performance, migration, UX, or compatibility risks before formal planning. +argument-hint: "type: api|performance|migration|ux|compatibility [scenario] [constraints or risks]" +--- + + +You are a scenario-specific technical decision facilitator for Spec Kit projects. Your job is to turn a known technical decision situation into an evidence-backed discovery artifact with scenario context, candidate approaches, risks, validation needs, and a clear planning decision. + + + +Use this command during the Discovery extension workflow when the user already knows the decision shape and it fits one of these scenario types: + +- `api`: external API, SDK, webhook provider, internal service, SaaS platform, protocol, or partner system integration. +- `performance`: latency, throughput, scalability, resource, reliability, capacity, or cost constraint. +- `migration`: data model change, storage choice, schema migration, backfill, import/export flow, retention change, or persistence boundary. +- `ux`: UX interaction, stateful workflow, responsive behavior, accessibility requirement, or frontend/backend handoff. +- `compatibility`: browser, OS, device, runtime, framework version, deployment target, database version, API version, or operating environment support. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: + +- Decision type: `api`, `performance`, `migration`, `ux`, or `compatibility`. +- Scenario: the integration, flow, data change, interaction, feature, environment, or support boundary being evaluated. +- Constraints or risks: known assumptions, operational limits, target thresholds, rollout constraints, validation concerns, or unresolved questions. + +Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. If the decision type cannot be derived from the input, ask one concise clarifying question. If the type is clear but required scenario context is missing, inspect repository context and ask one concise clarifying question only when the scenario cannot be inferred. + + + +1. Normalize the input into: + - Decision type: exactly one of `api`, `performance`, `migration`, `ux`, or `compatibility`. + - Decision question. + - Scenario context. + - Success criteria. + - Evaluation mode: `comparison` or `single-approach-readiness`. + - Candidate approaches. + - Known constraints. + - Assumptions. + +2. Apply type-specific framing: + - For `api`, capture integration target, intended workflow, actors and systems, data exchanged, authentication, authorization, contract assumptions, rate limits, retries, idempotency, sandbox access, observability, versioning, privacy, compliance, vendor lock-in, and operational ownership. + - For `performance`, capture target flow, workload assumptions, measurable thresholds, hot paths, data volume growth, bottleneck hypotheses, concurrency, backpressure, queue depth, memory, CPU, startup time, deployment constraints, cost, and repeatable measurement gaps. + - For `migration`, capture current state, affected readers and writers, data volume, data quality assumptions, migration constraints, compatibility boundaries, rollout order, rollback feasibility, backup or recovery points, privacy, retention, auditability, and sample data representativeness. + - For `ux`, capture user workflow, primary and secondary users, states and transitions, edge cases, loading states, optimistic updates, error recovery, undo, accessibility, keyboard support, focus behavior, responsive behavior, and cross-team contract needs. + - For `compatibility`, capture feature or workflow, required support matrix, optional support, runtime or platform metadata, dependency version constraints, build and packaging behavior, feature availability, fallbacks, degradation paths, and release verification effort. + +3. Inspect relevant repository context when available: + - Source files, manifests, configuration, tests, fixtures, documentation, dependency declarations, telemetry, or existing implementation patterns that affect the selected decision type. + - Treat user-provided descriptions, work notes, and prior analysis as input claims until repository evidence verifies them. + +4. Classify evidence: + - Repository facts. + - External or provider facts when current external documentation is required. + - Assumptions. + - Runtime-dependent behavior. + - Evidence gaps. + - Validation needed. + +5. Create or update the type-specific discovery document by rendering the matching template. Prefer the active feature directory when it exists. Otherwise create the file under `discovery//`. + + | Decision type | Template | Output file | + |---|---|---| + | `api` | `templates/api-integration-discovery.md` | `api-integration-discovery.md` | + | `performance` | `templates/performance-discovery.md` | `performance-discovery.md` | + | `migration` | `templates/data-migration-discovery.md` | `data-migration-discovery.md` | + | `ux` | `templates/ux-discovery.md` | `ux-discovery.md` | + | `compatibility` | `templates/compatibility-discovery.md` | `compatibility-discovery.md` | + +6. Set `Planning Decision` using the selected type's allowed values: + - `api`: `ready-for-planning`, `needs-poc`, `needs-provider-clarification`, `not-recommended`, `inconclusive`. + - `performance`: `ready-for-planning`, `needs-benchmark`, `needs-design-change`, `not-feasible`, `inconclusive`. + - `migration`: `ready-for-planning`, `needs-dry-run`, `needs-model-redesign`, `not-recommended`, `inconclusive`. + - `ux`: `ready-for-planning`, `needs-prototype`, `needs-contract-clarification`, `not-recommended`, `inconclusive`. + - `compatibility`: `ready-for-planning`, `needs-matrix-test`, `needs-fallback-design`, `not-supported`, `inconclusive`. + +7. Recommend follow-up work only when it directly reduces decision risk, such as `/speckit.discovery.poc`, `/speckit.discovery.techselect`, `/speckit.discovery.codebase`, `/speckit.discovery.codebase-api-imp`, or `/speckit.discovery.feasibility`. + + + +- Keep this command limited to discovery, evidence classification, planning decision classification, and template field population. +- Do not implement production code unless the user explicitly asks. +- Do not run probes, mocks, benchmarks, dry-runs, prototypes, matrix checks, smoke tests, dependency checks, or environment checks in this command. If executable evidence is required, record the evidence gap and recommend `/speckit.discovery.poc`. +- In `comparison` mode, require two or more candidates. In `single-approach-readiness` mode, evaluate the single approach against acceptance criteria appropriate to the selected decision type. +- Ground findings in repository paths, external facts, observed behavior, or explicitly labeled assumptions. +- Clearly separate facts, assumptions, unresolved questions, runtime-dependent behavior, and evidence gaps. +- Preserve existing file structure and unrelated content. + diff --git a/extensions/discovery/commands/feasibility.md b/extensions/discovery/commands/feasibility.md new file mode 100644 index 0000000000..0ebf9bddf5 --- /dev/null +++ b/extensions/discovery/commands/feasibility.md @@ -0,0 +1,68 @@ +--- +name: speckit.discovery.feasibility +description: Produce an evidence-backed feasibility study for a product or technical direction. +argument-hint: "[goal or idea] [constraints] [success criteria]" +--- + + +You are a technical discovery facilitator for Spec Kit projects. Your job is to produce a decision-grade feasibility assessment that supports a go/no-go continuation decision. + + + +Use this command during the Discovery extension workflow when the user needs to answer whether something can be built within known business, technical, operational, schedule, or resource constraints. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: +- Goal or idea: what the team wants to prove can be done. +- Constraints: time, budget, team skills, platform, compliance, data, performance, reliability, or migration boundaries. +- Success criteria: what must be true for the direction to be considered feasible. + +Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. If the primary goal or feasibility question is absent, ask one concise clarifying question. + + + +1. Normalize the input into: + - Goal. + - Context. + - Known constraints. + - Assumptions. + - Success criteria. + +2. Assess feasibility across these dimensions: + - Business fit. + - Technical viability. + - Resource and schedule fit. + - Operational readiness. + - Security, privacy, and compliance risk. + - Integration and migration complexity. + +3. Classify the evidence state: + - Existing evidence: repository findings, prior art, existing components, or observed behavior. + - Evidence gaps: unsupported claims, missing repository facts, or unresolved constraints. + - Validation needed: benchmarks, experiments, PoCs, or follow-up discovery required to close decision risk. + +4. Create or update `feasibility.md` by rendering `templates/feasibility.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//feasibility.md`. This command is responsible for input normalization, evidence classification, decision classification, and template field population only. + +5. Set `Decision` to exactly one of: + - `feasible` + - `feasible-with-risks` + - `not-feasible` + - `inconclusive` + +6. Recommend follow-up discovery work only when it directly reduces decision risk, such as `/speckit.discovery.poc`, `/speckit.discovery.techselect`, or `/speckit.discovery.codebase`. + + + +- Keep the output decision-oriented and evidence-backed. +- Do not turn the feasibility study into a full implementation plan. +- Do not invent requirements beyond the user's input, repository context, and explicitly stated assumptions. +- Clearly separate facts, assumptions, risks, and recommendations. +- Preserve existing file structure and unrelated content. + diff --git a/extensions/discovery/commands/poc.md b/extensions/discovery/commands/poc.md new file mode 100644 index 0000000000..53fbc23682 --- /dev/null +++ b/extensions/discovery/commands/poc.md @@ -0,0 +1,106 @@ +--- +name: speckit.discovery.poc +description: Derive a bounded-scope proof-of-concept and run it only when execution preconditions are met. +argument-hint: "[user stories] [use cases] [core design idea]" +--- + + +You are a proof-of-concept facilitator for Spec Kit projects. Your job is to turn a discovery assumption into a minimal-scope executable validation before formal planning, then report evidence and a classified conclusion. + + + +Use this command during the Discovery extension workflow when the user wants to validate a feasibility, technology selection, or legacy integration assumption with minimal-scope disposable code or scripts. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: +- User stories: what the user wants to accomplish. +- Use cases: key scenarios or typical flows to exercise. +- Core design idea: the user's proposed algorithm, technical path, architecture idea, or implementation approach. +- Discovery assumption: the specific feasibility, selection, or codebase risk assumption to validate. + +Minimum required input: + +```yaml +poc_minimum_inputs: + user_stories: + description: User stories that explain what the user wants to accomplish. + required: true + use_cases: + description: Key use cases or representative flows. + required: true + core_design_idea: + description: The proposed algorithm, technical path, architecture idea, or implementation approach. + required: true +``` + +The user does not need to provide a full product specification, final architecture, interface contracts, complete data model, implementation task list, success criteria, sample inputs, or constraints up front. + +Infer optional fields only from repository context and conversation, and label all inferred values as assumptions. If one of the three minimum inputs is absent and cannot be derived from explicit context, ask one concise clarifying question before designing the experiment. + + + +1. Normalize the bounded-scope input into: + - User stories. + - Use cases. + - Core design idea. + +2. Derive the POC validation frame from those inputs: + - Validation question. + - Hypothesis. + - Success criteria. + - Minimal executable experiment. + - Sample inputs. + - Expected observations. + - Risk focus. + +3. Define one single-hypothesis POC using this format: + - "We believe [approach] will satisfy [requirement] under [constraint]. We will know this is true when [observable evidence]." + +4. Create or update `poc-plan.md` by rendering `templates/poc-plan.md`. Prefer the active feature directory when it exists. Otherwise create it under a bounded-scope discovery workspace such as `discovery//poc-plan.md`. This command is responsible for validation framing, execution precondition classification, result classification, and template field population. + +5. Create a runnable validation artifact only when the validation question cannot be answered by static evidence. Prefer reversible artifacts: scripts, probes, mocks, toy datasets, disposable adapters, or minimal integration checks. Place executable POC code or scripts under `discovery//poc/` unless the repository has a clearer convention. + +6. Run the minimum experiment only when all execution preconditions are true: + - Required dependencies are installed or already declared by the repository. + - Commands are read-only or confined to the POC workspace. + - Inputs are synthetic fixtures or explicitly approved by the user in the current conversation. + - No production data, live write APIs, external side effects, or real secrets are used. + - Expected runtime is under 5 minutes. + + Stop at the first failed precondition, skip execution, set `Result` to `inconclusive`, and record the blocking condition. When execution proceeds, capture evidence logs, command outputs, screenshots, generated files, or metrics that directly support the conclusion. + +7. Create or update `poc-result.md` beside `poc-plan.md` by rendering `templates/poc-result.md` from captured evidence and the classified result. + +8. Set `Result` to exactly one of: + - `passed` + - `failed` + - `inconclusive` + +9. Summarize the result for the user: + - Files created or modified. + - Validation question. + - Hypothesis. + - Success criteria. + - Evidence captured. + - Result: `passed`, `failed`, or `inconclusive`. + + + +- POC input must stay bounded-scope: user stories, use cases, and core design idea are enough to start. +- POC output must be evidence-backed: always produce a plan, and produce a runnable validation artifact only when static evidence is insufficient and execution preconditions are met. Always record evidence or blocking conditions and a conclusion. +- Derive success criteria, sample inputs, expected observations, constraints, and risk focus unless the user already provided them. +- Do not require a full product specification, final architecture, interface contracts, complete data model, or implementation task list up front. +- Keep the POC smaller than the full implementation and limited to one key feasibility question. +- Do not implement production code unless the user explicitly asks for it. +- Do not invent product requirements beyond the user stories, use cases, core design idea, repository context, or explicit user input. +- Preserve existing file structure and unrelated content. +- Prefer reversible artifacts: docs, spike branches, throwaway scripts, mocks, or minimal integration probes. +- If writing code is necessary for the POC, place it where the repository conventions indicate and clearly mark it as experimental. + diff --git a/extensions/discovery/commands/techselect.md b/extensions/discovery/commands/techselect.md new file mode 100644 index 0000000000..92f48b4370 --- /dev/null +++ b/extensions/discovery/commands/techselect.md @@ -0,0 +1,65 @@ +--- +name: speckit.discovery.techselect +description: Build a technology selection matrix for candidate tools, libraries, platforms, or architectures. +argument-hint: "[decision to make] [candidate options] [criteria or constraints]" +--- + + +You are a technology selection facilitator for Spec Kit projects. Your job is to compare candidate technologies with explicit criteria, evidence, trade-offs, and a clear recommendation. + + + +Use this command during the Discovery extension workflow when the user needs to decide between competing implementation approaches, tools, libraries, vendors, platforms, data stores, frameworks, or architecture patterns. + + + +Raw user input: + +```text +$ARGUMENTS +``` + +The user may provide: +- Decision: what technology choice must be made. +- Candidate options: options already under consideration. +- Criteria: evaluation dimensions such as fit, complexity, performance, maintainability, cost, licensing, team familiarity, ecosystem maturity, security, portability, or operational burden. + +Infer optional candidates or criteria only from repository constraints and the user's stated goal. Label inferred criteria as assumptions. Ask one concise clarifying question when the selection decision itself cannot be framed. + + + +1. Normalize the selection problem into: + - Decision statement. + - Evaluation mode: `comparison` or `single-approach-readiness`. + - Candidate options. + - Constraints. + - Evaluation criteria. + - Weighting assumptions. + +2. Evaluate each option against the criteria using evidence from: + - Repository context. + - Existing dependencies and architecture. + - Known constraints. + - Evidence gaps that require a separate PoC or benchmark. + - Public documentation only when current external facts are required. + +3. Create or update `tech-selection-matrix.md` by rendering `templates/tech-selection-matrix.md`. Prefer the active feature directory when it exists. Otherwise create it under `discovery//tech-selection-matrix.md`. This command is responsible for selection framing, evidence classification, recommendation classification, and template field population only. + +4. Populate the Technology Selection Matrix template with one row per candidate and one evidence-backed rating per criterion. + +5. Recommend one of: + - A selected option. + - A short-listed set that needs PoC validation. + - No selection yet because the evidence is insufficient. + +6. Do not run experiments in this command. If executable evidence is required, record the evidence gap and recommend `/speckit.discovery.poc`. + + + +- Make criteria explicit before scoring. +- Do not hide subjective judgments; label them as assumptions. +- Do not overfit the recommendation to novelty or personal preference. +- Prefer existing project conventions and operational simplicity when scores are close. +- In `comparison` mode, require two or more candidates. In `single-approach-readiness` mode, evaluate the single approach against acceptance criteria. +- Preserve existing file structure and unrelated content. + diff --git a/extensions/discovery/docs/usage.md b/extensions/discovery/docs/usage.md new file mode 100644 index 0000000000..2c9d20d3b5 --- /dev/null +++ b/extensions/discovery/docs/usage.md @@ -0,0 +1,138 @@ +# Usage + +Use the `discovery` extension before formal planning when a product idea, technical direction, technology choice, legacy integration, or scenario-specific technical decision risk has important unknowns. + +The extension provides six source-backed discovery commands: + +- `/speckit.discovery.feasibility`: feasibility study. +- `/speckit.discovery.techselect`: technology selection matrix. +- `/speckit.discovery.decision`: scenario-specific API, performance, migration, UX, or compatibility technical decision. +- `/speckit.discovery.codebase`: scope-located, evidence-graded legacy codebase assessment. +- `/speckit.discovery.codebase-api-imp`: source-backed implementation overview for an existing API or interface. +- `/speckit.discovery.poc`: proof-of-concept experiment. + +Think of the command set as four capability types: + +- `feasibility`: support a go/no-go continuation decision. +- `techselect`: compare general technology choices. +- `decision`: evaluate API, performance, migration, UX, and compatibility decisions with scenario-specific risks. +- `codebase`, `codebase-api-imp`, and `poc`: locate relevant source scope, gather source-backed evidence, record evidence levels and unknowns, explain implemented interface behavior, or run executable validation. + +PoC input should stay bounded-scope: + +- User stories: what the user wants to accomplish. +- Use cases: key scenarios or typical flows. +- Core design idea: the proposed algorithm, technical path, architecture idea, or implementation approach. + +The command derives the validation question, hypothesis, success criteria, minimal executable experiment, sample inputs, expected observations, and risk focus from those inputs. + +Good discovery candidates include: + +- A third-party API or SDK integration. +- A performance or scalability assumption. +- A UX interaction that may be difficult to implement cleanly. +- A storage, migration, or data modeling decision. +- A cross-platform compatibility risk. + +## Scenario-Specific Technical Decision Selection + +Use `/speckit.discovery.decision` when the user already knows the shape of the technical decision: + +| Situation | Decision type | Typical output | +|---|---|---| +| External API, SDK, webhook, SaaS, partner, or service dependency | `type: api` | `api-integration-discovery.md` | +| Latency, throughput, load, scalability, resource, or cost assumption | `type: performance` | `performance-discovery.md` | +| Schema, model, storage, backfill, import/export, or data migration risk | `type: migration` | `data-migration-discovery.md` | +| Complex interaction, stateful workflow, accessibility, responsive behavior, or handoff risk | `type: ux` | `ux-discovery.md` | +| Browser, OS, device, runtime, dependency, deployment, or version support risk | `type: compatibility` | `compatibility-discovery.md` | + +The command sets a type-specific `Planning Decision`. It sets `Evaluation Mode` to `comparison` when evaluating multiple candidates, or `single-approach-readiness` when evaluating one approach against acceptance criteria. Use follow-up commands only when the decision assessment recommends them. + +## Source-Backed Codebase Command Selection + +Use these commands when existing source facts affect planning: + +| Situation | Command | Typical output | +|---|---|---| +| Fuzzy existing module, reusable asset, integration hazard, or legacy risk | `/speckit.discovery.codebase` | `legacy-codebase-risk-assessment.md` | +| Existing API route, SDK method, topic, command, job, or capability implementation | `/speckit.discovery.codebase-api-imp` | `codebase-api-imp.md` | + +## Example + +Feasibility: + +```text +/speckit.discovery.feasibility Goal: Add webhook retry support. Constraints: Existing worker queue, no duplicate side effects, must ship in two weeks. Success: retries are reliable and auditable. +``` + +Technology selection: + +```text +/speckit.discovery.techselect Decision: choose search implementation. Candidates: SQLite FTS5, Meilisearch, Postgres full-text search. Criteria: local-first fit, setup cost, query quality, maintenance burden. +``` + +Legacy codebase assessment: + +```text +/speckit.discovery.codebase Target: webhook retry/delivery area, not sure exact module. Planned change: add retries. Concerns: idempotency, test coverage, existing event schema. +``` + +Codebase API implementation overview: + +```text +/speckit.discovery.codebase-api-imp Target: POST /webhooks/stripe. Concern: duplicate event handling and retry behavior. Scope: payment service. +``` + +PoC: + +```text +/speckit.discovery.poc US: Operators can retry failed webhook deliveries. UC: A duplicate retry should not create duplicate side effects. Core design idea: Use an idempotency key derived from provider event ID plus delivery attempt. +``` + +API integration: + +```text +/speckit.discovery.decision type: api Target: Stripe webhooks. Workflow: mark invoices paid after payment_succeeded. Risks: retries, duplicate events, signature verification, local replay tests. +``` + +Performance: + +```text +/speckit.discovery.decision type: performance Concern: search must respond under 200ms p95. Target flow: note search while typing. Load: 50k local notes and 10 concurrent queries. +``` + +Data migration: + +```text +/speckit.discovery.decision type: migration Change: split customer address into normalized table. Current: address JSON on customer records. Constraints: zero downtime, rollback within one release. +``` + +UX: + +```text +/speckit.discovery.decision type: ux Workflow: bulk edit selected records. Concern: partial failures, undo, keyboard access, and responsive toolbar behavior. Success: operators can recover from failed rows. +``` + +Compatibility: + +```text +/speckit.discovery.decision type: compatibility Target: Safari and Chromium browsers. Feature: offline note sync. Environments: latest two major versions on desktop and mobile. +``` + +PoC expected result: + +- A `poc-plan.md` file. +- A single-hypothesis validation question, hypothesis, success criteria, and minimal executable experiment. +- A small runnable PoC under `discovery//poc/` when executable evidence is required and execution preconditions are met. +- Evidence logs, outputs, screenshots, or metrics. +- A `poc-result.md` file with result set to `passed`, `failed`, or `inconclusive`. + +## Recommended Flow + +1. Run `/speckit.discovery.decision` when the decision shape is obvious, such as `type: api` or `type: performance`. +2. Run `/speckit.discovery.feasibility` when the main question is whether the idea supports a go/no-go continuation decision. +3. Run `/speckit.discovery.techselect` when a general technology choice needs an explicit comparison, or when `/speckit.discovery.decision` finds multiple tools or architectures that need broader comparison. +4. Run `/speckit.discovery.codebase` when the existing code scope is unclear, source facts may affect the plan, or unknowns need to be confirmed before planning. +5. Run `/speckit.discovery.codebase-api-imp` when the source scope is an existing API or interface and engineers need the implementation path, key branches, dependencies, exceptions, or runtime boundaries explained. +6. Run `/speckit.discovery.poc` when an assumption needs executable evidence. +7. Continue with `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` once discovery evidence is strong enough for formal planning. diff --git a/extensions/discovery/extension.yml b/extensions/discovery/extension.yml new file mode 100644 index 0000000000..05b00a6ff6 --- /dev/null +++ b/extensions/discovery/extension.yml @@ -0,0 +1,55 @@ +schema_version: "1.0" + +extension: + id: "discovery" + name: "Spec Kit Discovery Extension" + version: "0.2.0" + description: "Run technical discovery commands for feasibility, technology selection, scenario-specific technical decisions, legacy codebase assessment, implementation understanding, and proof-of-concept validation." + author: "bigsmartben" + repository: "https://github.com/bigsmartben/spec-kit-discovery" + license: "MIT" + homepage: "https://github.com/bigsmartben/spec-kit-discovery" + category: "process" + effect: "read-write" + +requires: + speckit_version: ">=0.1.0" + commands: + - "speckit.specify" + +provides: + commands: + - name: "speckit.discovery.feasibility" + file: "commands/feasibility.md" + description: "Produces an evidence-backed feasibility study for a product or technical direction." + - name: "speckit.discovery.techselect" + file: "commands/techselect.md" + description: "Builds a technology selection matrix for candidate tools, libraries, platforms, or architectures." + - name: "speckit.discovery.codebase" + file: "commands/codebase.md" + description: "Assesses legacy codebase risks, reusable assets, constraints, and integration hazards." + - name: "speckit.discovery.codebase-api-imp" + file: "commands/codebase-api-imp.md" + description: "Explains an implemented API or interface from repository facts for implementation understanding and defect localization." + - name: "speckit.discovery.poc" + file: "commands/poc.md" + description: "Derives a bounded-scope proof-of-concept and runs it only when execution preconditions are met." + - name: "speckit.discovery.decision" + file: "commands/decision.md" + description: "Evaluates a scenario-specific technical decision for API, performance, migration, UX, or compatibility risks before formal planning." + +tags: + - "discovery" + - "feasibility" + - "selection" + - "codebase" + - "api-implementation" + - "poc" + - "decision" + - "api" + - "performance" + - "migration" + - "ux" + - "compatibility" + - "workflow" + - "validation" diff --git a/extensions/discovery/templates/api-integration-discovery.md b/extensions/discovery/templates/api-integration-discovery.md new file mode 100644 index 0000000000..85dd31600a --- /dev/null +++ b/extensions/discovery/templates/api-integration-discovery.md @@ -0,0 +1,37 @@ +# API Integration Discovery + +## Decision Question + +## Evaluation Mode + +Allowed values: `comparison`, `single-approach-readiness`. + +## Scenario Context + +## Success Criteria + +## Candidate Approaches + +## Data Contract + +## Authentication and Authorization + +## Operational Constraints + +## Repository Findings + +## Provider Facts + +## Assumptions + +## Scenario Risks + +## Evidence Gaps + +## Validation Plan + +## Recommendation + +## Planning Decision + +Allowed values: `ready-for-planning`, `needs-poc`, `needs-provider-clarification`, `not-recommended`, `inconclusive`. diff --git a/extensions/discovery/templates/codebase-api-imp.md b/extensions/discovery/templates/codebase-api-imp.md new file mode 100644 index 0000000000..820194bc89 --- /dev/null +++ b/extensions/discovery/templates/codebase-api-imp.md @@ -0,0 +1,82 @@ +# Codebase API Implementation Overview + +## Input And Scope + +| Field | Value | +|---|---| +| Interface target | | +| Route/address/topic/command/method | | +| Functional description | | +| Known concern | | +| Source scope | | +| Output generated at | | + +## Interface Match + +| Candidate | Source area | Evidence | Level | Decision | +|---|---|---|---|---| + +Level values: `Proven`, `Framework inferred`, `Runtime dependent`, or `Unknown`. + +## Business Implementation Overview + +Summarize only repository-fact-backed behavior, process stages, important decisions, observable outcomes, and fact gaps. + +| Business/process point | Confirmed behavior | Related sequence or flow | Evidence | Level | +|---|---|---|---|---| + +## Service/System-Level Sequence + +Use this diagram for externally observable interaction only. Add a Mermaid `sequenceDiagram` only when source evidence supports the participants and messages. Otherwise state `Not identified from scoped repository facts`. + +Not identified from scoped repository facts. + +## Module/Component-Level Sequence + +Use source-visible module, class, handler, configuration, component, or external-system names. Reference flowcharts from messages when details need expansion. Add a Mermaid `sequenceDiagram` only when source evidence supports the participants and messages. + +Not identified from scoped repository facts. + +## Business Implementation Flowcharts + +Create Mermaid `flowchart TD` diagrams only for repository-backed branch, exception, data/dependency, async, transaction, fallback, runtime-boundary, or return-path detail. + +Not identified from scoped repository facts. + +## Key Branches And Diagnostic Map + +| Category | Business/process point | Related sequence or flow | Evidence | Level | Diagnostic use | +|---|---|---|---|---|---| + +Categories may include `business domain`, `branch`, `exception/fallback handling`, `data/dependency boundary`, `async/event boundary`, `return mapping`, or `runtime-dependent behavior`. + +## Call Chain And Edge Types + +| Message | Source area | Target area/system | Edge type | Evidence | Level | +|---|---|---|---|---|---| + +Edge type values may include `[direct]`, `[framework]`, `[middleware]`, `[aop]`, `[async]`, `[event]`, `[data]`, `[external]`, or `[runtime]`. + +## Data Access And External Dependencies + +| Dependency or state | Operation | Access point | Evidence | Level | +|---|---|---|---|---| + +## Exceptions, Fallbacks, And Runtime Boundaries + +| Area or system | Behavior | Evidence | Level | Notes | +|---|---|---|---|---| + +## Source References + +| ID | What this verifies | File | Lines or symbol | Level | +|---|---|---|---|---| + +## Unknowns And Runtime Verification + +| Question | Why source is insufficient | Suggested verification | +|---|---|---| + +## Follow-up Recommendation + +State whether the interface evidence is sufficient for planning, whether `/speckit.discovery.poc` is needed for executable validation, or whether the user should provide a narrower interface target or additional source scope. diff --git a/extensions/discovery/templates/compatibility-discovery.md b/extensions/discovery/templates/compatibility-discovery.md new file mode 100644 index 0000000000..5aaf85d92e --- /dev/null +++ b/extensions/discovery/templates/compatibility-discovery.md @@ -0,0 +1,37 @@ +# Compatibility Discovery + +## Decision Question + +## Evaluation Mode + +Allowed values: `comparison`, `single-approach-readiness`. + +## Scenario Context + +## Success Criteria + +## Candidate Approaches + +## Support Matrix + +## Repository Findings + +## Required Support + +## Optional Support + +## Scenario Risks + +## Test Matrix + +## Fallbacks or Degradation + +## Evidence Gaps + +## Validation Plan + +## Recommendation + +## Planning Decision + +Allowed values: `ready-for-planning`, `needs-matrix-test`, `needs-fallback-design`, `not-supported`, `inconclusive`. diff --git a/extensions/discovery/templates/data-migration-discovery.md b/extensions/discovery/templates/data-migration-discovery.md new file mode 100644 index 0000000000..1939b9a64f --- /dev/null +++ b/extensions/discovery/templates/data-migration-discovery.md @@ -0,0 +1,37 @@ +# Data Migration Discovery + +## Decision Question + +## Evaluation Mode + +Allowed values: `comparison`, `single-approach-readiness`. + +## Scenario Context + +## Success Criteria + +## Candidate Approaches + +## Current State + +## Affected Data and Flows + +## Migration Constraints + +## Repository Findings + +## Assumptions + +## Scenario Risks + +## Rollout and Rollback Notes + +## Evidence Gaps + +## Validation Plan + +## Recommendation + +## Planning Decision + +Allowed values: `ready-for-planning`, `needs-dry-run`, `needs-model-redesign`, `not-recommended`, `inconclusive`. diff --git a/extensions/discovery/templates/feasibility.md b/extensions/discovery/templates/feasibility.md new file mode 100644 index 0000000000..9549bbc999 --- /dev/null +++ b/extensions/discovery/templates/feasibility.md @@ -0,0 +1,25 @@ +# Feasibility Study + +## Goal + +## Context + +## Constraints + +## Assumptions + +## Existing Evidence + +## Evidence Gaps + +## Validation Needed + +## Risk Assessment + +## Open Questions + +## Recommendation + +## Decision + +Allowed values: `feasible`, `feasible-with-risks`, `not-feasible`, `inconclusive`. diff --git a/extensions/discovery/templates/legacy-codebase-risk-assessment.md b/extensions/discovery/templates/legacy-codebase-risk-assessment.md new file mode 100644 index 0000000000..ee174b95fd --- /dev/null +++ b/extensions/discovery/templates/legacy-codebase-risk-assessment.md @@ -0,0 +1,87 @@ +# Legacy Codebase Risk Assessment + +## Scope + +## Input Targets + +| ID | Input claim or concern | Verification question | Source hints | Status | +|---|---|---|---|---| + +Status values: `confirmed`, `partially-confirmed`, `not-found`, `runtime-dependent`, or `unknown`. + +## Scope Candidates + +Use this section when the target area is ambiguous. + +| Rank | Candidate area | Confidence | Evidence | Unknowns | +|---:|---|---|---|---| + +Confidence values: `high`, `medium`, `low`, or `unknown`. + +## Evidence Capabilities + +| Capability | Available evidence | Limitations | +|---|---|---| + +## Codebase Map + +## Source Facts + +### Entrances + +| Type | Trigger or route | Handler or source area | Evidence | Confidence | +|---|---|---|---|---| + +### Module Boundaries + +| Module or area | Responsibility | Upstream | Downstream | Evidence | Confidence | +|---|---|---|---|---|---| + +### Dependency Edges + +| Kind | Source | Target | Evidence | Confidence | +|---|---|---|---|---| + +### Data Access + +| Data or state | Operation | Access point | Evidence | Confidence | +|---|---|---|---|---| + +### External Dependencies + +| Dependency | Call point | Protocol or method | Failure handling | Evidence | +|---|---|---|---|---| + +## Reusable Assets + +## Risks + +Rate each risk as `low`, `medium`, `high`, or `unknown`. + +| Risk | Rating | Source facts | Impact | Mitigation or follow-up | +|---|---|---|---|---| + +## Test Coverage + +## Integration Notes + +## Migration Notes + +## Source Boundary Notes + +| Boundary | Source-visible fact | Not proven | Downstream suggestion | +|---|---|---|---| + +## Recommendations + +## Evidence Gaps + +| Gap | Why it remains unknown | Evidence needed | +|---|---|---| + +## Evidence Index + +| Claim | Evidence | Confidence | +|---|---|---| + +## Follow-up Validation diff --git a/extensions/discovery/templates/performance-discovery.md b/extensions/discovery/templates/performance-discovery.md new file mode 100644 index 0000000000..a6adf54c0b --- /dev/null +++ b/extensions/discovery/templates/performance-discovery.md @@ -0,0 +1,37 @@ +# Performance Discovery + +## Decision Question + +## Evaluation Mode + +Allowed values: `comparison`, `single-approach-readiness`. + +## Scenario Context + +## Success Criteria + +## Candidate Approaches + +## Target Flow + +## Workload Assumptions + +## Repository Findings + +## Current Evidence + +## Bottleneck Hypotheses + +## Measurement Plan + +## Evidence Gaps + +## Follow-up Validation Decision + +## Scenario Risks + +## Recommendation + +## Planning Decision + +Allowed values: `ready-for-planning`, `needs-benchmark`, `needs-design-change`, `not-feasible`, `inconclusive`. diff --git a/extensions/discovery/templates/poc-plan.md b/extensions/discovery/templates/poc-plan.md new file mode 100644 index 0000000000..cc6ed1fe72 --- /dev/null +++ b/extensions/discovery/templates/poc-plan.md @@ -0,0 +1,21 @@ +# Proof of Concept + +## Input + +## Validation Question + +## Hypothesis + +Use: `We believe [approach] will satisfy [requirement] under [constraint]. We will know this is true when [observable evidence].` + +## Success Criteria + +## Minimal Executable Experiment + +## Execution Preconditions + +## Sample Inputs + +## Expected Observations + +## Risk Focus diff --git a/extensions/discovery/templates/poc-result.md b/extensions/discovery/templates/poc-result.md new file mode 100644 index 0000000000..d904af92ad --- /dev/null +++ b/extensions/discovery/templates/poc-result.md @@ -0,0 +1,15 @@ +# POC Result + +## Experiment Run + +## Evidence + +## Observations + +## Blocking Conditions + +## Conclusion + +## Result + +Allowed values: `passed`, `failed`, `inconclusive`. diff --git a/extensions/discovery/templates/tech-selection-matrix.md b/extensions/discovery/templates/tech-selection-matrix.md new file mode 100644 index 0000000000..15b75fec57 --- /dev/null +++ b/extensions/discovery/templates/tech-selection-matrix.md @@ -0,0 +1,25 @@ +# Technology Selection Matrix + +## Decision + +## Evaluation Mode + +Allowed values: `comparison`, `single-approach-readiness`. + +## Candidates + +## Criteria + +## Matrix + +Use one row per candidate and one evidence-backed rating per criterion. + +## Trade-offs + +## Risks + +## Recommendation + +## Evidence Gaps + +## Follow-up Validation diff --git a/extensions/discovery/templates/ux-discovery.md b/extensions/discovery/templates/ux-discovery.md new file mode 100644 index 0000000000..904e69e273 --- /dev/null +++ b/extensions/discovery/templates/ux-discovery.md @@ -0,0 +1,37 @@ +# UX Discovery + +## Decision Question + +## Evaluation Mode + +Allowed values: `comparison`, `single-approach-readiness`. + +## Scenario Context + +## Success Criteria + +## Candidate Approaches + +## User Scenarios + +## States and Transitions + +## Edge Cases + +## Accessibility and Responsiveness + +## Repository Findings + +## Assumptions + +## Scenario Risks + +## Evidence Gaps + +## Validation Plan + +## Recommendation + +## Planning Decision + +Allowed values: `ready-for-planning`, `needs-prototype`, `needs-contract-clarification`, `not-recommended`, `inconclusive`. diff --git a/pyproject.toml b/pyproject.toml index 08c6ce70f3..fe723fab49 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,6 +41,7 @@ packages = ["src/specify_cli"] # Bundled extensions (installable via `specify extension add `) "extensions/catalog.json" = "specify_cli/core_pack/extensions/catalog.json" "extensions/arch" = "specify_cli/core_pack/extensions/arch" +"extensions/discovery" = "specify_cli/core_pack/extensions/discovery" "extensions/git" = "specify_cli/core_pack/extensions/git" "extensions/preview" = "specify_cli/core_pack/extensions/preview" "extensions/repository-governance" = "specify_cli/core_pack/extensions/repository-governance" diff --git a/src/specify_cli/commands/init.py b/src/specify_cli/commands/init.py index 42c291f5b5..4f7c1e0c14 100644 --- a/src/specify_cli/commands/init.py +++ b/src/specify_cli/commands/init.py @@ -26,7 +26,7 @@ from .._console import StepTracker, console, select_with_arrows, show_banner from .._utils import check_tool -DEFAULT_BUNDLED_EXTENSIONS = ("arch", "preview", "repository-governance") +DEFAULT_BUNDLED_EXTENSIONS = ("arch", "discovery", "preview", "repository-governance") DEFAULT_BUNDLED_PRESETS = ("workflow-preset",) diff --git a/tests/integrations/community_defaults.py b/tests/integrations/community_defaults.py index 40ce5191da..755c88c6f2 100644 --- a/tests/integrations/community_defaults.py +++ b/tests/integrations/community_defaults.py @@ -9,10 +9,16 @@ from specify_cli.integrations import get_integration REPO_ROOT = Path(__file__).resolve().parents[2] -DEFAULT_EXTENSION_IDS = ("arch", "preview", "repository-governance") +DEFAULT_EXTENSION_IDS = ("arch", "discovery", "preview", "repository-governance") DEFAULT_EXTENSION_COMMANDS = ( "speckit.arch.generate", "speckit.arch.reverse", + "speckit.discovery.feasibility", + "speckit.discovery.techselect", + "speckit.discovery.codebase", + "speckit.discovery.codebase-api-imp", + "speckit.discovery.poc", + "speckit.discovery.decision", "speckit.preview.low-md", "speckit.preview.low-html", "speckit.preview.mid-md", diff --git a/tests/integrations/test_cli.py b/tests/integrations/test_cli.py index 86b7c22395..a69d2bda2f 100644 --- a/tests/integrations/test_cli.py +++ b/tests/integrations/test_cli.py @@ -820,7 +820,7 @@ def test_community_extensions_and_workflow_preset_auto_installed(self, tmp_path) assert result.exit_code == 0, f"init failed: {result.output}" - for extension_id in ("arch", "preview", "repository-governance"): + for extension_id in ("arch", "discovery", "preview", "repository-governance"): ext_dir = project / ".specify" / "extensions" / extension_id assert (ext_dir / "extension.yml").exists(), f"{extension_id} was not installed" @@ -829,6 +829,7 @@ def test_community_extensions_and_workflow_preset_auto_installed(self, tmp_path) assert hooks_data["installed"] == [ "agent-context", "arch", + "discovery", "preview", "repository-governance", ] @@ -924,7 +925,7 @@ def test_no_git_keeps_community_defaults(self, tmp_path): assert result.exit_code == 0, f"init failed: {result.output}" assert not (project / ".specify" / "extensions" / "git").exists() - for extension_id in ("arch", "preview", "repository-governance"): + for extension_id in ("arch", "discovery", "preview", "repository-governance"): ext_dir = project / ".specify" / "extensions" / extension_id assert (ext_dir / "extension.yml").exists(), f"{extension_id} was not installed" diff --git a/tests/test_arch_templates.py b/tests/test_arch_templates.py index cc8cff3bc6..8f47737310 100644 --- a/tests/test_arch_templates.py +++ b/tests/test_arch_templates.py @@ -119,7 +119,7 @@ def test_init_next_steps_do_not_list_arch_as_core_workflow(): ) assert "_display_cmd('arch')" not in init_source - assert 'DEFAULT_BUNDLED_EXTENSIONS = ("arch", "preview", "repository-governance")' in init_source + assert 'DEFAULT_BUNDLED_EXTENSIONS = ("arch", "discovery", "preview", "repository-governance")' in init_source assert "specify extension add arch" not in init_source diff --git a/tests/test_presets.py b/tests/test_presets.py index a36bc7c2ed..a3a0e1c77e 100644 --- a/tests/test_presets.py +++ b/tests/test_presets.py @@ -4530,7 +4530,7 @@ def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): "speckit.design.visual-item-matrix.v1.schema.json" ) in verify_run assert ( - 'for extension_id in arch preview repository-governance; do' + 'for extension_id in arch discovery preview repository-governance; do' in verify_run ) assert ( @@ -4539,6 +4539,7 @@ def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): ) assert "test ! -d .claude/skills/speckit-arch-generate" in verify_run assert "test ! -d .claude/skills/speckit-arch-reverse" in verify_run + assert "find .claude/skills -maxdepth 1 -type d -name 'speckit-discovery-*'" in verify_run for preview_skill in ( "speckit-preview-low-md", "speckit-preview-low-html", @@ -4563,6 +4564,15 @@ def test_community_smoke_checks_wheel_assets_and_extension_dev_reinstall(self): 'test -f .claude/skills/speckit-arch-generate/SKILL.md' in verify_run ) + assert ( + 'test -f .claude/skills/speckit-discovery-feasibility/SKILL.md' + in verify_run + ) + assert "specify extension add discovery" in verify_run + assert ( + 'test -f .claude/skills/speckit-discovery-decision/SKILL.md' + in verify_run + ) assert ( 'test -f .claude/skills/speckit-repository-governance-refresh/SKILL.md' in verify_run