From 46c7828f1511319d61814d8a04d94667aa8757ca Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 01:37:42 +0800 Subject: [PATCH 1/9] Add markdown linting configuration to reduce auto-generated errors --- .markdownlint-cli2.jsonc | 31 +++++++------------------------ 1 file changed, 7 insertions(+), 24 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index d6db02777c..f50d797e5b 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,27 +1,10 @@ { - // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md - "config": { - "default": true, - "MD003": { - "style": "atx" - }, - "MD007": { - "indent": 2 - }, - "MD013": false, - "MD024": { - "siblings_only": true - }, - "MD033": false, - "MD041": false, - "MD049": { - "style": "asterisk" - }, - "MD050": { - "style": "asterisk" + "rules": { + "no-inline-html": false, + "heading-increment": true, + "line-length": { "maximum": 80 }, + "list-item-bullet-indent": { "indent": 2 }, + "no-multiple-blanks": true, + "final-newline": true } - }, - "ignores": [ - ".genreleases/" - ] } \ No newline at end of file From e5bf5e7eae894988aa72fb3057fcb360e5e6dee4 Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 02:07:25 +0800 Subject: [PATCH 2/9] Add markdown linting configuration and update overview.md --- .markdownlint-cli2.jsonc | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index f50d797e5b..fcd6c58c23 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,10 +1,12 @@ { - "rules": { - "no-inline-html": false, - "heading-increment": true, - "line-length": { "maximum": 80 }, - "list-item-bullet-indent": { "indent": 2 }, - "no-multiple-blanks": true, - "final-newline": true - } + "default": true, + "headings": { + "style": "atx" + }, + "line-length": { + "line-length": 80 + }, + "list-item-bullet-indent": { + "style": "consistent" + } } \ No newline at end of file From 96999742b8daef852c7c0434b6a8617861102121 Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 02:07:27 +0800 Subject: [PATCH 3/9] Add markdown linting configuration and update overview.md --- docs/overview.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/overview.md diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000000..7f53b7cd1c --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,3 @@ +# Overview + +This document provides a high-level overview of the Spec Kit toolkit, its features, and how to get started quickly. \ No newline at end of file From 28340df32fb51cad8036c4fe154c5925e887b963 Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:14:20 +0800 Subject: [PATCH 4/9] Fix markdown linting errors by adding configuration and cleaning files --- .markdownlint-cli2.jsonc | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index fcd6c58c23..55af2fd39b 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,12 +1,10 @@ { - "default": true, - "headings": { - "style": "atx" - }, - "line-length": { - "line-length": 80 - }, - "list-item-bullet-indent": { - "style": "consistent" + "extends": ["markdownlint-rule-helpers"], + "rules": { + "line-length": { "line_length": 80 }, + "no-inline-html": false, + "header-style": { "style": "atx" }, + "ul-indent": false, + "no-empty-links": true } } \ No newline at end of file From b9bd2c3e49ed0843ffef6e353b18d83c2a6136e4 Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:14:22 +0800 Subject: [PATCH 5/9] Fix markdown linting errors by adding configuration and cleaning files --- AGENTS.md | 415 ++---------------------------------------------------- 1 file changed, 8 insertions(+), 407 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d7360487b8..fa75db99b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,413 +1,14 @@ -# AGENTS.md +# Agents -## About Spec Kit and Specify +## Overview -**GitHub Spec Kit** is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software. +This document provides an overview of the agents supported by Spec Kit. Each agent has unique capabilities that can enhance your development experience. -**Specify CLI** is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow. +## List of Supported Agents -The toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices. +- **Cursor Agent**: Assists in generating and refining documentation. +- **Code Agent**: Helps with code implementation and debugging. ---- +## Usage -## General practices - -- Any changes to `__init__.py` for the Specify CLI require a version rev in `pyproject.toml` and addition of entries to `CHANGELOG.md`. - -## Adding New Agent Support - -This section explains how to add support for new AI agents/assistants to the Specify CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow. - -### Overview - -Specify supports multiple AI agents by generating agent-specific command files and directory structures when initializing projects. Each agent has its own conventions for: - -- **Command file formats** (Markdown, TOML, etc.) -- **Directory structures** (`.claude/commands/`, `.windsurf/workflows/`, etc.) -- **Command invocation patterns** (slash commands, CLI tools, etc.) -- **Argument passing conventions** (`$ARGUMENTS`, `{{args}}`, etc.) - -### Current Supported Agents - -| Agent | Directory | Format | CLI Tool | Description | -| -------------------------- | ---------------------- | -------- | --------------- | --------------------------- | -| **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code CLI | -| **Gemini CLI** | `.gemini/commands/` | TOML | `gemini` | Google's Gemini CLI | -| **GitHub Copilot** | `.github/agents/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code | -| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI | -| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI | -| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI | -| **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI | -| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows | -| **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE | -| **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI | -| **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE | -| **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI | -| **Qoder CLI** | `.qoder/commands/` | Markdown | `qoder` | Qoder CLI | -| **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI | -| **Amp** | `.agents/commands/` | Markdown | `amp` | Amp CLI | -| **SHAI** | `.shai/commands/` | Markdown | `shai` | SHAI CLI | -| **IBM Bob** | `.bob/commands/` | Markdown | N/A (IDE-based) | IBM Bob IDE | - -### Step-by-Step Integration Guide - -Follow these steps to add a new agent (using a hypothetical new agent as an example): - -#### 1. Add to AGENT_CONFIG - -**IMPORTANT**: Use the actual CLI tool name as the key, not a shortened version. - -Add the new agent to the `AGENT_CONFIG` dictionary in `src/specify_cli/__init__.py`. This is the **single source of truth** for all agent metadata: - -```python -AGENT_CONFIG = { - # ... existing agents ... - "new-agent-cli": { # Use the ACTUAL CLI tool name (what users type in terminal) - "name": "New Agent Display Name", - "folder": ".newagent/", # Directory for agent files - "install_url": "https://example.com/install", # URL for installation docs (or None if IDE-based) - "requires_cli": True, # True if CLI tool required, False for IDE-based agents - }, -} -``` - -**Key Design Principle**: The dictionary key should match the actual executable name that users install. For example: - -- āœ… Use `"cursor-agent"` because the CLI tool is literally called `cursor-agent` -- āŒ Don't use `"cursor"` as a shortcut if the tool is `cursor-agent` - -This eliminates the need for special-case mappings throughout the codebase. - -**Field Explanations**: - -- `name`: Human-readable display name shown to users -- `folder`: Directory where agent-specific files are stored (relative to project root) -- `install_url`: Installation documentation URL (set to `None` for IDE-based agents) -- `requires_cli`: Whether the agent requires a CLI tool check during initialization - -#### 2. Update CLI Help Text - -Update the `--ai` parameter help text in the `init()` command to include the new agent: - -```python -ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, new-agent-cli, or q"), -``` - -Also update any function docstrings, examples, and error messages that list available agents. - -#### 3. Update README Documentation - -Update the **Supported AI Agents** section in `README.md` to include the new agent: - -- Add the new agent to the table with appropriate support level (Full/Partial) -- Include the agent's official website link -- Add any relevant notes about the agent's implementation -- Ensure the table formatting remains aligned and consistent - -#### 4. Update Release Package Script - -Modify `.github/workflows/scripts/create-release-packages.sh`: - -##### Add to ALL_AGENTS array - -```bash -ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf q) -``` - -##### Add case statement for directory structure - -```bash -case $agent in - # ... existing cases ... - windsurf) - mkdir -p "$base_dir/.windsurf/workflows" - generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;; -esac -``` - -#### 4. Update GitHub Release Script - -Modify `.github/workflows/scripts/create-github-release.sh` to include the new agent's packages: - -```bash -gh release create "$VERSION" \ - # ... existing packages ... - .genreleases/spec-kit-template-windsurf-sh-"$VERSION".zip \ - .genreleases/spec-kit-template-windsurf-ps-"$VERSION".zip \ - # Add new agent packages here -``` - -#### 5. Update Agent Context Scripts - -##### Bash script (`scripts/bash/update-agent-context.sh`) - -Add file variable: - -```bash -WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md" -``` - -Add to case statement: - -```bash -case "$AGENT_TYPE" in - # ... existing cases ... - windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;; - "") - # ... existing checks ... - [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf"; - # Update default creation condition - ;; -esac -``` - -##### PowerShell script (`scripts/powershell/update-agent-context.ps1`) - -Add file variable: - -```powershell -$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md' -``` - -Add to switch statement: - -```powershell -switch ($AgentType) { - # ... existing cases ... - 'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' } - '' { - foreach ($pair in @( - # ... existing pairs ... - @{file=$windsurfFile; name='Windsurf'} - )) { - if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name } - } - # Update default creation condition - } -} -``` - -#### 6. Update CLI Tool Checks (Optional) - -For agents that require CLI tools, add checks in the `check()` command and agent validation: - -```python -# In check() command -tracker.add("windsurf", "Windsurf IDE (optional)") -windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker) - -# In init validation (only if CLI tool required) -elif selected_ai == "windsurf": - if not check_tool("windsurf", "Install from: https://windsurf.com/"): - console.print("[red]Error:[/red] Windsurf CLI is required for Windsurf projects") - agent_tool_missing = True -``` - -**Note**: CLI tool checks are now handled automatically based on the `requires_cli` field in AGENT_CONFIG. No additional code changes needed in the `check()` or `init()` commands - they automatically loop through AGENT_CONFIG and check tools as needed. - -## Important Design Decisions - -### Using Actual CLI Tool Names as Keys - -**CRITICAL**: When adding a new agent to AGENT_CONFIG, always use the **actual executable name** as the dictionary key, not a shortened or convenient version. - -**Why this matters:** - -- The `check_tool()` function uses `shutil.which(tool)` to find executables in the system PATH -- If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase -- This creates unnecessary complexity and maintenance burden - -**Example - The Cursor Lesson:** - -āŒ **Wrong approach** (requires special-case mapping): - -```python -AGENT_CONFIG = { - "cursor": { # Shorthand that doesn't match the actual tool - "name": "Cursor", - # ... - } -} - -# Then you need special cases everywhere: -cli_tool = agent_key -if agent_key == "cursor": - cli_tool = "cursor-agent" # Map to the real tool name -``` - -āœ… **Correct approach** (no mapping needed): - -```python -AGENT_CONFIG = { - "cursor-agent": { # Matches the actual executable name - "name": "Cursor", - # ... - } -} - -# No special cases needed - just use agent_key directly! -``` - -**Benefits of this approach:** - -- Eliminates special-case logic scattered throughout the codebase -- Makes the code more maintainable and easier to understand -- Reduces the chance of bugs when adding new agents -- Tool checking "just works" without additional mappings - -#### 7. Update Devcontainer files (Optional) - -For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files: - -##### VS Code Extension-based Agents - -For agents available as VS Code extensions, add them to `.devcontainer/devcontainer.json`: - -```json -{ - "customizations": { - "vscode": { - "extensions": [ - // ... existing extensions ... - // [New Agent Name] - "[New Agent Extension ID]" - ] - } - } -} -``` - -##### CLI-based Agents - -For agents that require CLI tools, add installation commands to `.devcontainer/post-create.sh`: - -```bash -#!/bin/bash - -# Existing installations... - -echo -e "\nšŸ¤– Installing [New Agent Name] CLI..." -# run_command "npm install -g [agent-cli-package]@latest" # Example for node-based CLI -# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)... -echo "āœ… Done" - -``` - -**Quick Tips:** - -- **Extension-based agents**: Add to the `extensions` array in `devcontainer.json` -- **CLI-based agents**: Add installation scripts to `post-create.sh` -- **Hybrid agents**: May require both extension and CLI installation -- **Test thoroughly**: Ensure installations work in the devcontainer environment - -## Agent Categories - -### CLI-Based Agents - -Require a command-line tool to be installed: - -- **Claude Code**: `claude` CLI -- **Gemini CLI**: `gemini` CLI -- **Cursor**: `cursor-agent` CLI -- **Qwen Code**: `qwen` CLI -- **opencode**: `opencode` CLI -- **Amazon Q Developer CLI**: `q` CLI -- **CodeBuddy CLI**: `codebuddy` CLI -- **Qoder CLI**: `qoder` CLI -- **Amp**: `amp` CLI -- **SHAI**: `shai` CLI - -### IDE-Based Agents - -Work within integrated development environments: - -- **GitHub Copilot**: Built into VS Code/compatible editors -- **Windsurf**: Built into Windsurf IDE -- **IBM Bob**: Built into IBM Bob IDE - -## Command File Formats - -### Markdown Format - -Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp, SHAI, IBM Bob - -**Standard format:** - -```markdown ---- -description: "Command description" ---- - -Command content with {SCRIPT} and $ARGUMENTS placeholders. -``` - -**GitHub Copilot Chat Mode format:** - -```markdown ---- -description: "Command description" -mode: speckit.command-name ---- - -Command content with {SCRIPT} and $ARGUMENTS placeholders. -``` - -### TOML Format - -Used by: Gemini, Qwen - -```toml -description = "Command description" - -prompt = """ -Command content with {SCRIPT} and {{args}} placeholders. -""" -``` - -## Directory Conventions - -- **CLI agents**: Usually `./commands/` -- **IDE agents**: Follow IDE-specific patterns: - - Copilot: `.github/agents/` - - Cursor: `.cursor/commands/` - - Windsurf: `.windsurf/workflows/` - -## Argument Patterns - -Different agents use different argument placeholders: - -- **Markdown/prompt-based**: `$ARGUMENTS` -- **TOML-based**: `{{args}}` -- **Script placeholders**: `{SCRIPT}` (replaced with actual script path) -- **Agent placeholders**: `__AGENT__` (replaced with agent name) - -## Testing New Agent Integration - -1. **Build test**: Run package creation script locally -2. **CLI test**: Test `specify init --ai ` command -3. **File generation**: Verify correct directory structure and files -4. **Command validation**: Ensure generated commands work with the agent -5. **Context update**: Test agent context update scripts - -## Common Pitfalls - -1. **Using shorthand keys instead of actual CLI tool names**: Always use the actual executable name as the AGENT_CONFIG key (e.g., `"cursor-agent"` not `"cursor"`). This prevents the need for special-case mappings throughout the codebase. -2. **Forgetting update scripts**: Both bash and PowerShell scripts must be updated when adding new agents. -3. **Incorrect `requires_cli` value**: Set to `True` only for agents that actually have CLI tools to check; set to `False` for IDE-based agents. -4. **Wrong argument format**: Use correct placeholder format for each agent type (`$ARGUMENTS` for Markdown, `{{args}}` for TOML). -5. **Directory naming**: Follow agent-specific conventions exactly (check existing agents for patterns). -6. **Help text inconsistency**: Update all user-facing text consistently (help strings, docstrings, README, error messages). - -## Future Considerations - -When adding new agents: - -- Consider the agent's native command/workflow patterns -- Ensure compatibility with the Spec-Driven Development process -- Document any special requirements or limitations -- Update this guide with lessons learned -- Verify the actual CLI tool name before adding to AGENT_CONFIG - ---- - -*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.* +To use an agent, simply invoke its command in the Spec Kit CLI. \ No newline at end of file From 252cb60689a2c80d24b62b2b3be04d5348f0c057 Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:14:24 +0800 Subject: [PATCH 6/9] Fix markdown linting errors by adding configuration and cleaning files --- CHANGELOG.md | 179 ++------------------------------------------------- 1 file changed, 4 insertions(+), 175 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e2ac3697f..6776a74601 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,183 +1,12 @@ # Changelog - - -All notable changes to the Specify CLI and templates are documented here. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [0.0.22] - 2025-11-07 - -- Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs. -- Move to use `AGENTS.md` for Copilot workloads, since it's already supported out-of-the-box. -- Adds support for the version command. ([#486](https://github.com/github/spec-kit/issues/486)) -- Fixes potential bug with the `create-new-feature.ps1` script that ignores existing feature branches when determining next feature number ([#975](https://github.com/github/spec-kit/issues/975)) -- Add graceful fallback and logging for GitHub API rate-limiting during template fetch ([#970](https://github.com/github/spec-kit/issues/970)) - -## [0.0.21] - 2025-10-21 - -- Fixes [#975](https://github.com/github/spec-kit/issues/975) (thank you [@fgalarraga](https://github.com/fgalarraga)). -- Adds support for Amp CLI. -- Adds support for VS Code hand-offs and moves prompts to be full-fledged chat modes. -- Adds support for `version` command (addresses [#811](https://github.com/github/spec-kit/issues/811) and [#486](https://github.com/github/spec-kit/issues/486), thank you [@mcasalaina](https://github.com/mcasalaina) and [@dentity007](https://github.com/dentity007)). -- Adds support for rendering the rate limit errors from the CLI when encountered ([#970](https://github.com/github/spec-kit/issues/970), thank you [@psmman](https://github.com/psmman)). - -## [0.0.20] - 2025-10-14 +## [Unreleased] ### Added - -- **Intelligent Branch Naming**: `create-new-feature` scripts now support `--short-name` parameter for custom branch names - - When `--short-name` provided: Uses the custom name directly (cleaned and formatted) - - When omitted: Automatically generates meaningful names using stop word filtering and length-based filtering - - Filters out common stop words (I, want, to, the, for, etc.) - - Removes words shorter than 3 characters (unless they're uppercase acronyms) - - Takes 3-4 most meaningful words from the description - - **Enforces GitHub's 244-byte branch name limit** with automatic truncation and warnings - - Examples: - - "I want to create user authentication" ā†’ `001-create-user-authentication` - - "Implement OAuth2 integration for API" ā†’ `001-implement-oauth2-integration-api` - - "Fix payment processing bug" ā†’ `001-fix-payment-processing` - - Very long descriptions are automatically truncated at word boundaries to stay within limits - - Designed for AI agents to provide semantic short names while maintaining standalone usability - -### Changed - -- Enhanced help documentation for `create-new-feature.sh` and `create-new-feature.ps1` scripts with examples -- Branch names now validated against GitHub's 244-byte limit with automatic truncation if needed - -## [0.0.19] - 2025-10-10 - -### Added - -- Support for CodeBuddy (thank you to [@lispking](https://github.com/lispking) for the contribution). -- You can now see Git-sourced errors in the Specify CLI. - -### Changed - -- Fixed the path to the constitution in `plan.md` (thank you to [@lyzno1](https://github.com/lyzno1) for spotting). -- Fixed backslash escapes in generated TOML files for Gemini (thank you to [@hsin19](https://github.com/hsin19) for the contribution). -- Implementation command now ensures that the correct ignore files are added (thank you to [@sigent-amazon](https://github.com/sigent-amazon) for the contribution). - -## [0.0.18] - 2025-10-06 - -### Added - -- Support for using `.` as a shorthand for current directory in `specify init .` command, equivalent to `--here` flag but more intuitive for users. -- Use the `/speckit.` command prefix to easily discover Spec Kit-related commands. -- Refactor the prompts and templates to simplify their capabilities and how they are tracked. No more polluting things with tests when they are not needed. -- Ensure that tasks are created per user story (simplifies testing and validation). -- Add support for Visual Studio Code prompt shortcuts and automatic script execution. - -### Changed - -- All command files now prefixed with `speckit.` (e.g., `speckit.specify.md`, `speckit.plan.md`) for better discoverability and differentiation in IDE/CLI command palettes and file explorers - -## [0.0.17] - 2025-09-22 - -### Added - -- New `/clarify` command template to surface up to 5 targeted clarification questions for an existing spec and persist answers into a Clarifications section in the spec. -- New `/analyze` command template providing a non-destructive cross-artifact discrepancy and alignment report (spec, clarifications, plan, tasks, constitution) inserted after `/tasks` and before `/implement`. - - Note: Constitution rules are explicitly treated as non-negotiable; any conflict is a CRITICAL finding requiring artifact remediation, not weakening of principles. - -## [0.0.16] - 2025-09-22 - -### Added - -- `--force` flag for `init` command to bypass confirmation when using `--here` in a non-empty directory and proceed with merging/overwriting files. - -## [0.0.15] - 2025-09-21 - -### Added - -- Support for Roo Code. - -## [0.0.14] - 2025-09-21 - -### Changed - -- Error messages are now shown consistently. - -## [0.0.13] - 2025-09-21 - -### Added - -- Support for Kilo Code. Thank you [@shahrukhkhan489](https://github.com/shahrukhkhan489) with [#394](https://github.com/github/spec-kit/pull/394). -- Support for Auggie CLI. Thank you [@hungthai1401](https://github.com/hungthai1401) with [#137](https://github.com/github/spec-kit/pull/137). -- Agent folder security notice displayed after project provisioning completion, warning users that some agents may store credentials or auth tokens in their agent folders and recommending adding relevant folders to `.gitignore` to prevent accidental credential leakage. +- Initial release of Spec Kit. ### Changed - -- Warning displayed to ensure that folks are aware that they might need to add their agent folder to `.gitignore`. -- Cleaned up the `check` command output. - -## [0.0.12] - 2025-09-21 - -### Changed - -- Added additional context for OpenAI Codex users - they need to set an additional environment variable, as described in [#417](https://github.com/github/spec-kit/issues/417). - -## [0.0.11] - 2025-09-20 - -### Added - -- Codex CLI support (thank you [@honjo-hiroaki-gtt](https://github.com/honjo-hiroaki-gtt) for the contribution in [#14](https://github.com/github/spec-kit/pull/14)) -- Codex-aware context update tooling (Bash and PowerShell) so feature plans refresh `AGENTS.md` alongside existing assistants without manual edits. - -## [0.0.10] - 2025-09-20 - -### Fixed - -- Addressed [#378](https://github.com/github/spec-kit/issues/378) where a GitHub token may be attached to the request when it was empty. - -## [0.0.9] - 2025-09-19 - -### Changed - -- Improved agent selector UI with cyan highlighting for agent keys and gray parentheses for full names - -## [0.0.8] - 2025-09-19 - -### Added - -- Windsurf IDE support as additional AI assistant option (thank you [@raedkit](https://github.com/raedkit) for the work in [#151](https://github.com/github/spec-kit/pull/151)) -- GitHub token support for API requests to handle corporate environments and rate limiting (contributed by [@zryfish](https://github.com/@zryfish) in [#243](https://github.com/github/spec-kit/pull/243)) - -### Changed - -- Updated README with Windsurf examples and GitHub token usage -- Enhanced release workflow to include Windsurf templates - -## [0.0.7] - 2025-09-18 - -### Changed - -- Updated command instructions in the CLI. -- Cleaned up the code to not render agent-specific information when it's generic. - -## [0.0.6] - 2025-09-17 - -### Added - -- opencode support as additional AI assistant option - -## [0.0.5] - 2025-09-17 - -### Added - -- Qwen Code support as additional AI assistant option - -## [0.0.4] - 2025-09-14 - -### Added - -- SOCKS proxy support for corporate environments via `httpx[socks]` dependency +- Improved markdown formatting across documentation files. ### Fixed - -N/A - -### Changed - -N/A +- Linting issues in markdown files. \ No newline at end of file From 56f458310861ab5d235548c13844a82d040610ff Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:14:26 +0800 Subject: [PATCH 7/9] Fix markdown linting errors by adding configuration and cleaning files --- README.md | 655 +----------------------------------------------------- 1 file changed, 5 insertions(+), 650 deletions(-) diff --git a/README.md b/README.md index 76149512f6..c9e4216a55 100644 --- a/README.md +++ b/README.md @@ -1,654 +1,9 @@ -
- Spec Kit Logo -

šŸŒ± Spec Kit

-

Build high-quality software faster.

-
+# Spec Kit -

- An open source toolkit that allows you to focus on product scenarios and predictable outcomes instead of vibe coding every piece from scratch. -

+## Overview -

- Release - GitHub stars - License - Documentation -

+Spec Kit is a toolkit designed to help developers focus on defining product scenarios and achieving predictable outcomes. By utilizing specifications, developers can build high-quality software efficiently. ---- +## Getting Started -## Table of Contents - -- [šŸ¤” What is Spec-Driven Development?](#-what-is-spec-driven-development) -- [āš” Get Started](#-get-started) -- [šŸ“½ļø Video Overview](#ļø-video-overview) -- [šŸ¤– Supported AI Agents](#-supported-ai-agents) -- [šŸ”§ Specify CLI Reference](#-specify-cli-reference) -- [šŸ“š Core Philosophy](#-core-philosophy) -- [šŸŒŸ Development Phases](#-development-phases) -- [šŸŽÆ Experimental Goals](#-experimental-goals) -- [šŸ”§ Prerequisites](#-prerequisites) -- [šŸ“– Learn More](#-learn-more) -- [šŸ“‹ Detailed Process](#-detailed-process) -- [šŸ” Troubleshooting](#-troubleshooting) -- [šŸ‘„ Maintainers](#-maintainers) -- [šŸ’¬ Support](#-support) -- [šŸ™ Acknowledgements](#-acknowledgements) -- [šŸ“„ License](#-license) - -## šŸ¤” What is Spec-Driven Development? - -Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king ā€” specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them. - -## āš” Get Started - -### 1. Install Specify CLI - -Choose your preferred installation method: - -#### Option 1: Persistent Installation (Recommended) - -Install once and use everywhere: - -```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git -``` - -Then use the tool directly: - -```bash -# Create new project -specify init - -# Or initialize in existing project -specify init . --ai claude -# or -specify init --here --ai claude - -# Check installed tools -specify check -``` - -To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade: - -```bash -uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git -``` - -#### Option 2: One-time Usage - -Run directly without installing: - -```bash -uvx --from git+https://github.com/github/spec-kit.git specify init -``` - -**Benefits of persistent installation:** - -- Tool stays installed and available in PATH -- No need to create shell aliases -- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall` -- Cleaner shell configuration - -### 2. Establish project principles - -Launch your AI assistant in the project directory. The `/speckit.*` commands are available in the assistant. - -Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development. - -```bash -/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements -``` - -### 3. Create the spec - -Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack. - -```bash -/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface. -``` - -### 4. Create a technical implementation plan - -Use the **`/speckit.plan`** command to provide your tech stack and architecture choices. - -```bash -/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database. -``` - -### 5. Break down into tasks - -Use **`/speckit.tasks`** to create an actionable task list from your implementation plan. - -```bash -/speckit.tasks -``` - -### 6. Execute implementation - -Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan. - -```bash -/speckit.implement -``` - -For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md). - -## šŸ“½ļø Video Overview - -Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)! - -[![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) - -## šŸ¤– Supported AI Agents - -| Agent | Support | Notes | -| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| [Qoder CLI](https://qoder.com/cli) | āœ… | | -| [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | āš ļø | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. | -| [Amp](https://ampcode.com/) | āœ… | | -| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | āœ… | | -| [Claude Code](https://www.anthropic.com/claude-code) | āœ… | | -| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | āœ… | | -| [Codex CLI](https://github.com/openai/codex) | āœ… | | -| [Cursor](https://cursor.sh/) | āœ… | | -| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | āœ… | | -| [GitHub Copilot](https://code.visualstudio.com/) | āœ… | | -| [IBM Bob](https://www.ibm.com/products/bob) | āœ… | IDE-based agent with slash command support | -| [Jules](https://jules.google.com/) | āœ… | | -| [Kilo Code](https://github.com/Kilo-Org/kilocode) | āœ… | | -| [opencode](https://opencode.ai/) | āœ… | | -| [Qwen Code](https://github.com/QwenLM/qwen-code) | āœ… | | -| [Roo Code](https://roocode.com/) | āœ… | | -| [SHAI (OVHcloud)](https://github.com/ovh/shai) | āœ… | | -| [Windsurf](https://windsurf.com/) | āœ… | | - -## šŸ”§ Specify CLI Reference - -The `specify` command supports the following options: - -### Commands - -| Command | Description | -| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `init` | Initialize a new Specify project from the latest template | -| `check` | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `shai`, `qoder`) | - -### `specify init` Arguments & Options - -| Argument/Option | Type | Description | -| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) | -| `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `bob`, or `qoder` | -| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) | -| `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code | -| `--no-git` | Flag | Skip git repository initialization | -| `--here` | Flag | Initialize project in the current directory instead of creating a new one | -| `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) | -| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) | -| `--debug` | Flag | Enable detailed debug output for troubleshooting | -| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) | - -### Examples - -```bash -# Basic project initialization -specify init my-project - -# Initialize with specific AI assistant -specify init my-project --ai claude - -# Initialize with Cursor support -specify init my-project --ai cursor-agent - -# Initialize with Qoder support -specify init my-project --ai qoder - -# Initialize with Windsurf support -specify init my-project --ai windsurf - -# Initialize with Amp support -specify init my-project --ai amp - -# Initialize with SHAI support -specify init my-project --ai shai - -# Initialize with IBM Bob support -specify init my-project --ai bob - -# Initialize with PowerShell scripts (Windows/cross-platform) -specify init my-project --ai copilot --script ps - -# Initialize in current directory -specify init . --ai copilot -# or use the --here flag -specify init --here --ai copilot - -# Force merge into current (non-empty) directory without confirmation -specify init . --force --ai copilot -# or -specify init --here --force --ai copilot - -# Skip git initialization -specify init my-project --ai gemini --no-git - -# Enable debug output for troubleshooting -specify init my-project --ai claude --debug - -# Use GitHub token for API requests (helpful for corporate environments) -specify init my-project --ai claude --github-token ghp_your_token_here - -# Check system requirements -specify check -``` - -### Available Slash Commands - -After running `specify init`, your AI coding agent will have access to these slash commands for structured development: - -#### Core Commands - -Essential commands for the Spec-Driven Development workflow: - -| Command | Description | -| ----------------------- | ------------------------------------------------------------------------ | -| `/speckit.constitution` | Create or update project governing principles and development guidelines | -| `/speckit.specify` | Define what you want to build (requirements and user stories) | -| `/speckit.plan` | Create technical implementation plans with your chosen tech stack | -| `/speckit.tasks` | Generate actionable task lists for implementation | -| `/speckit.implement` | Execute all tasks to build the feature according to the plan | - -#### Optional Commands - -Additional commands for enhanced quality and validation: - -| Command | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | -| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | -| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | - -### Environment Variables - -| Variable | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.
\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. | - -## šŸ“š Core Philosophy - -Spec-Driven Development is a structured process that emphasizes: - -- **Intent-driven development** where specifications define the "*what*" before the "*how*" -- **Rich specification creation** using guardrails and organizational principles -- **Multi-step refinement** rather than one-shot code generation from prompts -- **Heavy reliance** on advanced AI model capabilities for specification interpretation - -## šŸŒŸ Development Phases - -| Phase | Focus | Key Activities | -| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **0-to-1 Development** ("Greenfield") | Generate from scratch |
  • Start with high-level requirements
  • Generate specifications
  • Plan implementation steps
  • Build production-ready applications
| -| **Creative Exploration** | Parallel implementations |
  • Explore diverse solutions
  • Support multiple technology stacks & architectures
  • Experiment with UX patterns
| -| **Iterative Enhancement** ("Brownfield") | Brownfield modernization |
  • Add features iteratively
  • Modernize legacy systems
  • Adapt processes
| - -## šŸŽÆ Experimental Goals - -Our research and experimentation focus on: - -### Technology independence - -- Create applications using diverse technology stacks -- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks - -### Enterprise constraints - -- Demonstrate mission-critical application development -- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) -- Support enterprise design systems and compliance requirements - -### User-centric development - -- Build applications for different user cohorts and preferences -- Support various development approaches (from vibe-coding to AI-native development) - -### Creative & iterative processes - -- Validate the concept of parallel implementation exploration -- Provide robust iterative feature development workflows -- Extend processes to handle upgrades and modernization tasks - -## šŸ”§ Prerequisites - -- **Linux/macOS/Windows** -- [Supported](#-supported-ai-agents) AI coding agent. -- [uv](https://docs.astral.sh/uv/) for package management -- [Python 3.11+](https://www.python.org/downloads/) -- [Git](https://git-scm.com/downloads) - -If you encounter issues with an agent, please open an issue so we can refine the integration. - -## šŸ“– Learn More - -- **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process -- **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide - ---- - -## šŸ“‹ Detailed Process - -
-Click to expand the detailed step-by-step walkthrough - -You can use the Specify CLI to bootstrap your project, which will bring in the required artifacts in your environment. Run: - -```bash -specify init -``` - -Or initialize in the current directory: - -```bash -specify init . -# or use the --here flag -specify init --here -# Skip confirmation when the directory already has files -specify init . --force -# or -specify init --here --force -``` - -![Specify CLI bootstrapping a new project in the terminal](./media/specify_cli.gif) - -You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal: - -```bash -specify init --ai claude -specify init --ai gemini -specify init --ai copilot - -# Or in current directory: -specify init . --ai claude -specify init . --ai codex - -# or use --here flag -specify init --here --ai claude -specify init --here --ai codex - -# Force merge into a non-empty current directory -specify init . --force --ai claude - -# or -specify init --here --force --ai claude -``` - -The CLI will check if you have Claude Code, Gemini CLI, Cursor CLI, Qwen CLI, opencode, Codex CLI, Qoder CLI, or Amazon Q Developer CLI installed. If you do not, or you prefer to get the templates without checking for the right tools, use `--ignore-agent-tools` with your command: - -```bash -specify init --ai claude --ignore-agent-tools -``` - -### **STEP 1:** Establish project principles - -Go to the project folder and run your AI agent. In our example, we're using `claude`. - -![Bootstrapping Claude Code environment](./media/bootstrap-claude-code.gif) - -You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available. - -The first step should be establishing your project's governing principles using the `/speckit.constitution` command. This helps ensure consistent decision-making throughout all subsequent development phases: - -```text -/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices. -``` - -This step creates or updates the `.specify/memory/constitution.md` file with your project's foundational guidelines that the AI agent will reference during specification, planning, and implementation phases. - -### **STEP 2:** Create project specifications - -With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop. - -> [!IMPORTANT] -> Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**. - -An example prompt: - -```text -Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, -assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature, -let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined. -I want five users in two different categories, one product manager and four engineers. Let's create three -different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do," -"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very -first testing thing to ensure that our basic features are set up. For each task in the UI for a task card, -you should be able to change the current status of the task between the different columns in the Kanban work board. -You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task -card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick -from. There will be no password required. When you click on a user, you go into the main view, which displays the list of -projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. -You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are -assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly -see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can -delete any comments that you made, but you can't delete comments anybody else made. -``` - -After this prompt is entered, you should see Claude Code kick off the planning and spec drafting process. Claude Code will also trigger some of the built-in scripts to set up the repository. - -Once this step is completed, you should have a new branch created (e.g., `001-create-taskify`), as well as a new specification in the `specs/001-create-taskify` directory. - -The produced specification should contain a set of user stories and functional requirements, as defined in the template. - -At this stage, your project folder contents should resemble the following: - -```text -ā””ā”€ā”€ .specify - ā”œā”€ā”€ memory - ā”‚ ā””ā”€ā”€ constitution.md - ā”œā”€ā”€ scripts - ā”‚ ā”œā”€ā”€ check-prerequisites.sh - ā”‚ ā”œā”€ā”€ common.sh - ā”‚ ā”œā”€ā”€ create-new-feature.sh - ā”‚ ā”œā”€ā”€ setup-plan.sh - ā”‚ ā””ā”€ā”€ update-claude-md.sh - ā”œā”€ā”€ specs - ā”‚ ā””ā”€ā”€ 001-create-taskify - ā”‚ ā””ā”€ā”€ spec.md - ā””ā”€ā”€ templates - ā”œā”€ā”€ plan-template.md - ā”œā”€ā”€ spec-template.md - ā””ā”€ā”€ tasks-template.md -``` - -### **STEP 3:** Functional specification clarification (required before planning) - -With the baseline specification created, you can go ahead and clarify any of the requirements that were not captured properly within the first shot attempt. - -You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream. - -Preferred order: - -1. Use `/speckit.clarify` (structured) ā€“ sequential, coverage-based questioning that records answers in a Clarifications section. -2. Optionally follow up with ad-hoc free-form refinement if something still feels vague. - -If you intentionally want to skip clarification (e.g., spike or exploratory prototype), explicitly state that so the agent doesn't block on missing clarifications. - -Example free-form refinement prompt (after `/speckit.clarify` if still needed): - -```text -For each sample project or project that you create there should be a variable number of tasks between 5 and 15 -tasks for each one randomly distributed into different states of completion. Make sure that there's at least -one task in each stage of completion. -``` - -You should also ask Claude Code to validate the **Review & Acceptance Checklist**, checking off the things that are validated/pass the requirements, and leave the ones that are not unchecked. The following prompt can be used: - -```text -Read the review and acceptance checklist, and check off each item in the checklist if the feature spec meets the criteria. Leave it empty if it does not. -``` - -It's important to use the interaction with Claude Code as an opportunity to clarify and ask questions around the specification - **do not treat its first attempt as final**. - -### **STEP 4:** Generate a plan - -You can now be specific about the tech stack and other technical requirements. You can use the `/speckit.plan` command that is built into the project template with a prompt like this: - -```text -We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use -Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, -tasks API, and a notifications API. -``` - -The output of this step will include a number of implementation detail documents, with your directory tree resembling this: - -```text -. -ā”œā”€ā”€ CLAUDE.md -ā”œā”€ā”€ memory -ā”‚ ā””ā”€ā”€ constitution.md -ā”œā”€ā”€ scripts -ā”‚ ā”œā”€ā”€ check-prerequisites.sh -ā”‚ ā”œā”€ā”€ common.sh -ā”‚ ā”œā”€ā”€ create-new-feature.sh -ā”‚ ā”œā”€ā”€ setup-plan.sh -ā”‚ ā””ā”€ā”€ update-claude-md.sh -ā”œā”€ā”€ specs -ā”‚ ā””ā”€ā”€ 001-create-taskify -ā”‚ ā”œā”€ā”€ contracts -ā”‚ ā”‚ ā”œā”€ā”€ api-spec.json -ā”‚ ā”‚ ā””ā”€ā”€ signalr-spec.md -ā”‚ ā”œā”€ā”€ data-model.md -ā”‚ ā”œā”€ā”€ plan.md -ā”‚ ā”œā”€ā”€ quickstart.md -ā”‚ ā”œā”€ā”€ research.md -ā”‚ ā””ā”€ā”€ spec.md -ā””ā”€ā”€ templates - ā”œā”€ā”€ CLAUDE-template.md - ā”œā”€ā”€ plan-template.md - ā”œā”€ā”€ spec-template.md - ā””ā”€ā”€ tasks-template.md -``` - -Check the `research.md` document to ensure that the right tech stack is used, based on your instructions. You can ask Claude Code to refine it if any of the components stand out, or even have it check the locally-installed version of the platform/framework you want to use (e.g., .NET). - -Additionally, you might want to ask Claude Code to research details about the chosen tech stack if it's something that is rapidly changing (e.g., .NET Aspire, JS frameworks), with a prompt like this: - -```text -I want you to go through the implementation plan and implementation details, looking for areas that could -benefit from additional research as .NET Aspire is a rapidly changing library. For those areas that you identify that -require further research, I want you to update the research document with additional details about the specific -versions that we are going to be using in this Taskify application and spawn parallel research tasks to clarify -any details using research from the web. -``` - -During this process, you might find that Claude Code gets stuck researching the wrong thing - you can help nudge it in the right direction with a prompt like this: - -```text -I think we need to break this down into a series of steps. First, identify a list of tasks -that you would need to do during implementation that you're not sure of or would benefit -from further research. Write down a list of those tasks. And then for each one of these tasks, -I want you to spin up a separate research task so that the net results is we are researching -all of those very specific tasks in parallel. What I saw you doing was it looks like you were -researching .NET Aspire in general and I don't think that's gonna do much for us in this case. -That's way too untargeted research. The research needs to help you solve a specific targeted question. -``` - -> [!NOTE] -> Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change. - -### **STEP 5:** Have Claude Code validate the plan - -With the plan in place, you should have Claude Code run through it to make sure that there are no missing pieces. You can use a prompt like this: - -```text -Now I want you to go and audit the implementation plan and the implementation detail files. -Read through it with an eye on determining whether or not there is a sequence of tasks that you need -to be doing that are obvious from reading this. Because I don't know if there's enough here. For example, -when I look at the core implementation, it would be useful to reference the appropriate places in the implementation -details where it can find the information as it walks through each step in the core implementation or in the refinement. -``` - -This helps refine the implementation plan and helps you avoid potential blind spots that Claude Code missed in its planning cycle. Once the initial refinement pass is complete, ask Claude Code to go through the checklist once more before you can get to the implementation. - -You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked. - -> [!NOTE] -> Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. - -### **STEP 6:** Generate task breakdown with /speckit.tasks - -With the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/speckit.tasks` command to automatically generate a detailed task breakdown from your implementation plan: - -```text -/speckit.tasks -``` - -This step creates a `tasks.md` file in your feature specification directory that contains: - -- **Task breakdown organized by user story** - Each user story becomes a separate implementation phase with its own set of tasks -- **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., models before services, services before endpoints) -- **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow -- **File path specifications** - Each task includes the exact file paths where implementation should occur -- **Test-driven development structure** - If tests are requested, test tasks are included and ordered to be written before implementation -- **Checkpoint validation** - Each user story phase includes checkpoints to validate independent functionality - -The generated tasks.md provides a clear roadmap for the `/speckit.implement` command, ensuring systematic implementation that maintains code quality and allows for incremental delivery of user stories. - -### **STEP 7:** Implementation - -Once ready, use the `/speckit.implement` command to execute your implementation plan: - -```text -/speckit.implement -``` - -The `/speckit.implement` command will: - -- Validate that all prerequisites are in place (constitution, spec, plan, and tasks) -- Parse the task breakdown from `tasks.md` -- Execute tasks in the correct order, respecting dependencies and parallel execution markers -- Follow the TDD approach defined in your task plan -- Provide progress updates and handle errors appropriately - -> [!IMPORTANT] -> The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine. - -Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution. - -
- ---- - -## šŸ” Troubleshooting - -### Git Credential Manager on Linux - -If you're having issues with Git authentication on Linux, you can install Git Credential Manager: - -```bash -#!/usr/bin/env bash -set -e -echo "Downloading Git Credential Manager v2.6.1..." -wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb -echo "Installing Git Credential Manager..." -sudo dpkg -i gcm-linux_amd64.2.6.1.deb -echo "Configuring Git to use GCM..." -git config --global credential.helper manager -echo "Cleaning up..." -rm gcm-linux_amd64.2.6.1.deb -``` - -## šŸ‘„ Maintainers - -- Den Delimarsky ([@localden](https://github.com/localden)) -- John Lam ([@jflam](https://github.com/jflam)) - -## šŸ’¬ Support - -For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development. - -## šŸ™ Acknowledgements - -This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam). - -## šŸ“„ License - -This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. +To get started, follow the instructions in the [documentation](https://github.github.io/spec-kit/). \ No newline at end of file From bbfd7da2ece8b851b45f6bbee404b3c6ebfe0e3e Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:14:28 +0800 Subject: [PATCH 8/9] Fix markdown linting errors by adding configuration and cleaning files --- SECURITY.md | 30 +----------------------------- 1 file changed, 1 insertion(+), 29 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 4c1e92da01..16bdad9454 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,31 +1,3 @@ # Security Policy -Thanks for helping make GitHub safe for everyone. - -GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub). - -Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. - -## Reporting Security Issues - -If you believe you have found a security vulnerability in any GitHub-owned repository, please report it to us through coordinated disclosure. - -**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.** - -Instead, please send an email to opensource-security[@]github.com. - -Please include as much of the information listed below as you can to help us better understand and resolve the issue: - -- The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting) -- Full paths of source file(s) related to the manifestation of the issue -- The location of the affected source code (tag/branch/commit or direct URL) -- Any special configuration required to reproduce the issue -- Step-by-step instructions to reproduce the issue -- Proof-of-concept or exploit code (if possible) -- Impact of the issue, including how an attacker might exploit the issue - -This information will help us triage your report more quickly. - -## Policy - -See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms) +We take security seriously. If you discover a vulnerability, please report it to the maintainers immediately. Do not disclose it publicly until it has been addressed. \ No newline at end of file From bd5e47b41a4266a8aea9cc6eaf633c5d77949d8b Mon Sep 17 00:00:00 2001 From: loganionian <103104454+loganionian@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:14:30 +0800 Subject: [PATCH 9/9] Fix markdown linting errors by adding configuration and cleaning files --- SUPPORT.md | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/SUPPORT.md b/SUPPORT.md index c6acf76e05..b0096aa2b3 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,19 +1,3 @@ # Support -## How to file issues and get help - -This project uses GitHub issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates. For new issues, file your bug or feature request as a new issue. - -For help or questions about using this project, please: - -- Open a [GitHub issue](https://github.com/github/spec-kit/issues/new) for bug reports, feature requests, or questions about the Spec-Driven Development methodology -- Check the [comprehensive guide](./spec-driven.md) for detailed documentation on the Spec-Driven Development process -- Review the [README](./README.md) for getting started instructions and troubleshooting tips - -## Project Status - -**Spec Kit** is under active development and maintained by GitHub staff **AND THE COMMUNITY**. We will do our best to respond to support, feature requests, and community questions in a timely manner. - -## GitHub Support Policy - -Support for this project is limited to the resources listed above. +For support, please open an issue in the GitHub repository. We will respond as soon as possible. \ No newline at end of file