diff --git a/AGENTS.md b/AGENTS.md index eb3d27065f..3b9d4a7c95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,7 +107,7 @@ Also update any function docstrings, examples, and error messages that list avai #### 3. Update README Documentation -Update the **Supported AI Agents** section in `README.md` to include the new agent: +Update the **Supported AI Tools** section in `README.md` to include the new tool: - Add the new agent to the table with appropriate support level (Full/Partial) - Include the agent's official website link diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9044ef5ff9..9220cf9873 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ These are one time installations required to be able to test your changes locall 1. Install [Python 3.11+](https://www.python.org/downloads/) 1. Install [uv](https://docs.astral.sh/uv/) for package management 1. Install [Git](https://git-scm.com/downloads) -1. Have an [AI coding agent available](README.md#-supported-ai-agents) +1. Have an [AI coding tool available](README.md#-supported-ai-tools)
πŸ’‘ Hint if you are using VSCode or GitHub Codespaces as your IDE diff --git a/README.md b/README.md index 462c24c05d..f52ac154e5 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ - [🎨 Community Presets](#-community-presets) - [🚢 Community Walkthroughs](#-community-walkthroughs) - [πŸ› οΈ Community Friends](#️-community-friends) -- [πŸ€– Supported AI Agents](#-supported-ai-agents) +- [πŸ€– Supported AI Tools](#-supported-ai-tools) - [πŸ”§ Specify CLI Reference](#-specify-cli-reference) - [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets) - [πŸ“š Core Philosophy](#-core-philosophy) @@ -260,9 +260,9 @@ Community projects that extend, visualize, or build on Spec Kit: - **[Spec Kit Assistant](https://marketplace.visualstudio.com/items?itemName=rfsales.speckit-assistant)** β€” A VS Code extension that provides a visual orchestrator for the full SDD workflow (constitution β†’ specification β†’ planning β†’ tasks β†’ implementation) with phase status visualization, an interactive task checklist, DAG visualization, and support for Claude, Gemini, GitHub Copilot, and OpenAI backends. Requires the `specify` CLI in your PATH. -## πŸ€– Supported AI Agents +## πŸ€– Supported AI Tools -| Agent | Support | Notes | +| Tool | Support | Notes | | ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Qoder CLI](https://qoder.com/cli) | βœ… | | | [Kiro CLI](https://kiro.dev/docs/cli/) | βœ… | Use `--ai kiro-cli` (alias: `--ai kiro`) | @@ -543,7 +543,7 @@ Our research and experimentation focus on: ## πŸ”§ Prerequisites - **Linux/macOS/Windows** -- [Supported](#-supported-ai-agents) AI coding agent. +- [Supported](#-supported-ai-tools) AI coding tool. - [uv](https://docs.astral.sh/uv/) for package management - [Python 3.11+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) diff --git a/docs/upgrade.md b/docs/upgrade.md index cd5cc124fe..f65aaf7a2f 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -9,7 +9,7 @@ | What to Upgrade | Command | When to Use | |----------------|---------|-------------| | **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | Get latest CLI features without touching project files | -| **Project Files** | `specify init --here --force --ai ` | Update slash commands, templates, and scripts in your project | +| **Project Files** | `specify init --here --force --ai ` | Update slash commands, templates, and scripts in your project | | **Both** | Run CLI upgrade, then project update | Recommended for major version updates | --- @@ -73,10 +73,10 @@ The `specs/` directory is completely excluded from template packages and will ne Run this inside your project directory: ```bash -specify init --here --force --ai +specify init --here --force --ai ``` -Replace `` with your AI assistant. Refer to this list of [Supported AI Agents](../README.md#-supported-ai-agents) +Replace `` with your AI tool. Refer to this list of [Supported AI Tools](../README.md#-supported-ai-tools) **Example:** diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index 698b672dab..daee264ef7 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -1378,6 +1378,15 @@ def scaffold_from_core_pack( if f.is_file(): shutil.copy2(f, tmpl_root / f.name) + # Copy compact templates subdirectory + compact_src = templates_dir / "compact" + if compact_src.is_dir(): + compact_dst = tmpl_root / "compact" + compact_dst.mkdir(parents=True, exist_ok=True) + for f in compact_src.iterdir(): + if f.is_file(): + shutil.copy2(f, compact_dst / f.name) + # Scripts (bash/ and powershell/) for subdir in ("bash", "powershell"): src = scripts_dir / subdir @@ -1509,7 +1518,17 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None = def ensure_constitution_from_template(project_path: Path, tracker: StepTracker | None = None) -> None: """Copy constitution template to memory if it doesn't exist (preserves existing constitution on reinitialization).""" memory_constitution = project_path / ".specify" / "memory" / "constitution.md" - template_constitution = project_path / ".specify" / "templates" / "constitution-template.md" + + # Choose template based on format preference + init_opts = load_init_options(project_path) + fmt = init_opts.get("format", "markdown") + if fmt == "compact": + template_constitution = project_path / ".specify" / "templates" / "compact" / "constitution-template.md" + if not template_constitution.exists(): + # Fallback to standard template + template_constitution = project_path / ".specify" / "templates" / "constitution-template.md" + else: + template_constitution = project_path / ".specify" / "templates" / "constitution-template.md" # If constitution already exists in memory, preserve it if memory_constitution.exists(): @@ -1542,6 +1561,23 @@ def ensure_constitution_from_template(project_path: Path, tracker: StepTracker | console.print(f"[yellow]Warning: Could not initialize constitution: {e}[/yellow]") +def resolve_template_path(project_path: Path, template_name: str) -> Path: + """Resolve a template file path based on the configured format preference. + + When format is 'compact', looks for the template in the compact/ subdirectory + first. Falls back to the standard template if compact variant is not found. + """ + init_opts = load_init_options(project_path) + fmt = init_opts.get("format", "markdown") + + if fmt == "compact": + compact_path = project_path / ".specify" / "templates" / "compact" / template_name + if compact_path.exists(): + return compact_path + + return project_path / ".specify" / "templates" / template_name + + INIT_OPTIONS_FILE = ".specify/init-options.json" @@ -1906,6 +1942,7 @@ def init( offline: bool = typer.Option(False, "--offline", help="Use assets bundled in the specify-cli package instead of downloading from GitHub (no network access required). Bundled assets will become the default in v0.6.0 and this flag will be removed."), preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"), branch_numbering: str = typer.Option(None, "--branch-numbering", help="Branch numbering strategy: 'sequential' (001, 002, ...) or 'timestamp' (YYYYMMDD-HHMMSS)"), + template_format: str = typer.Option(None, "--format", help="Template format: 'markdown' (full verbose) or 'compact' (token-efficient minimal format)"), integration: str = typer.Option(None, "--integration", help="Use the new integration system (e.g. --integration copilot). Mutually exclusive with --ai."), ): """ @@ -2019,6 +2056,11 @@ def init( console.print(f"[red]Error:[/red] Invalid --branch-numbering value '{branch_numbering}'. Choose from: {', '.join(sorted(BRANCH_NUMBERING_CHOICES))}") raise typer.Exit(1) + TEMPLATE_FORMAT_CHOICES = {"markdown", "compact"} + if template_format and template_format not in TEMPLATE_FORMAT_CHOICES: + console.print(f"[red]Error:[/red] Invalid --format value '{template_format}'. Choose from: {', '.join(sorted(TEMPLATE_FORMAT_CHOICES))}") + raise typer.Exit(1) + if here: project_name = Path.cwd().name project_path = Path.cwd() @@ -2375,6 +2417,7 @@ def init( "ai_skills": ai_skills, "ai_commands_dir": ai_commands_dir, "branch_numbering": branch_numbering or "sequential", + "format": template_format or "markdown", "here": here, "preset": preset, "offline": offline, diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.py index 4a8c2d1b29..20bbebd6c2 100644 --- a/src/specify_cli/agents.py +++ b/src/specify_cli/agents.py @@ -171,6 +171,16 @@ class CommandRegistrar: } } + @staticmethod + def _get_template_format(project_root: Path) -> str: + """Read the template format preference from init-options.json.""" + try: + from . import load_init_options + except ImportError: + return "markdown" + opts = load_init_options(project_root) + return opts.get("format", "markdown") if isinstance(opts, dict) else "markdown" + @staticmethod def parse_frontmatter(content: str) -> tuple[dict, str]: """Parse YAML frontmatter from Markdown content. @@ -490,11 +500,20 @@ def register_commands( registered = [] + # Determine template format preference from init options + template_format = self._get_template_format(project_root) + for cmd_info in commands: cmd_name = cmd_info["name"] cmd_file = cmd_info["file"] + # Use compact command template if format is compact and compact variant exists source_file = source_dir / cmd_file + if template_format == "compact": + compact_file = source_dir / "compact" / cmd_file + if compact_file.exists(): + source_file = compact_file + if not source_file.exists(): continue diff --git a/templates/commands/compact/analyze.md b/templates/commands/compact/analyze.md new file mode 100644 index 0000000000..889bd5fd61 --- /dev/null +++ b/templates/commands/compact/analyze.md @@ -0,0 +1,54 @@ +--- +description: Non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Constraints + +**READ-ONLY**: Never modify files. Output structured analysis report only. +**Constitution** (`/memory/constitution.md`) is non-negotiable - conflicts are always CRITICAL. + +## Workflow + +1. Run `{SCRIPT}`, parse FEATURE_DIR. Derive SPEC, PLAN, TASKS paths. Abort if any missing. + +2. **Load** minimal context from each artifact: + - spec.md: requirements, success criteria, user stories, edge cases + - plan.md: architecture, data model, phases, constraints + - tasks.md: IDs, descriptions, phases, [P] markers, file paths + - constitution: principles, MUST/SHOULD statements + +3. **Build models**: Requirements inventory (FR-###, SC-###), user story/action inventory, task coverage mapping, constitution rule set. + +4. **Detection passes** (max 50 findings): + - A. **Duplication**: near-duplicate requirements + - B. **Ambiguity**: vague terms without metrics, unresolved placeholders + - C. **Underspecification**: missing outcomes, unaligned stories, undefined references + - D. **Constitution alignment**: MUST principle violations, missing mandated sections + - E. **Coverage gaps**: requirements with zero tasks, orphan tasks, unbuildable success criteria + - F. **Inconsistency**: terminology drift, entity mismatches, ordering contradictions + +5. **Severity**: CRITICAL (constitution violation, zero-coverage blocking req) > HIGH (conflicts, ambiguous security/perf) > MEDIUM (terminology drift, missing NFR tasks) > LOW (style, minor redundancy) + +6. **Report** (markdown, no file writes): + + | ID | Category | Severity | Location(s) | Summary | Recommendation | + |----|----------|----------|-------------|---------|----------------| + + + Coverage summary table + Constitution issues + Unmapped tasks + Metrics (total reqs, tasks, coverage%, ambiguity/duplication/critical counts) + +7. **Next actions**: If CRITICAL β†’ resolve before `/speckit.implement`. If LOW/MEDIUM β†’ may proceed with suggestions. + +8. **Offer remediation**: Ask user if they want concrete edit suggestions for top N issues (don't apply automatically). + +Context: {ARGS} diff --git a/templates/commands/compact/checklist.md b/templates/commands/compact/checklist.md new file mode 100644 index 0000000000..e554a6b859 --- /dev/null +++ b/templates/commands/compact/checklist.md @@ -0,0 +1,49 @@ +--- +description: Generate a custom checklist for the current feature - "unit tests for requirements writing". +scripts: + sh: scripts/bash/check-prerequisites.sh --json + ps: scripts/powershell/check-prerequisites.ps1 -Json +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Core Concept + +Checklists are **unit tests for requirements** - they validate quality, clarity, and completeness of requirements, NOT implementation behavior. + +- YES: "Are visual hierarchy requirements defined?" / "Is 'fast' quantified with metrics?" +- NO: "Verify button clicks" / "Test error handling works" + +## Workflow + +1. **Setup**: Run `{SCRIPT}`, parse FEATURE_DIR and AVAILABLE_DOCS. + +2. **Clarify intent**: Generate up to 3 contextual questions from user phrasing + spec signals (scope, depth, audience, risk). Skip if already clear from $ARGUMENTS. May ask 2 follow-ups if gaps remain (max 5 total). + +3. **Load context**: Read spec.md, plan.md (if exists), tasks.md (if exists) - only relevant portions. + +4. **Generate checklist**: + - Create `FEATURE_DIR/checklists/[domain].md` + - If exists: append continuing from last CHK ID. Never delete existing content. + - Group by: Completeness, Clarity, Consistency, Measurability, Coverage, Edge Cases, NFRs, Dependencies, Ambiguities + - Each item: question format about requirement quality with [dimension] tag + - Include traceability refs: `[Spec Β§X.Y]`, `[Gap]`, `[Ambiguity]`, `[Conflict]` + - Soft cap: 40 items, merge near-duplicates, consolidate low-impact edge cases + +5. **Report**: Path, item count, focus areas, whether created or appended. + +## Item Format + +``` +- [ ] CHK### Are [requirement type] defined/specified for [scenario]? [Dimension, Spec Β§X.Y] +``` + +Patterns: "Are X defined?" / "Is X quantified?" / "Are X consistent between A and B?" / "Can X be measured?" / "Does spec define X?" + +Prohibited: "Verify", "Test", "Confirm" + implementation behavior / "Displays correctly" / "Click", "navigate", "render" diff --git a/templates/commands/compact/clarify.md b/templates/commands/compact/clarify.md new file mode 100644 index 0000000000..253dab0e02 --- /dev/null +++ b/templates/commands/compact/clarify.md @@ -0,0 +1,52 @@ +--- +description: Identify underspecified areas in feature spec, ask up to 5 targeted clarification questions, encode answers back into spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +scripts: + sh: scripts/bash/check-prerequisites.sh --json --paths-only + ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Workflow + +1. Run `{SCRIPT}`, parse FEATURE_DIR and FEATURE_SPEC. Abort if JSON fails. + +2. **Scan spec** using taxonomy (mark Clear/Partial/Missing): + - Functional scope, domain/data model, UX flow, non-functional (perf/scale/security/observability), integrations, edge cases, constraints, terminology, completion signals, placeholders + +3. **Generate max 5 questions** (prioritized by Impact*Uncertainty): + - Must be answerable via multiple-choice (2-5 options) or short answer (<=5 words) + - Only include if answer materially impacts architecture, testing, UX, or compliance + - Balance category coverage + +4. **Ask one at a time**: + - Multiple-choice: show **Recommended** option with reasoning + options table. User can pick letter, say "yes"/"recommended", or custom answer + - Short-answer: show **Suggested** answer. User can accept or provide own + - Stop when: all resolved, user signals done, or 5 questions asked + +5. **Integrate each answer** immediately: + - Add `## Clarifications` > `### Session YYYY-MM-DD` if missing + - Append `- Q: β†’ A: ` + - Update appropriate spec section (requirements, stories, data model, success criteria, edge cases) + - Replace obsolete statements, save after each integration + +6. **Validate**: No duplicates, <=5 questions, no lingering placeholders, consistent terminology. + +7. **Report**: Questions asked/answered, path to updated spec, sections touched, coverage summary, next command suggestion. + +## Rules + +- Never exceed 5 questions | Present one at a time | Never reveal future questions +- If no ambiguities: report "No critical ambiguities" and suggest proceeding +- If spec missing: instruct to run `/speckit.specify` first +- Respect early termination ("done", "stop", "proceed") diff --git a/templates/commands/compact/constitution.md b/templates/commands/compact/constitution.md new file mode 100644 index 0000000000..e38b807e90 --- /dev/null +++ b/templates/commands/compact/constitution.md @@ -0,0 +1,41 @@ +--- +description: Create or update project constitution from interactive or provided principle inputs. +handoffs: + - label: Build Specification + agent: speckit.specify + prompt: Implement the feature specification based on the updated constitution. I want to build... +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Workflow + +1. **Load** `.specify/memory/constitution.md`. Identify all `[PLACEHOLDER]` tokens. Respect user's desired principle count. + +2. **Collect values**: From user input, repo context, or inference. Version: semver (MAJOR=breaking, MINOR=additions, PATCH=clarifications). LAST_AMENDED_DATE=today if changes made. + +3. **Draft**: Replace all placeholders with concrete text. Each principle: name + non-negotiable rules + rationale. Governance: amendment procedure + versioning + compliance expectations. + +4. **Propagate**: Check alignment with plan-template.md, spec-template.md, tasks-template.md, commands/*.md. Update references if needed. + +5. **Sync Report**: Add HTML comment at top: version change, modified/added/removed sections, templates needing updates. + +6. **Validate**: No unexplained brackets, version matches report, dates ISO, principles are declarative+testable (MUST/SHOULD not vague "should"). + +7. **Write** to `.specify/memory/constitution.md`. + +8. **Report**: Version + bump rationale, files needing follow-up, suggested commit message. + +## Rules + +- Use exact template heading hierarchy +- Single blank line between sections +- If partial updates: still validate and version-decide +- Missing info: insert `TODO(): explanation` +- Always operate on existing file, never create new template diff --git a/templates/commands/compact/implement.md b/templates/commands/compact/implement.md new file mode 100644 index 0000000000..cb165d063f --- /dev/null +++ b/templates/commands/compact/implement.md @@ -0,0 +1,49 @@ +--- +description: Execute implementation plan by processing all tasks in tasks.md. +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Pre-Execution + +Check `.specify/extensions.yml` for `hooks.before_implement`. Run mandatory hooks, show optional. Skip silently if missing/invalid. + +## Workflow + +1. Run `{SCRIPT}`, parse FEATURE_DIR and AVAILABLE_DOCS. + +2. **Check checklists** (if FEATURE_DIR/checklists/ exists): + - Count total/completed/incomplete items per checklist + - If incomplete: show status table, ask user to confirm proceeding + - If all pass: auto-proceed + +3. **Load context**: tasks.md (required), plan.md (required), data-model.md, contracts/, research.md, quickstart.md (if exist). + +4. **Setup verification**: Create/verify ignore files (.gitignore, .dockerignore, etc.) based on detected tech stack from plan.md. Append missing patterns to existing files, create full set for missing files. + +5. **Parse tasks.md**: Extract phases, dependencies, task details, parallel markers [P]. + +6. **Execute phase-by-phase**: + - Setup β†’ Tests (if any) β†’ Core β†’ Integration β†’ Polish + - Sequential tasks in order, [P] tasks can run together + - Mark completed tasks as `[X]` in tasks.md + - Report progress after each task + - Halt on non-parallel task failure, continue others for [P] failures + +7. **Validate**: All tasks complete, features match spec, tests pass. + +8. Check `.specify/extensions.yml` for `hooks.after_implement`. Run mandatory, show optional. Skip silently if missing. + +## Rules + +- If tasks.md incomplete/missing: suggest `/speckit.tasks` first +- Provide clear error messages with debugging context diff --git a/templates/commands/compact/plan.md b/templates/commands/compact/plan.md new file mode 100644 index 0000000000..e59fd334e2 --- /dev/null +++ b/templates/commands/compact/plan.md @@ -0,0 +1,65 @@ +--- +description: Execute implementation planning workflow to generate design artifacts. +handoffs: + - label: Create Tasks + agent: speckit.tasks + prompt: Break the plan into tasks + send: true + - label: Create Checklist + agent: speckit.checklist + prompt: Create a checklist for the following domain... +scripts: + sh: scripts/bash/setup-plan.sh --json + ps: scripts/powershell/setup-plan.ps1 -Json +agent_scripts: + sh: scripts/bash/update-agent-context.sh __AGENT__ + ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__ +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Pre-Execution + +Check `.specify/extensions.yml` for `hooks.before_plan`. Run mandatory hooks, show optional. Skip silently if missing/invalid. + +## Workflow + +1. **Setup**: Run `{SCRIPT}` from repo root, parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. + +2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template. + +3. **Execute plan**: + - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION") + - Fill Constitution Check from constitution, evaluate gates (ERROR if violations unjustified) + - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION) + - Phase 1: Generate data-model.md, contracts/, quickstart.md + - Run `{AGENT_SCRIPT}` to update agent context + - Re-evaluate Constitution Check post-design + +4. **Report**: Branch, IMPL_PLAN path, generated artifacts. + +5. Check `.specify/extensions.yml` for `hooks.after_plan`. Run mandatory, show optional. Skip silently if missing. + +## Phases + +### Phase 0: Research + +For each unknown in Technical Context β†’ research task. Consolidate in research.md: Decision, Rationale, Alternatives. + +### Phase 1: Design & Contracts + +Prereqs: research.md complete. +- Extract entities β†’ data-model.md +- Define interface contracts β†’ /contracts/ (skip if purely internal) +- Run `{AGENT_SCRIPT}` for agent context update + +## Rules + +- Use absolute paths +- ERROR on gate failures or unresolved clarifications diff --git a/templates/commands/compact/specify.md b/templates/commands/compact/specify.md new file mode 100644 index 0000000000..97e305615c --- /dev/null +++ b/templates/commands/compact/specify.md @@ -0,0 +1,58 @@ +--- +description: Create or update feature specification from natural language description. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... + - label: Clarify Spec Requirements + agent: speckit.clarify + prompt: Clarify specification requirements + send: true +scripts: + sh: scripts/bash/create-new-feature.sh "{ARGS}" + ps: scripts/powershell/create-new-feature.ps1 "{ARGS}" +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Pre-Execution + +Check `.specify/extensions.yml` for `hooks.before_specify`. For enabled hooks: run mandatory ones (EXECUTE_COMMAND), show optional ones. Skip silently if file missing/invalid. + +## Workflow + +1. **Generate branch short name** (2-4 words, action-noun format, e.g. "user-auth", "fix-payment-timeout") + +2. **Create feature branch**: Run script with `--short-name` and `--json`. Check `.specify/init-options.json` for `branch_numbering` - add `--timestamp` if "timestamp". Never pass `--number`. Run script only once. Parse BRANCH_NAME and SPEC_FILE from JSON output. + +3. **Load** `templates/compact/spec-template.md` for structure. + +4. **Generate spec**: + - Parse feature description, extract actors/actions/data/constraints + - Make informed guesses for unclear aspects using industry defaults + - Mark max 3 [NEEDS CLARIFICATION] only for high-impact ambiguities (scope > security > UX > technical) + - Fill: Scenarios (prioritized user stories with independent tests), Requirements (testable FRs), Success Criteria (measurable, tech-agnostic), Entities (if data involved), Assumptions + - Write to SPEC_FILE + +5. **Validate** against quality checklist at `FEATURE_DIR/checklists/requirements.md`: + - No implementation details, focused on user value, all mandatory sections complete + - Requirements testable, success criteria measurable+tech-agnostic, scenarios cover primary flows + - If items fail: fix and re-validate (max 3 iterations) + - If [NEEDS CLARIFICATION] remain (max 3): present options table to user, wait for response, update spec + +6. **Report** completion with branch, spec path, checklist results, next steps (`/speckit.clarify` or `/speckit.plan`). + +7. Check `.specify/extensions.yml` for `hooks.after_specify`. Run mandatory, show optional. Skip silently if missing. + +## Rules + +- Focus on WHAT users need and WHY - avoid HOW (no tech stack, APIs, code) +- Written for business stakeholders, not developers +- Remove N/A sections entirely +- Success criteria: measurable, tech-agnostic, user-focused, verifiable diff --git a/templates/commands/compact/tasks.md b/templates/commands/compact/tasks.md new file mode 100644 index 0000000000..b0b8e28a76 --- /dev/null +++ b/templates/commands/compact/tasks.md @@ -0,0 +1,64 @@ +--- +description: Generate actionable, dependency-ordered tasks.md from design artifacts. +handoffs: + - label: Analyze For Consistency + agent: speckit.analyze + prompt: Run a project analysis for consistency + send: true + - label: Implement Project + agent: speckit.implement + prompt: Start the implementation in phases + send: true +scripts: + sh: scripts/bash/check-prerequisites.sh --json + ps: scripts/powershell/check-prerequisites.ps1 -Json +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Pre-Execution + +Check `.specify/extensions.yml` for `hooks.before_tasks`. Run mandatory hooks, show optional. Skip silently if missing/invalid. + +## Workflow + +1. **Setup**: Run `{SCRIPT}`, parse FEATURE_DIR and AVAILABLE_DOCS. + +2. **Load docs**: Required: plan.md, spec.md. Optional: data-model.md, contracts/, research.md, quickstart.md. + +3. **Generate tasks**: + - Extract tech stack/structure from plan.md, user stories (P1,P2,P3) from spec.md + - Map entities from data-model.md and contracts to user stories + - Organize by user story for independent implementation/testing + - Use `templates/compact/tasks-template.md` structure + +4. **Write tasks.md** with phases: + - Phase 1: Setup | Phase 2: Foundation (blocks all stories) + - Phase 3+: One per user story (priority order) + - Final: Polish & cross-cutting + +5. **Report**: Path, task count per story, parallel opportunities, MVP scope. + +6. Check `.specify/extensions.yml` for `hooks.after_tasks`. Run mandatory, show optional. Skip silently if missing. + +## Task Format + +``` +- [ ] [TaskID] [P?] [Story?] Description with file path +``` + +- Checkbox `- [ ]` required | TaskID: T001, T002.. | [P]=parallel | [Story]=US1,US2 (story phases only) +- Include exact file paths | Tests optional (only if requested) + +## Task Organization + +- From stories (PRIMARY): each story gets own phase with modelsβ†’servicesβ†’endpoints +- From contracts: map to serving story +- From data model: map entities to stories, sharedβ†’Setup +- Phase order: Setupβ†’Foundationβ†’Stories(P1β†’P2β†’P3)β†’Polish diff --git a/templates/commands/compact/taskstoissues.md b/templates/commands/compact/taskstoissues.md new file mode 100644 index 0000000000..6e506b871a --- /dev/null +++ b/templates/commands/compact/taskstoissues.md @@ -0,0 +1,24 @@ +--- +description: Convert tasks into GitHub issues for the feature. +tools: ['github/github-mcp-server/issue_write'] +scripts: + sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks + ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks +--- + +## Input + +```text +$ARGUMENTS +``` + +Consider user input before proceeding (if not empty). + +## Workflow + +1. Run `{SCRIPT}`, parse FEATURE_DIR. Extract tasks path. +2. Get Git remote: `git config --get remote.origin.url` +3. **ONLY proceed if remote is a GitHub URL.** +4. For each task: create GitHub issue in the matching repository. + +**NEVER create issues in repositories that don't match the remote URL.** diff --git a/templates/compact/agent-file-template.md b/templates/compact/agent-file-template.md new file mode 100644 index 0000000000..5aacfe5658 --- /dev/null +++ b/templates/compact/agent-file-template.md @@ -0,0 +1,28 @@ +# [PROJECT NAME] Dev Guidelines + +Auto-generated from feature plans. Updated: [DATE] + +## Tech Stack + +[FROM ALL PLAN.MD FILES] + +## Structure + +```text +[ACTUAL STRUCTURE FROM PLANS] +``` + +## Commands + +[ACTIVE TECH COMMANDS ONLY] + +## Code Style + +[LANGUAGE-SPECIFIC FOR LANGUAGES IN USE] + +## Recent Changes + +[LAST 3 FEATURES] + + + diff --git a/templates/compact/checklist-template.md b/templates/compact/checklist-template.md new file mode 100644 index 0000000000..805840d041 --- /dev/null +++ b/templates/compact/checklist-template.md @@ -0,0 +1,20 @@ +# [TYPE] Checklist: [FEATURE NAME] + +purpose: [description] | date: [DATE] | feature: [link] + +## [Category 1] + +- [ ] CHK001 [action item] +- [ ] CHK002 [action item] +- [ ] CHK003 [action item] + +## [Category 2] + +- [ ] CHK004 [action item] +- [ ] CHK005 [action item] +- [ ] CHK006 [action item] + +## Notes + +- Mark complete: `[x]` +- Add findings inline diff --git a/templates/compact/constitution-template.md b/templates/compact/constitution-template.md new file mode 100644 index 0000000000..7a705b3b64 --- /dev/null +++ b/templates/compact/constitution-template.md @@ -0,0 +1,32 @@ +# [PROJECT_NAME] Constitution + +## Core Principles + +### [PRINCIPLE_1_NAME] +[PRINCIPLE_1_DESCRIPTION] + +### [PRINCIPLE_2_NAME] +[PRINCIPLE_2_DESCRIPTION] + +### [PRINCIPLE_3_NAME] +[PRINCIPLE_3_DESCRIPTION] + +### [PRINCIPLE_4_NAME] +[PRINCIPLE_4_DESCRIPTION] + +### [PRINCIPLE_5_NAME] +[PRINCIPLE_5_DESCRIPTION] + +## [SECTION_2_NAME] + +[SECTION_2_CONTENT] + +## [SECTION_3_NAME] + +[SECTION_3_CONTENT] + +## Governance + +[GOVERNANCE_RULES] + +v[VERSION] | ratified: [DATE] | amended: [DATE] diff --git a/templates/compact/plan-template.md b/templates/compact/plan-template.md new file mode 100644 index 0000000000..83169aefc3 --- /dev/null +++ b/templates/compact/plan-template.md @@ -0,0 +1,59 @@ +# Plan: [FEATURE] + +branch: `[###-feature-name]` | date: [DATE] | spec: [link] +input: `/specs/[###-feature-name]/spec.md` + +## Summary + +[Primary requirement + technical approach] + +## Technical Context + +- lang: [e.g. Python 3.11] +- deps: [e.g. FastAPI] +- storage: [e.g. PostgreSQL or N/A] +- testing: [e.g. pytest] +- platform: [e.g. Linux server] +- type: [library/cli/web-service/mobile-app] +- perf: [e.g. 1000 req/s or N/A] +- constraints: [e.g. <200ms p95] +- scale: [e.g. 10k users] + +## Constitution Check + +[Gates from constitution file - must pass before Phase 0] + +## Project Structure + +### Docs (this feature) + +```text +specs/[###-feature]/ +β”œβ”€β”€ plan.md +β”œβ”€β”€ research.md +β”œβ”€β”€ data-model.md +β”œβ”€β”€ quickstart.md +β”œβ”€β”€ contracts/ +└── tasks.md +``` + +### Source + +```text +src/ +β”œβ”€β”€ models/ +β”œβ”€β”€ services/ +β”œβ”€β”€ cli/ +└── lib/ +tests/ +β”œβ”€β”€ contract/ +β”œβ”€β”€ integration/ +└── unit/ +``` + +Structure decision: [selected structure rationale] + +## Complexity Tracking + +| Violation | Why Needed | Simpler Alt Rejected | +|-----------|-----------|---------------------| diff --git a/templates/compact/spec-template.md b/templates/compact/spec-template.md new file mode 100644 index 0000000000..975bff79ed --- /dev/null +++ b/templates/compact/spec-template.md @@ -0,0 +1,61 @@ +# Spec: [FEATURE NAME] + +branch: `[###-feature-name]` | date: [DATE] | status: Draft +input: "$ARGUMENTS" + +## Scenarios + +### US1 [Title] (P1) + +[Journey description] + +- why: [Priority reason] +- test: [Independent verification method] +- accept: + 1. given [state] when [action] then [outcome] + 2. given [state] when [action] then [outcome] + +### US2 [Title] (P2) + +[Journey description] + +- why: [Priority reason] +- test: [Independent verification method] +- accept: + 1. given [state] when [action] then [outcome] + +### US3 [Title] (P3) + +[Journey description] + +- why: [Priority reason] +- test: [Independent verification method] +- accept: + 1. given [state] when [action] then [outcome] + +### Edge Cases + +- [boundary condition]? +- [error scenario]? + +## Requirements + +- FR-001: MUST [capability] +- FR-002: MUST [capability] +- FR-003: MUST [capability] + +### Entities + +- [Entity1]: [attributes, relationships] +- [Entity2]: [attributes, relationships] + +## Success Criteria + +- SC-001: [measurable metric] +- SC-002: [measurable metric] +- SC-003: [measurable metric] + +## Assumptions + +- [assumption about scope/users/environment] +- [assumption about dependencies] diff --git a/templates/compact/tasks-template.md b/templates/compact/tasks-template.md new file mode 100644 index 0000000000..4c452a0de3 --- /dev/null +++ b/templates/compact/tasks-template.md @@ -0,0 +1,75 @@ +--- +description: "Task list template for feature implementation" +--- + +# Tasks: [FEATURE NAME] + +input: `/specs/[###-feature-name]/` +prereqs: plan.md, spec.md, research.md, data-model.md, contracts/ + +Format: `[ID] [P?] [Story] Description` | [P]=parallel | [Story]=US1,US2.. + +## Phase 1: Setup + +- [ ] T001 Create project structure per plan +- [ ] T002 Init [language] project with [framework] deps +- [ ] T003 [P] Configure lint/format tools + +## Phase 2: Foundation (blocks all stories) + +- [ ] T004 Setup DB schema/migrations +- [ ] T005 [P] Implement auth framework +- [ ] T006 [P] Setup API routing/middleware +- [ ] T007 Create base models/entities +- [ ] T008 Configure error handling/logging + +Checkpoint: foundation ready + +## Phase 3: US1 [Title] (P1) MVP + +goal: [deliverable] +test: [verification method] + +- [ ] T010 [P] [US1] Create [Entity1] model src/models/[entity1].py +- [ ] T011 [P] [US1] Create [Entity2] model src/models/[entity2].py +- [ ] T012 [US1] Implement [Service] src/services/[service].py +- [ ] T013 [US1] Implement [endpoint] src/[location]/[file].py +- [ ] T014 [US1] Add validation/error handling + +Checkpoint: US1 functional + +## Phase 4: US2 [Title] (P2) + +goal: [deliverable] +test: [verification method] + +- [ ] T020 [P] [US2] Create [Entity] model +- [ ] T021 [US2] Implement [Service] +- [ ] T022 [US2] Implement [endpoint] + +Checkpoint: US1+US2 functional + +## Phase 5: US3 [Title] (P3) + +goal: [deliverable] +test: [verification method] + +- [ ] T026 [P] [US3] Create [Entity] model +- [ ] T027 [US3] Implement [Service] +- [ ] T028 [US3] Implement [endpoint] + +Checkpoint: all stories functional + +## Phase N: Polish + +- [ ] TXXX [P] Docs updates +- [ ] TXXX Code cleanup +- [ ] TXXX Perf optimization +- [ ] TXXX Security hardening +- [ ] TXXX Run quickstart.md validation + +## Dependencies + +- Setup β†’ Foundation β†’ User Stories (parallel or P1β†’P2β†’P3) β†’ Polish +- Within stories: models β†’ services β†’ endpoints +- [P] = different files, no deps