Initial plan

Co-authored-by: Santosh Bhavani <sb@mac-mini-i7.local>

.github/CODEOWNERS

@@ -1,3 +1,3 @@
 # Global code owner
-* @localden
+* @mnriem
 

.github/ISSUE_TEMPLATE/agent_request.yml

@@ -0,0 +1,141 @@
+name: Agent Request
+description: Request support for a new AI agent/assistant in Spec Kit
+title: "[Agent]: Add support for "
+labels: ["agent-request", "enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for requesting a new agent! Before submitting, please check if the agent is already supported.
+        
+        **Currently supported agents**: Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qwen Code, opencode, Codex CLI, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy, Qoder CLI, Amazon Q Developer CLI, Amp, SHAI, IBM Bob, Antigravity
+
+  - type: input
+    id: agent-name
+    attributes:
+      label: Agent Name
+      description: What is the name of the AI agent/assistant?
+      placeholder: "e.g., SuperCoder AI"
+    validations:
+      required: true
+
+  - type: input
+    id: website
+    attributes:
+      label: Official Website
+      description: Link to the agent's official website or documentation
+      placeholder: "https://..."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: agent-type
+    attributes:
+      label: Agent Type
+      description: How is the agent accessed?
+      options:
+        - CLI tool (command-line interface)
+        - IDE extension/plugin
+        - Both CLI and IDE
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: cli-command
+    attributes:
+      label: CLI Command (if applicable)
+      description: What command is used to invoke the agent from terminal?
+      placeholder: "e.g., supercode, ai-assistant"
+
+  - type: input
+    id: install-method
+    attributes:
+      label: Installation Method
+      description: How is the agent installed?
+      placeholder: "e.g., npm install -g supercode, pip install supercode, IDE marketplace"
+    validations:
+      required: true
+
+  - type: textarea
+    id: command-structure
+    attributes:
+      label: Command/Workflow Structure
+      description: How does the agent define custom commands or workflows?
+      placeholder: |
+        - Command file format (Markdown, YAML, TOML, etc.)
+        - Directory location (e.g., .supercode/commands/)
+        - Example command file structure
+    validations:
+      required: true
+
+  - type: textarea
+    id: argument-pattern
+    attributes:
+      label: Argument Passing Pattern
+      description: How does the agent handle arguments in commands?
+      placeholder: |
+        e.g., Uses {{args}}, $ARGUMENTS, %ARGS%, or other placeholder format
+        Example: "Run test suite with {{args}}"
+
+  - type: dropdown
+    id: popularity
+    attributes:
+      label: Popularity/Usage
+      description: How widely is this agent used?
+      options:
+        - Widely used (thousands+ of users)
+        - Growing adoption (hundreds of users)
+        - New/emerging (less than 100 users)
+        - Unknown
+    validations:
+      required: true
+
+  - type: textarea
+    id: documentation
+    attributes:
+      label: Documentation Links
+      description: Links to relevant documentation for custom commands/workflows
+      placeholder: |
+        - Command documentation: https://...
+        - API/CLI reference: https://...
+        - Examples: https://...
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Why do you want this agent supported in Spec Kit?
+      placeholder: Explain your workflow and how this agent fits into your development process
+    validations:
+      required: true
+
+  - type: textarea
+    id: example-command
+    attributes:
+      label: Example Command File
+      description: If possible, provide an example of a command file for this agent
+      render: markdown
+      placeholder: |
+        ```toml
+        description = "Example command"
+        prompt = "Do something with {{args}}"
+        ```
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      description: Are you willing to help implement support for this agent?
+      options:
+        - label: I can help test the integration
+        - label: I can provide example command files
+        - label: I can help with documentation
+        - label: I can submit a pull request for the integration
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Any other relevant information about this agent
+      placeholder: Screenshots, community links, comparison to existing agents, etc.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,118 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in Specify CLI or Spec Kit
+title: "[Bug]: "
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below to help us diagnose and fix the issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: What went wrong?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Run command '...'
+        2. Execute script '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: Describe the expected outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+      placeholder: Describe what happened instead
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Specify CLI Version
+      description: "Run `specify version` or `pip show spec-kit`"
+      placeholder: "e.g., 1.3.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ai-agent
+    attributes:
+      label: AI Agent
+      description: Which AI agent are you using?
+      options:
+        - Claude Code
+        - Gemini CLI
+        - GitHub Copilot
+        - Cursor
+        - Qwen Code
+        - opencode
+        - Codex CLI
+        - Windsurf
+        - Kilo Code
+        - Auggie CLI
+        - Roo Code
+        - CodeBuddy
+        - Qoder CLI
+        - Amazon Q Developer CLI
+        - Amp
+        - SHAI
+        - IBM Bob
+        - Antigravity
+        - Not applicable
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: Your operating system and version
+      placeholder: "e.g., macOS 14.2, Ubuntu 22.04, Windows 11"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python Version
+      description: "Run `python --version` or `python3 --version`"
+      placeholder: "e.g., Python 3.11.5"
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs
+      description: Please paste any relevant error messages or logs
+      render: shell
+      placeholder: Paste error output here
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem
+      placeholder: Screenshots, related issues, workarounds attempted, etc.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 General Discussion
+    url: https://github.com/github/spec-kit/discussions
+    about: Ask questions, share ideas, or discuss Spec-Driven Development
+  - name: 📖 Documentation
+    url: https://github.com/github/spec-kit/blob/main/README.md
+    about: Read the Spec Kit documentation and guides
+  - name: 🛠️ Extension Development Guide
+    url: https://github.com/manfredseee/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+    about: Learn how to develop and publish Spec Kit extensions
+  - name: 🤝 Contributing Guide
+    url: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md
+    about: Learn how to contribute to Spec Kit
+  - name: 🔒 Security Issues
+    url: https://github.com/github/spec-kit/blob/main/SECURITY.md
+    about: Report security vulnerabilities privately

.github/ISSUE_TEMPLATE/extension_submission.yml

@@ -0,0 +1,280 @@
+name: Extension Submission
+description: Submit your extension to the Spec Kit catalog
+title: "[Extension]: Add "
+labels: ["extension-submission", "enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for contributing an extension! This template helps you submit your extension to the community catalog.
+        
+        **Before submitting:**
+        - Review the [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md)
+        - Ensure your extension has a valid `extension.yml` manifest
+        - Create a GitHub release with a version tag (e.g., v1.0.0)
+        - Test installation: `specify extension add --from <your-release-url>`
+
+  - type: input
+    id: extension-id
+    attributes:
+      label: Extension ID
+      description: Unique extension identifier (lowercase with hyphens only)
+      placeholder: "e.g., jira-integration"
+    validations:
+      required: true
+
+  - type: input
+    id: extension-name
+    attributes:
+      label: Extension Name
+      description: Human-readable extension name
+      placeholder: "e.g., Jira Integration"
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Semantic version number
+      placeholder: "e.g., 1.0.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Brief description of what your extension does (under 200 characters)
+      placeholder: Integrates Jira issue tracking with Spec Kit workflows for seamless task management
+    validations:
+      required: true
+
+  - type: input
+    id: author
+    attributes:
+      label: Author
+      description: Your name or organization
+      placeholder: "e.g., John Doe or Acme Corp"
+    validations:
+      required: true
+
+  - type: input
+    id: repository
+    attributes:
+      label: Repository URL
+      description: GitHub repository URL for your extension
+      placeholder: "https://github.com/your-org/spec-kit-your-extension"
+    validations:
+      required: true
+
+  - type: input
+    id: download-url
+    attributes:
+      label: Download URL
+      description: URL to the GitHub release archive (e.g., v1.0.0.zip)
+      placeholder: "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip"
+    validations:
+      required: true
+
+  - type: input
+    id: license
+    attributes:
+      label: License
+      description: Open source license type
+      placeholder: "e.g., MIT, Apache-2.0"
+    validations:
+      required: true
+
+  - type: input
+    id: homepage
+    attributes:
+      label: Homepage (optional)
+      description: Link to extension homepage or documentation site
+      placeholder: "https://..."
+
+  - type: input
+    id: documentation
+    attributes:
+      label: Documentation URL (optional)
+      description: Link to detailed documentation
+      placeholder: "https://github.com/your-org/spec-kit-your-extension/blob/main/docs/"
+
+  - type: input
+    id: changelog
+    attributes:
+      label: Changelog URL (optional)
+      description: Link to changelog file
+      placeholder: "https://github.com/your-org/spec-kit-your-extension/blob/main/CHANGELOG.md"
+
+  - type: input
+    id: speckit-version
+    attributes:
+      label: Required Spec Kit Version
+      description: Minimum Spec Kit version required
+      placeholder: "e.g., >=0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: required-tools
+    attributes:
+      label: Required Tools (optional)
+      description: List any external tools or dependencies required
+      placeholder: |
+        - jira-cli (>=1.0.0) - required
+        - python (>=3.8) - optional
+      render: markdown
+
+  - type: input
+    id: commands-count
+    attributes:
+      label: Number of Commands
+      description: How many commands does your extension provide?
+      placeholder: "e.g., 3"
+    validations:
+      required: true
+
+  - type: input
+    id: hooks-count
+    attributes:
+      label: Number of Hooks (optional)
+      description: How many hooks does your extension provide?
+      placeholder: "e.g., 0"
+
+  - type: textarea
+    id: tags
+    attributes:
+      label: Tags
+      description: 2-5 relevant tags (lowercase, separated by commas)
+      placeholder: "issue-tracking, jira, atlassian, automation"
+    validations:
+      required: true
+
+  - type: textarea
+    id: features
+    attributes:
+      label: Key Features
+      description: List the main features and capabilities of your extension
+      placeholder: |
+        - Create Jira issues from specs
+        - Sync task status with Jira
+        - Link specs to existing issues
+        - Generate Jira reports
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: testing
+    attributes:
+      label: Testing Checklist
+      description: Confirm that your extension has been tested
+      options:
+        - label: Extension installs successfully via download URL
+          required: true
+        - label: All commands execute without errors
+          required: true
+        - label: Documentation is complete and accurate
+          required: true
+        - label: No security vulnerabilities identified
+          required: true
+        - label: Tested on at least one real project
+          required: true
+
+  - type: checkboxes
+    id: requirements
+    attributes:
+      label: Submission Requirements
+      description: Verify your extension meets all requirements
+      options:
+        - label: Valid `extension.yml` manifest included
+          required: true
+        - label: README.md with installation and usage instructions
+          required: true
+        - label: LICENSE file included
+          required: true
+        - label: GitHub release created with version tag
+          required: true
+        - label: All command files exist and are properly formatted
+          required: true
+        - label: Extension ID follows naming conventions (lowercase-with-hyphens)
+          required: true
+
+  - type: textarea
+    id: testing-details
+    attributes:
+      label: Testing Details
+      description: Describe how you tested your extension
+      placeholder: |
+        **Tested on:**
+        - macOS 14.0 with Spec Kit v0.1.0
+        - Linux Ubuntu 22.04 with Spec Kit v0.1.0
+        
+        **Test project:** [Link or description]
+        
+        **Test scenarios:**
+        1. Installed extension
+        2. Configured settings
+        3. Ran all commands
+        4. Verified outputs
+    validations:
+      required: true
+
+  - type: textarea
+    id: example-usage
+    attributes:
+      label: Example Usage
+      description: Provide a simple example of using your extension
+      render: markdown
+      placeholder: |
+        ```bash
+        # Install extension
+        specify extension add --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
+        
+        # Use a command
+        /speckit.your-extension.command-name arg1 arg2
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: catalog-entry
+    attributes:
+      label: Proposed Catalog Entry
+      description: Provide the JSON entry for catalog.json (helps reviewers)
+      render: json
+      placeholder: |
+        {
+          "your-extension": {
+            "name": "Your Extension",
+            "id": "your-extension",
+            "description": "Brief description",
+            "author": "Your Name",
+            "version": "1.0.0",
+            "download_url": "https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip",
+            "repository": "https://github.com/your-org/spec-kit-your-extension",
+            "homepage": "https://github.com/your-org/spec-kit-your-extension",
+            "license": "MIT",
+            "requires": {
+              "speckit_version": ">=0.1.0"
+            },
+            "provides": {
+              "commands": 3
+            },
+            "tags": ["category", "tool"],
+            "verified": false,
+            "downloads": 0,
+            "stars": 0,
+            "created_at": "2026-02-20T00:00:00Z",
+            "updated_at": "2026-02-20T00:00:00Z"
+          }
+        }
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other information that would help reviewers
+      placeholder: Screenshots, demo videos, links to related projects, etc.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,104 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for Specify CLI or Spec Kit
+title: "[Feature]: "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please provide details below to help us understand and evaluate your request.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Is your feature request related to a problem? Please describe.
+      placeholder: "I'm frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like
+      placeholder: What would you like to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?
+      placeholder: What other approaches might work?
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which component does this feature relate to?
+      options:
+        - Specify CLI (initialization, commands)
+        - Spec templates (BDD, Testing Strategy, etc.)
+        - Agent integrations (command files, workflows)
+        - Scripts (Bash/PowerShell utilities)
+        - Documentation
+        - CI/CD workflows
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ai-agent
+    attributes:
+      label: AI Agent (if applicable)
+      description: Does this feature relate to a specific AI agent?
+      options:
+        - All agents
+        - Claude Code
+        - Gemini CLI
+        - GitHub Copilot
+        - Cursor
+        - Qwen Code
+        - opencode
+        - Codex CLI
+        - Windsurf
+        - Kilo Code
+        - Auggie CLI
+        - Roo Code
+        - CodeBuddy
+        - Qoder CLI
+        - Amazon Q Developer CLI
+        - Amp
+        - SHAI
+        - IBM Bob
+        - Antigravity
+        - Not applicable
+
+  - type: textarea
+    id: use-cases
+    attributes:
+      label: Use Cases
+      description: Describe specific use cases where this feature would be valuable
+      placeholder: |
+        1. When working on large projects...
+        2. During spec review...
+        3. When integrating with CI/CD...
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: How would you know this feature is complete and working?
+      placeholder: |
+        - [ ] Feature does X
+        - [ ] Documentation is updated
+        - [ ] Works with all supported agents
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Add any other context, screenshots, or examples
+      placeholder: Links to similar features, mockups, related discussions, etc.

.github/workflows/release.yml

@@ -58,4 +58,12 @@ jobs:
         run: |
           chmod +x .github/workflows/scripts/update-version.sh
           .github/workflows/scripts/update-version.sh ${{ steps.get_tag.outputs.new_version }}
+      - name: Commit version bump to main
+        if: steps.check_release.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git diff --cached --quiet || git commit -m "chore: bump version to ${{ steps.get_tag.outputs.new_version }} [skip ci]"
+          git push
 

.github/workflows/scripts/create-github-release.sh

@@ -40,8 +40,8 @@ gh release create "$VERSION" \
   .genreleases/spec-kit-template-roo-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-codebuddy-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-codebuddy-ps-"$VERSION".zip \
-  .genreleases/spec-kit-template-qoder-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-qodercli-sh-"$VERSION".zip \
-  .genreleases/spec-kit-template-qoder-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-qodercli-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-amp-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-amp-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-shai-sh-"$VERSION".zip \
@@ -52,5 +52,7 @@ gh release create "$VERSION" \
   .genreleases/spec-kit-template-agy-ps-"$VERSION".zip \
   .genreleases/spec-kit-template-bob-sh-"$VERSION".zip \
   .genreleases/spec-kit-template-bob-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-generic-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-generic-ps-"$VERSION".zip \
   --title "Spec Kit Templates - $VERSION_NO_V" \
   --notes-file release_notes.md

.github/workflows/scripts/create-release-packages.ps1

@@ -14,7 +14,7 @@
 
 .PARAMETER Agents
     Comma or space separated subset of agents to build (default: all)
-    Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q, bob, qoder
+    Valid agents: claude, gemini, copilot, cursor-agent, qwen, opencode, windsurf, codex, kilocode, auggie, roo, codebuddy, amp, q, bob, qodercli, shai, agy, generic
 
 .PARAMETER Scripts
     Comma or space separated subset of script types to build (default: both)
@@ -343,9 +343,13 @@ function Build-Variant {
             $cmdDir = Join-Path $baseDir ".bob/commands"
             Generate-Commands -Agent 'bob' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
         }
-        'qoder' {
+        'qodercli' {
             $cmdDir = Join-Path $baseDir ".qoder/commands"
-            Generate-Commands -Agent 'qoder' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+            Generate-Commands -Agent 'qodercli' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
+        }
+        'generic' {
+            $cmdDir = Join-Path $baseDir ".speckit/commands"
+            Generate-Commands -Agent 'generic' -Extension 'md' -ArgFormat '$ARGUMENTS' -OutputDir $cmdDir -ScriptVariant $Script
         }
     }
     
@@ -356,7 +360,7 @@ function Build-Variant {
 }
 
 # Define all agents and scripts
-$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q', 'bob', 'qoder')
+$AllAgents = @('claude', 'gemini', 'copilot', 'cursor-agent', 'qwen', 'opencode', 'windsurf', 'codex', 'kilocode', 'auggie', 'roo', 'codebuddy', 'amp', 'q', 'bob', 'qodercli', 'shai', 'agy', 'generic')
 $AllScripts = @('sh', 'ps')
 
 function Normalize-List {

.github/workflows/scripts/create-release-packages.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 # Usage: .github/workflows/scripts/create-release-packages.sh <version>
 #   Version argument should include leading 'v'.
 #   Optionally set AGENTS and/or SCRIPTS env vars to limit what gets built.
-#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex amp shai bob (default: all)
+#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex amp shai bob generic (default: all)
 #     SCRIPTS : space or comma separated subset of: sh ps (default: both)
 #   Examples:
 #     AGENTS=claude SCRIPTS=sh $0 v0.2.0
@@ -203,9 +203,9 @@ build_variant() {
     codebuddy)
       mkdir -p "$base_dir/.codebuddy/commands"
       generate_commands codebuddy md "\$ARGUMENTS" "$base_dir/.codebuddy/commands" "$script" ;;
-    qoder)
+    qodercli)
       mkdir -p "$base_dir/.qoder/commands"
-      generate_commands qoder md "\$ARGUMENTS" "$base_dir/.qoder/commands" "$script" ;;
+      generate_commands qodercli md "\$ARGUMENTS" "$base_dir/.qoder/commands" "$script" ;;
     amp)
       mkdir -p "$base_dir/.agents/commands"
       generate_commands amp md "\$ARGUMENTS" "$base_dir/.agents/commands" "$script" ;;
@@ -221,13 +221,16 @@ build_variant() {
     bob)
       mkdir -p "$base_dir/.bob/commands"
       generate_commands bob md "\$ARGUMENTS" "$base_dir/.bob/commands" "$script" ;;
+    generic)
+      mkdir -p "$base_dir/.speckit/commands"
+      generate_commands generic md "\$ARGUMENTS" "$base_dir/.speckit/commands" "$script" ;;
   esac
   ( cd "$base_dir" && zip -r "../spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip" . )
   echo "Created $GENRELEASES_DIR/spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip"
 }
 
 # Determine agent list
-ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai q agy bob qoder)
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy amp shai q agy bob qodercli generic)
 ALL_SCRIPTS=(sh ps)
 
 norm_list() {

AGENTS.md

@@ -43,11 +43,12 @@ Specify supports multiple AI agents by generating agent-specific command files a
 | **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                   |
+| **Qoder CLI**              | `.qoder/commands/`     | Markdown | `qodercli`      | 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                 |
+| **Generic**                | User-specified via `--ai-commands-dir` | Markdown | N/A | Bring your own agent        |
 
 ### Step-by-Step Integration Guide
 
@@ -65,6 +66,7 @@ AGENT_CONFIG = {
     "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
+        "commands_subdir": "commands",  # Subdirectory name for command files (default: "commands")
         "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
     },
@@ -82,6 +84,10 @@ This eliminates the need for special-case mappings throughout the codebase.
 
 - `name`: Human-readable display name shown to users
 - `folder`: Directory where agent-specific files are stored (relative to project root)
+- `commands_subdir`: Subdirectory name within the agent folder where command/prompt files are stored (default: `"commands"`)
+  - Most agents use `"commands"` (e.g., `.claude/commands/`)
+  - Some agents use alternative names: `"agents"` (copilot), `"workflows"` (windsurf, kilocode, agy), `"prompts"` (codex, q), `"command"` (opencode - singular)
+  - This field enables `--ai-skills` to locate command templates correctly for skill generation
 - `install_url`: Installation documentation URL (set to `None` for IDE-based agents)
 - `requires_cli`: Whether the agent requires a CLI tool check during initialization
 
@@ -313,7 +319,7 @@ Require a command-line tool to be installed:
 - **opencode**: `opencode` CLI
 - **Amazon Q Developer CLI**: `q` CLI
 - **CodeBuddy CLI**: `codebuddy` CLI
-- **Qoder CLI**: `qoder` CLI
+- **Qoder CLI**: `qodercli` CLI
 - **Amp**: `amp` CLI
 - **SHAI**: `shai` CLI
 

CHANGELOG.md

@@ -2,312 +2,81 @@
 
 <!-- markdownlint-disable MD024 -->
 
-
+Recent changes to the Specify CLI and templates are documented here.
-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.1.1] - 2026-02-13
+## [0.1.6] - 2026-02-23
-
-### Added
-
-- **Agent Skills Installation**: New `--ai-skills` CLI option to install Prompt.MD templates as agent skills following [agentskills.io specification](https://agentskills.io/specification)
-  - Skills are installed to agent-specific directories (e.g., `.claude/skills/`, `.gemini/skills/`, `.github/skills/`)
-  - Codex uses `.agents/skills/` following Codex agent directory conventions
-  - Default fallback directory is `.agents/skills/` for agents without a specific mapping
-  - Requires `--ai` flag to be specified
-  - Converts all 9 spec-kit command templates (specify, plan, tasks, implement, analyze, clarify, constitution, checklist, taskstoissues) to properly formatted SKILL.md files
-  - **New projects**: command files are not installed when `--ai-skills` is used (skills replace commands)
-  - **Existing repos** (`--here`): pre-existing command files are preserved — no breaking changes
-  - `pyyaml` dependency (already present) used for YAML frontmatter parsing
-- **Unit tests** for `install_ai_skills`, `_get_skills_dir`, and `--ai-skills` CLI validation (51 test cases covering all 18 supported agents)
-
-## [0.1.0] - 2026-01-28
-
-### Added
-
-- **Extension System**: Introduced modular extension architecture for Spec Kit
-  - Extensions are self-contained packages that add commands and functionality without bloating core
-  - Extension manifest schema (`extension.yml`) with validation
-  - Extension registry (`.specify/extensions/.registry`) for tracking installed extensions
-  - Extension manager module (`src/specify_cli/extensions.py`) for installation/removal
-  - New CLI commands:
-    - `specify extension list` - List installed extensions
-    - `specify extension add` - Install extension from local directory or URL
-    - `specify extension remove` - Uninstall extension
-    - `specify extension search` - Search extension catalog
-    - `specify extension info` - Show detailed extension information
-  - Semantic versioning compatibility checks
-  - Support for extension configuration files
-  - Command registration system for AI agents (Claude support initially)
-  - Added dependencies: `pyyaml>=6.0`, `packaging>=23.0`
-
-- **Extension Catalog**: Extension discovery and distribution system
-  - Central catalog (`extensions/catalog.json`) for published extensions
-  - Extension catalog manager (`ExtensionCatalog` class) with:
-    - Catalog fetching from GitHub
-    - 1-hour local caching for performance
-    - Search by query, tag, author, or verification status
-    - Extension info retrieval
-  - Catalog cache stored in `.specify/extensions/.cache/`
-  - Search and info commands with rich console output
-  - Added 9 catalog-specific unit tests (100% pass rate)
-
-- **Jira Extension**: First official extension for Jira integration
-  - Extension ID: `jira`
-  - Version: 1.0.0
-  - Commands:
-    - `/speckit.jira.specstoissues` - Create Jira hierarchy from spec and tasks
-    - `/speckit.jira.discover-fields` - Discover Jira custom fields
-    - `/speckit.jira.sync-status` - Sync task completion status
-  - Comprehensive documentation (README, usage guide, examples)
-  - MIT licensed
-
-- **Hook System**: Extension lifecycle hooks for automation
-  - `HookExecutor` class for managing extension hooks
-  - Hooks registered in `.specify/extensions.yml`
-  - Hook registration during extension installation
-  - Hook unregistration during extension removal
-  - Support for optional and mandatory hooks
-  - Hook execution messages for AI agent integration
-  - Condition support for conditional hook execution (placeholder)
-
-- **Extension Management**: Advanced extension management commands
-  - `specify extension update` - Check and update extensions to latest version
-  - `specify extension enable` - Enable a disabled extension
-  - `specify extension disable` - Disable extension without removing it
-  - Version comparison with catalog
-  - Update notifications
-  - Preserve configuration during updates
-
-- **Multi-Agent Support**: Extensions now work with all supported AI agents (Phase 6)
-  - Automatic detection and registration for all agents in project
-  - Support for 16+ AI agents (Claude, Gemini, Copilot, Cursor, Qwen, and more)
-  - Agent-specific command formats (Markdown and TOML)
-  - Automatic argument placeholder conversion ($ARGUMENTS → {{args}})
-  - Commands registered for all detected agents during installation
-  - Multi-agent command unregistration on extension removal
-  - `CommandRegistrar.register_commands_for_agent()` method
-  - `CommandRegistrar.register_commands_for_all_agents()` method
-
-- **Configuration Layers**: Full configuration cascade system (Phase 6)
-  - **Layer 1**: Defaults from extension manifest (`extension.yml`)
-  - **Layer 2**: Project config (`.specify/extensions/{ext-id}/{ext-id}-config.yml`)
-  - **Layer 3**: Local config (`.specify/extensions/{ext-id}/local-config.yml`, gitignored)
-  - **Layer 4**: Environment variables (`SPECKIT_{EXT_ID}_{KEY}` pattern)
-  - Recursive config merging with proper precedence
-  - `ConfigManager` class for programmatic config access
-  - `get_config()`, `get_value()`, `has_value()` methods
-  - Support for nested configuration paths with dot-notation
-
-- **Hook Condition Evaluation**: Smart hook execution based on runtime conditions (Phase 6)
-  - Config conditions: `config.key.path is set`, `config.key == 'value'`, `config.key != 'value'`
-  - Environment conditions: `env.VAR is set`, `env.VAR == 'value'`, `env.VAR != 'value'`
-  - Automatic filtering of hooks based on condition evaluation
-  - Safe fallback behavior on evaluation errors
-  - Case-insensitive pattern matching
-
-- **Hook Integration**: Agent-level hook checking and execution (Phase 6)
-  - `check_hooks_for_event()` method for AI agents to query hooks after core commands
-  - Condition-aware hook filtering before execution
-  - `enable_hooks()` and `disable_hooks()` methods per extension
-  - Formatted hook messages for agent display
-  - `execute_hook()` method for hook execution information
-
-- **Documentation Suite**: Comprehensive documentation for users and developers
-  - **EXTENSION-USER-GUIDE.md**: Complete user guide with installation, usage, configuration, and troubleshooting
-  - **EXTENSION-API-REFERENCE.md**: Technical API reference with manifest schema, Python API, and CLI commands
-  - **EXTENSION-PUBLISHING-GUIDE.md**: Publishing guide for extension authors
-  - **RFC-EXTENSION-SYSTEM.md**: Extension architecture design document
-
-- **Extension Template**: Starter template in `extensions/template/` for creating new extensions
-  - Fully commented `extension.yml` manifest template
-  - Example command file with detailed explanations
-  - Configuration template with all options
-  - Complete project structure (README, LICENSE, CHANGELOG, .gitignore)
-  - EXAMPLE-README.md showing final documentation format
-
-- **Unit Tests**: Comprehensive test suite with 39 tests covering all extension system components
-  - Test coverage: 83% of extension module code
-  - Test dependencies: `pytest>=7.0`, `pytest-cov>=4.0`
-  - Configured pytest in `pyproject.toml`
-
-### Changed
-
-- Version bumped to 0.1.0 (minor release for new feature)
-
-## [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
-
-### 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.
-
-### 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.
+- **Parameter Ordering Issues (#1641)**: Fixed CLI parameter parsing issue where option flags were incorrectly consumed as values for preceding options
+  - Added validation to detect when `--ai` or `--ai-commands-dir` incorrectly consume following flags like `--here` or `--ai-skills`
+  - Now provides clear error messages: "Invalid value for --ai: '--here'"
+  - Includes helpful hints suggesting proper usage and listing available agents
+  - Commands like `specify init --ai-skills --ai --here` now fail with actionable feedback instead of confusing "Must specify project name" errors
+  - Added comprehensive test suite (5 new tests) to prevent regressions
 
-## [0.0.9] - 2025-09-19
+## [0.1.5] - 2026-02-21
-
-### 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
 
 ### Fixed
 
-N/A
+- **AI Skills Installation Bug (#1658)**: Fixed `--ai-skills` flag not generating skill files for GitHub Copilot and other agents with non-standard command directory structures
+  - Added `commands_subdir` field to `AGENT_CONFIG` to explicitly specify the subdirectory name for each agent
+  - Affected agents now work correctly: copilot (`.github/agents/`), opencode (`.opencode/command/`), windsurf (`.windsurf/workflows/`), codex (`.codex/prompts/`), kilocode (`.kilocode/workflows/`), q (`.amazonq/prompts/`), and agy (`.agent/workflows/`)
+  - The `install_ai_skills()` function now uses the correct path for all agents instead of assuming `commands/` for everyone
 
-### Changed
+## [0.1.4] - 2026-02-20
 
-N/A
+### Fixed
+
+- **Qoder CLI detection**: Renamed `AGENT_CONFIG` key from `"qoder"` to `"qodercli"` to match the actual executable name, fixing `specify check` and `specify init --ai` detection failures
+
+## [0.1.3] - 2026-02-20
+
+### Added
+
+- **Generic Agent Support**: Added `--ai generic` option for unsupported AI agents ("bring your own agent")
+  - Requires `--ai-commands-dir <path>` to specify where the agent reads commands from
+  - Generates Markdown commands with `$ARGUMENTS` format (compatible with most agents)
+  - Example: `specify init my-project --ai generic --ai-commands-dir .myagent/commands/`
+  - Enables users to start with Spec Kit immediately while their agent awaits formal support
+
+## [0.0.102] - 2026-02-20
+
+- fix: include 'src/**' path in release workflow triggers (#1646)
+
+## [0.0.101] - 2026-02-19
+
+- chore(deps): bump github/codeql-action from 3 to 4 (#1635)
+
+## [0.0.100] - 2026-02-19
+
+- Add pytest and Python linting (ruff) to CI (#1637)
+- feat: add pull request template for better contribution guidelines (#1634)
+
+## [0.0.99] - 2026-02-19
+
+- Feat/ai skills (#1632)
+
+## [0.0.98] - 2026-02-19
+
+- chore(deps): bump actions/stale from 9 to 10 (#1623)
+- feat: add dependabot configuration for pip and GitHub Actions updates (#1622)
+
+## [0.0.97] - 2026-02-18
+
+- Remove Maintainers section from README.md (#1618)
+
+## [0.0.96] - 2026-02-17
+
+- fix: typo in plan-template.md (#1446)
+
+## [0.0.95] - 2026-02-12
+
+- Feat: add a new agent: Google Anti Gravity (#1220)
+
+## [0.0.94] - 2026-02-11
+
+- Add stale workflow for 180-day inactive issues and PRs (#1594)

README.md

@@ -162,6 +162,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
 | [SHAI (OVHcloud)](https://github.com/ovh/shai)                                       | ✅      |                                                                                                                                           |
 | [Windsurf](https://windsurf.com/)                                                    | ✅      |                                                                                                                                           |
 | [Antigravity (agy)](https://agy.ai/)                                                 | ✅      |                                                                                                                                           |
+| Generic                                                                              | ✅      | Bring your own agent — use `--ai generic --ai-commands-dir <path>` for unsupported agents                                                 |
 
 ## 🔧 Specify CLI Reference
 
@@ -172,14 +173,15 @@ The `specify` command supports the following options:
 | 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`) |
+| `check` | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `shai`, `qodercli`) |
 
 ### `specify init` Arguments & Options
 
 | Argument/Option        | Type     | Description                                                                                                                                                                                  |
 | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `<project-name>`       | 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`, `agy`, `bob`, or `qoder` |
+| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `agy`, `bob`, `qodercli`, or `generic` (requires `--ai-commands-dir`) |
+| `--ai-commands-dir`    | Option   | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`)                                                                                                  |
 | `--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                                                                                                                                                           |
@@ -203,7 +205,7 @@ specify init my-project --ai claude
 specify init my-project --ai cursor-agent
 
 # Initialize with Qoder support
-specify init my-project --ai qoder
+specify init my-project --ai qodercli
 
 # Initialize with Windsurf support
 specify init my-project --ai windsurf
@@ -217,6 +219,9 @@ specify init my-project --ai shai
 # Initialize with IBM Bob support
 specify init my-project --ai bob
 
+# Initialize with an unsupported agent (generic / bring your own agent)
+specify init my-project --ai generic --ai-commands-dir .myagent/commands/
+
 # Initialize with PowerShell scripts (Windows/cross-platform)
 specify init my-project --ai copilot --script ps
 

docs/quickstart.md

@@ -81,6 +81,9 @@ Then, use the `/speckit.implement` slash command to execute the plan.
 /speckit.implement
 ```
 
+> [!TIP]
+> **Phased Implementation**: For complex projects, implement in phases to avoid overwhelming the agent's context. Start with core functionality, validate it works, then add features incrementally.
+
 ## Detailed Example: Building Taskify
 
 Here's a complete example of building a team productivity platform:
@@ -135,7 +138,15 @@ Be specific about your tech stack and technical requirements:
 /speckit.plan 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.
 ```
 
-### Step 6: Validate and Implement
+### Step 6: Define Tasks
+
+Generate an actionable task list using the `/speckit.tasks` command:
+
+```bash
+/speckit.tasks
+```
+
+### Step 7: Validate and Implement
 
 Have your AI agent audit the implementation plan using `/speckit.analyze`:
 
@@ -149,6 +160,9 @@ Finally, implement the solution:
 /speckit.implement
 ```
 
+> [!TIP]
+> **Phased Implementation**: For large projects like Taskify, consider implementing in phases (e.g., Phase 1: Basic project/task structure, Phase 2: Kanban functionality, Phase 3: Comments and assignments). This prevents context saturation and allows for validation at each stage.
+
 ## Key Principles
 
 - **Be explicit** about what you're building and why

extensions/EXTENSION-USER-GUIDE.md

@@ -46,7 +46,7 @@ Extensions are modular packages that add new commands and functionality to Spec
 ### Check Your Version
 
 ```bash
-specify --version
+specify version
 # Should show 0.1.0 or higher
 ```
 

extensions/README.md

@@ -0,0 +1,14 @@
+# Spec Kit Community Extensions
+
+Community-contributed extensions for [Spec Kit](https://github.com/github/spec-kit).
+
+## Available Extensions
+
+| Extension | Purpose | URL |
+|-----------|---------|-----|
+| V-Model Extension Pack | Enforces V-Model paired generation of development specs and test specs with full traceability | [spec-kit-v-model](https://github.com/leocamello/spec-kit-v-model) |
+| Cleanup Extension | Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues | [spec-kit-cleanup](https://github.com/dsrednicki/spec-kit-cleanup) |
+
+## Adding Your Extension
+
+See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for instructions on how to submit your extension to the community catalog.

extensions/catalog.community.json

@@ -0,0 +1,85 @@
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-02-24T00:00:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json",
+  "extensions": {
+    "cleanup": {
+      "name": "Cleanup Extension",
+      "id": "cleanup",
+      "description": "Post-implementation quality gate that reviews changes, fixes small issues (scout rule), creates tasks for medium issues, and generates analysis for large issues.",
+      "author": "dsrednicki",
+      "version": "1.0.0",
+      "download_url": "https://github.com/dsrednicki/spec-kit-cleanup/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/dsrednicki/spec-kit-cleanup",
+      "homepage": "https://github.com/dsrednicki/spec-kit-cleanup",
+      "documentation": "https://github.com/dsrednicki/spec-kit-cleanup/blob/main/README.md",
+      "changelog": "https://github.com/dsrednicki/spec-kit-cleanup/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 1
+      },
+      "tags": ["quality", "tech-debt", "review", "cleanup", "scout-rule"],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-02-22T00:00:00Z",
+      "updated_at": "2026-02-22T00:00:00Z"
+    },
+    "retrospective": {
+      "name": "Retrospective Extension",
+      "id": "retrospective",
+      "description": "Post-implementation retrospective with spec adherence scoring, drift analysis, and human-gated spec updates.",
+      "author": "emi-dm",
+      "version": "1.0.0",
+      "download_url": "https://github.com/emi-dm/spec-kit-retrospective/archive/refs/tags/v1.0.0.zip",
+      "repository": "https://github.com/emi-dm/spec-kit-retrospective",
+      "homepage": "https://github.com/emi-dm/spec-kit-retrospective",
+      "documentation": "https://github.com/emi-dm/spec-kit-retrospective/blob/main/README.md",
+      "changelog": "https://github.com/emi-dm/spec-kit-retrospective/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 1,
+        "hooks": 1
+      },
+      "tags": ["retrospective", "spec-drift", "quality", "analysis", "governance"],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-02-24T00:00:00Z",
+      "updated_at": "2026-02-24T00:00:00Z"
+    },
+    "v-model": {
+      "name": "V-Model Extension Pack",
+      "id": "v-model",
+      "description": "Enforces V-Model paired generation of development specs and test specs with full traceability.",
+      "author": "leocamello",
+      "version": "0.4.0",
+      "download_url": "https://github.com/leocamello/spec-kit-v-model/archive/refs/tags/v0.4.0.zip",
+      "repository": "https://github.com/leocamello/spec-kit-v-model",
+      "homepage": "https://github.com/leocamello/spec-kit-v-model",
+      "documentation": "https://github.com/leocamello/spec-kit-v-model/blob/main/README.md",
+      "changelog": "https://github.com/leocamello/spec-kit-v-model/blob/main/CHANGELOG.md",
+      "license": "MIT",
+      "requires": {
+        "speckit_version": ">=0.1.0"
+      },
+      "provides": {
+        "commands": 9,
+        "hooks": 1
+      },
+      "tags": ["v-model", "traceability", "testing", "compliance", "safety-critical"],
+      "verified": false,
+      "downloads": 0,
+      "stars": 0,
+      "created_at": "2026-02-20T00:00:00Z",
+      "updated_at": "2026-02-22T00:00:00Z"
+    }
+  }
+}

extensions/catalog.example.json

@@ -1,60 +0,0 @@
-{
-  "schema_version": "1.0",
-  "updated_at": "2026-02-03T00:00:00Z",
-  "catalog_url": "https://your-org.example.com/speckit/catalog.json",
-  "extensions": {
-    "jira": {
-      "name": "Jira Integration",
-      "id": "jira",
-      "description": "Create Jira Epics, Stories, and Issues from spec-kit artifacts",
-      "author": "Your Organization",
-      "version": "2.1.0",
-      "download_url": "https://github.com/your-org/spec-kit-jira/archive/refs/tags/v2.1.0.zip",
-      "repository": "https://github.com/your-org/spec-kit-jira",
-      "homepage": "https://github.com/your-org/spec-kit-jira",
-      "documentation": "https://github.com/your-org/spec-kit-jira/blob/main/README.md",
-      "changelog": "https://github.com/your-org/spec-kit-jira/blob/main/CHANGELOG.md",
-      "license": "MIT",
-      "requires": {
-        "speckit_version": ">=0.1.0",
-        "tools": [
-          {
-            "name": "atlassian",
-            "version": ">=1.0.0",
-            "required": true
-          }
-        ]
-      },
-      "provides": {
-        "commands": 3,
-        "hooks": 1
-      },
-      "tags": ["jira", "atlassian", "issue-tracking"],
-      "verified": true,
-      "downloads": 0,
-      "stars": 0,
-      "created_at": "2026-01-28T00:00:00Z",
-      "updated_at": "2026-02-03T00:00:00Z"
-    },
-    "linear": {
-      "name": "Linear Integration",
-      "id": "linear",
-      "description": "Sync specs and tasks with Linear issues",
-      "author": "Your Organization",
-      "version": "1.0.0",
-      "download_url": "https://github.com/your-org/spec-kit-linear/archive/refs/tags/v1.0.0.zip",
-      "repository": "https://github.com/your-org/spec-kit-linear",
-      "license": "MIT",
-      "requires": {
-        "speckit_version": ">=0.1.0"
-      },
-      "provides": {
-        "commands": 2
-      },
-      "tags": ["linear", "issue-tracking"],
-      "verified": false,
-      "created_at": "2026-01-30T00:00:00Z",
-      "updated_at": "2026-01-30T00:00:00Z"
-    }
-  }
-}

pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "specify-cli"
-version = "0.1.1"
+version = "0.1.6"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
     "typer",
+    "click>=8.1",
     "rich",
     "httpx[socks]",
     "platformdirs",

scripts/bash/update-agent-context.sh

@@ -35,7 +35,7 @@
 #    - Creates default Claude file if no agent files exist
 #
 # Usage: ./update-agent-context.sh [agent_type]
-# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli
 # Leave empty to update all existing agent files
 
 set -e
@@ -619,7 +619,7 @@ update_specific_agent() {
         codebuddy)
             update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
             ;;
-        qoder)
+        qodercli)
             update_agent_file "$QODER_FILE" "Qoder CLI"
             ;;
         amp)
@@ -637,9 +637,12 @@ update_specific_agent() {
         bob)
             update_agent_file "$BOB_FILE" "IBM Bob"
             ;;
+        generic)
+            log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+            ;;
         *)
             log_error "Unknown agent type '$agent_type'"
-            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|agy|bob|qoder"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli|generic"
             exit 1
             ;;
     esac
@@ -752,7 +755,7 @@ print_summary() {
     
     echo
 
-    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder]"
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli]"
 }
 
 #==============================================================================

scripts/powershell/update-agent-context.ps1

@@ -9,7 +9,7 @@ Mirrors the behavior of scripts/bash/update-agent-context.sh:
  2. Plan Data Extraction
  3. Agent File Management (create from template or update existing)
  4. Content Generation (technology stack, recent changes, timestamp)
- 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, agy, bob, qoder)
+ 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, shai, q, agy, bob, qodercli)
 
 .PARAMETER AgentType
 Optional agent key to update a single agent. If omitted, updates all existing agent files (creating a default Claude file if none exist).
@@ -25,7 +25,7 @@ Relies on common helper functions in common.ps1
 #>
 param(
     [Parameter(Position=0)]
-    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','shai','q','agy','bob','qoder')]
+    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','amp','shai','q','agy','bob','qodercli','generic')]
     [string]$AgentType
 )
 
@@ -384,13 +384,14 @@ function Update-SpecificAgent {
         'auggie'   { Update-AgentFile -TargetFile $AUGGIE_FILE   -AgentName 'Auggie CLI' }
         'roo'      { Update-AgentFile -TargetFile $ROO_FILE      -AgentName 'Roo Code' }
         'codebuddy' { Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI' }
-        'qoder'    { Update-AgentFile -TargetFile $QODER_FILE    -AgentName 'Qoder CLI' }
+        'qodercli' { Update-AgentFile -TargetFile $QODER_FILE    -AgentName 'Qoder CLI' }
         'amp'      { Update-AgentFile -TargetFile $AMP_FILE      -AgentName 'Amp' }
         'shai'     { Update-AgentFile -TargetFile $SHAI_FILE     -AgentName 'SHAI' }
         'q'        { Update-AgentFile -TargetFile $Q_FILE        -AgentName 'Amazon Q Developer CLI' }
         'agy'      { Update-AgentFile -TargetFile $AGY_FILE      -AgentName 'Antigravity' }
         'bob'      { Update-AgentFile -TargetFile $BOB_FILE      -AgentName 'IBM Bob' }
-        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder'; return $false }
+        'generic'  { Write-Info 'Generic agent: no predefined context file. Use the agent-specific update script for your agent.' }
+        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli|generic'; return $false }
     }
 }
 
@@ -427,7 +428,7 @@ function Print-Summary {
     if ($NEW_FRAMEWORK) { Write-Host "  - Added framework: $NEW_FRAMEWORK" }
     if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host "  - Added database: $NEW_DB" }
     Write-Host ''
-    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qoder]'
+    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|q|agy|bob|qodercli|generic]'
 }
 
 function Main {

src/specify_cli/__init__.py

@@ -123,116 +123,141 @@ def _format_rate_limit_error(status_code: int, headers: httpx.Headers, url: str)
     
     return "\n".join(lines)
 
-# Agent configuration with name, folder, install URL, and CLI tool requirement
+# Agent configuration with name, folder, install URL, CLI tool requirement, and commands subdirectory
 AGENT_CONFIG = {
     "copilot": {
         "name": "GitHub Copilot",
         "folder": ".github/",
+        "commands_subdir": "agents",  # Special: uses agents/ not commands/
         "install_url": None,  # IDE-based, no CLI check needed
         "requires_cli": False,
     },
     "claude": {
         "name": "Claude Code",
         "folder": ".claude/",
+        "commands_subdir": "commands",
         "install_url": "https://docs.anthropic.com/en/docs/claude-code/setup",
         "requires_cli": True,
     },
     "gemini": {
         "name": "Gemini CLI",
         "folder": ".gemini/",
+        "commands_subdir": "commands",
         "install_url": "https://github.com/google-gemini/gemini-cli",
         "requires_cli": True,
     },
     "cursor-agent": {
         "name": "Cursor",
         "folder": ".cursor/",
+        "commands_subdir": "commands",
         "install_url": None,  # IDE-based
         "requires_cli": False,
     },
     "qwen": {
         "name": "Qwen Code",
         "folder": ".qwen/",
+        "commands_subdir": "commands",
         "install_url": "https://github.com/QwenLM/qwen-code",
         "requires_cli": True,
     },
     "opencode": {
         "name": "opencode",
         "folder": ".opencode/",
+        "commands_subdir": "command",  # Special: singular 'command' not 'commands'
         "install_url": "https://opencode.ai",
         "requires_cli": True,
     },
     "codex": {
         "name": "Codex CLI",
         "folder": ".codex/",
+        "commands_subdir": "prompts",  # Special: uses prompts/ not commands/
         "install_url": "https://github.com/openai/codex",
         "requires_cli": True,
     },
     "windsurf": {
         "name": "Windsurf",
         "folder": ".windsurf/",
+        "commands_subdir": "workflows",  # Special: uses workflows/ not commands/
         "install_url": None,  # IDE-based
         "requires_cli": False,
     },
     "kilocode": {
         "name": "Kilo Code",
         "folder": ".kilocode/",
+        "commands_subdir": "workflows",  # Special: uses workflows/ not commands/
         "install_url": None,  # IDE-based
         "requires_cli": False,
     },
     "auggie": {
         "name": "Auggie CLI",
         "folder": ".augment/",
+        "commands_subdir": "commands",
         "install_url": "https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli",
         "requires_cli": True,
     },
     "codebuddy": {
         "name": "CodeBuddy",
         "folder": ".codebuddy/",
+        "commands_subdir": "commands",
         "install_url": "https://www.codebuddy.ai/cli",
         "requires_cli": True,
     },
-    "qoder": {
+    "qodercli": {
         "name": "Qoder CLI",
         "folder": ".qoder/",
+        "commands_subdir": "commands",
         "install_url": "https://qoder.com/cli",
         "requires_cli": True,
     },
     "roo": {
         "name": "Roo Code",
         "folder": ".roo/",
+        "commands_subdir": "commands",
         "install_url": None,  # IDE-based
         "requires_cli": False,
     },
     "q": {
         "name": "Amazon Q Developer CLI",
         "folder": ".amazonq/",
+        "commands_subdir": "prompts",  # Special: uses prompts/ not commands/
         "install_url": "https://aws.amazon.com/developer/learning/q-developer-cli/",
         "requires_cli": True,
     },
     "amp": {
         "name": "Amp",
         "folder": ".agents/",
+        "commands_subdir": "commands",
         "install_url": "https://ampcode.com/manual#install",
         "requires_cli": True,
     },
     "shai": {
         "name": "SHAI",
         "folder": ".shai/",
+        "commands_subdir": "commands",
         "install_url": "https://github.com/ovh/shai",
         "requires_cli": True,
     },
     "agy": {
         "name": "Antigravity",
         "folder": ".agent/",
+        "commands_subdir": "workflows",  # Special: uses workflows/ not commands/
         "install_url": None,  # IDE-based
         "requires_cli": False,
     },
     "bob": {
         "name": "IBM Bob",
         "folder": ".bob/",
+        "commands_subdir": "commands",
         "install_url": None,  # IDE-based
         "requires_cli": False,
     },
+    "generic": {
+        "name": "Generic (bring your own agent)",
+        "folder": None,  # Set dynamically via --ai-commands-dir
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": False,
+    },
 }
 
 SCRIPT_TYPE_CHOICES = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}
@@ -1050,10 +1075,11 @@ def install_ai_skills(project_path: Path, selected_ai: str, tracker: StepTracker
     # download_and_extract_template() already placed the .md files here.
     agent_config = AGENT_CONFIG.get(selected_ai, {})
     agent_folder = agent_config.get("folder", "")
+    commands_subdir = agent_config.get("commands_subdir", "commands")
     if agent_folder:
-        templates_dir = project_path / agent_folder.rstrip("/") / "commands"
+        templates_dir = project_path / agent_folder.rstrip("/") / commands_subdir
     else:
-        templates_dir = project_path / "commands"
+        templates_dir = project_path / commands_subdir
 
     if not templates_dir.exists() or not any(templates_dir.glob("*.md")):
         # Fallback: try the repo-relative path (for running from source checkout)
@@ -1188,7 +1214,8 @@ def install_ai_skills(project_path: Path, selected_ai: str, tracker: StepTracker
 @app.command()
 def init(
     project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here, or use '.' for current directory)"),
-    ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, shai, q, agy, bob, or qoder "),
+    ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, amp, shai, q, agy, bob, qodercli, or generic (requires --ai-commands-dir)"),
+    ai_commands_dir: str = typer.Option(None, "--ai-commands-dir", help="Directory for agent command files (required with --ai generic, e.g. .myagent/commands/)"),
     script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"),
     ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for AI agent tools like Claude Code"),
     no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"),
@@ -1224,10 +1251,25 @@ def init(
         specify init --here --force  # Skip confirmation when current directory not empty
         specify init my-project --ai claude --ai-skills   # Install agent skills
         specify init --here --ai gemini --ai-skills
+        specify init my-project --ai generic --ai-commands-dir .myagent/commands/  # Unsupported agent
     """
 
     show_banner()
 
+    # Detect when option values are likely misinterpreted flags (parameter ordering issue)
+    if ai_assistant and ai_assistant.startswith("--"):
+        console.print(f"[red]Error:[/red] Invalid value for --ai: '{ai_assistant}'")
+        console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai?")
+        console.print("[yellow]Example:[/yellow] specify init --ai claude --here")
+        console.print(f"[yellow]Available agents:[/yellow] {', '.join(AGENT_CONFIG.keys())}")
+        raise typer.Exit(1)
+    
+    if ai_commands_dir and ai_commands_dir.startswith("--"):
+        console.print(f"[red]Error:[/red] Invalid value for --ai-commands-dir: '{ai_commands_dir}'")
+        console.print("[yellow]Hint:[/yellow] Did you forget to provide a value for --ai-commands-dir?")
+        console.print("[yellow]Example:[/yellow] specify init --ai generic --ai-commands-dir .myagent/commands/")
+        raise typer.Exit(1)
+
     if project_name == ".":
         here = True
         project_name = None  # Clear project_name to use existing validation logic
@@ -1308,6 +1350,16 @@ def init(
             "copilot"
         )
 
+    # Validate --ai-commands-dir usage
+    if selected_ai == "generic":
+        if not ai_commands_dir:
+            console.print("[red]Error:[/red] --ai-commands-dir is required when using --ai generic")
+            console.print("[dim]Example: specify init my-project --ai generic --ai-commands-dir .myagent/commands/[/dim]")
+            raise typer.Exit(1)
+    elif ai_commands_dir:
+        console.print(f"[red]Error:[/red] --ai-commands-dir can only be used with --ai generic (not '{selected_ai}')")
+        raise typer.Exit(1)
+
     if not ignore_agent_tools:
         agent_config = AGENT_CONFIG.get(selected_ai)
         if agent_config and agent_config["requires_cli"]:
@@ -1383,6 +1435,18 @@ def init(
 
             download_and_extract_template(project_path, selected_ai, selected_script, here, verbose=False, tracker=tracker, client=local_client, debug=debug, github_token=github_token)
 
+            # For generic agent, rename placeholder directory to user-specified path
+            if selected_ai == "generic" and ai_commands_dir:
+                placeholder_dir = project_path / ".speckit" / "commands"
+                target_dir = project_path / ai_commands_dir
+                if placeholder_dir.is_dir():
+                    target_dir.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.move(str(placeholder_dir), str(target_dir))
+                    # Clean up empty .speckit dir if it's now empty
+                    speckit_dir = project_path / ".speckit"
+                    if speckit_dir.is_dir() and not any(speckit_dir.iterdir()):
+                        speckit_dir.rmdir()
+
             ensure_executable_scripts(project_path, tracker=tracker)
 
             ensure_constitution_from_template(project_path, tracker=tracker)
@@ -1468,16 +1532,17 @@ def init(
     # Agent folder security notice
     agent_config = AGENT_CONFIG.get(selected_ai)
     if agent_config:
-        agent_folder = agent_config["folder"]
+        agent_folder = ai_commands_dir if selected_ai == "generic" else agent_config["folder"]
-        security_notice = Panel(
+        if agent_folder:
-            f"Some agents may store credentials, auth tokens, or other identifying and private artifacts in the agent folder within your project.\n"
+            security_notice = Panel(
-            f"Consider adding [cyan]{agent_folder}[/cyan] (or parts of it) to [cyan].gitignore[/cyan] to prevent accidental credential leakage.",
+                f"Some agents may store credentials, auth tokens, or other identifying and private artifacts in the agent folder within your project.\n"
-            title="[yellow]Agent Folder Security[/yellow]",
+                f"Consider adding [cyan]{agent_folder}[/cyan] (or parts of it) to [cyan].gitignore[/cyan] to prevent accidental credential leakage.",
-            border_style="yellow",
+                title="[yellow]Agent Folder Security[/yellow]",
-            padding=(1, 2)
+                border_style="yellow",
-        )
+                padding=(1, 2)
-        console.print()
+            )
-        console.print(security_notice)
+            console.print()
+            console.print(security_notice)
 
     steps_lines = []
     if not here:
@@ -1535,6 +1600,8 @@ def check():
 
     agent_results = {}
     for agent_key, agent_config in AGENT_CONFIG.items():
+        if agent_key == "generic":
+            continue  # Generic is not a real agent to check
         agent_name = agent_config["name"]
         requires_cli = agent_config["requires_cli"]
 

src/specify_cli/extensions.py

@@ -647,7 +647,7 @@ class CommandRegistrar:
             "args": "$ARGUMENTS",
             "extension": ".md"
         },
-        "qoder": {
+        "qodercli": {
             "dir": ".qoder/commands",
             "format": "markdown",
             "args": "$ARGUMENTS",

templates/commands/plan.md

@@ -75,10 +75,11 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Validation rules from requirements
    - State transitions if applicable
 
-2. **Generate API contracts** from functional requirements:
+2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
-   - For each user action → endpoint
+   - Identify what interfaces the project exposes to users or other systems
-   - Use standard REST/GraphQL patterns
+   - Document the contract format appropriate for the project type
-   - Output OpenAPI/GraphQL schema to `/contracts/`
+   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
+   - Skip if project is purely internal (build scripts, one-off tools, etc.)
 
 3. **Agent context update**:
    - Run `{AGENT_SCRIPT}`

templates/commands/specify.md

@@ -235,7 +235,7 @@ When creating this spec from a user prompt:
 - Performance targets: Standard web/mobile app expectations unless specified
 - Error handling: User-friendly messages with appropriate fallbacks
 - Authentication method: Standard session-based or OAuth2 for web apps
-- Integration patterns: RESTful APIs unless specified otherwise
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
 
 ### Success Criteria Guidelines
 

templates/commands/tasks.md

@@ -28,14 +28,14 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 2. **Load design documents**: Read from FEATURE_DIR:
    - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
-   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
    - Note: Not all projects have all documents. Generate tasks based on what's available.
 
 3. **Execute task generation workflow**:
    - Load plan.md and extract tech stack, libraries, project structure
    - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
    - If data-model.md exists: Extract entities and map to user stories
-   - If contracts/ exists: Map endpoints to user stories
+   - If contracts/ exists: Map interface contracts to user stories
    - If research.md exists: Extract decisions for setup tasks
    - Generate tasks organized by user story (see Task Generation Rules below)
    - Generate dependency graph showing user story completion order
@@ -112,13 +112,13 @@ Every task MUST strictly follow this format:
    - Map all related components to their story:
      - Models needed for that story
      - Services needed for that story
-     - Endpoints/UI needed for that story
+     - Interfaces/UI needed for that story
      - If tests requested: Tests specific to that story
    - Mark story dependencies (most stories should be independent)
 
 2. **From Contracts**:
-   - Map each contract/endpoint → to the user story it serves
+   - Map each interface contract → to the user story it serves
-   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
 
 3. **From Data Model**:
    - Map each entity to the user story(ies) that need it

templates/plan-template.md

@@ -22,7 +22,7 @@
 **Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
 **Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
 **Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
-**Project Type**: [single/web/mobile - determines source structure]  
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
 **Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
 **Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
 **Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]

tests/test_ai_skills.py

@@ -380,7 +380,7 @@ class TestInstallAiSkills:
         # .toml commands should be untouched
         assert (cmds_dir / "speckit.specify.toml").exists()
 
-    @pytest.mark.parametrize("agent_key", list(AGENT_CONFIG.keys()))
+    @pytest.mark.parametrize("agent_key", [k for k in AGENT_CONFIG.keys() if k != "generic"])
     def test_skills_install_for_all_agents(self, temp_dir, agent_key):
         """install_ai_skills should produce skills for every configured agent."""
         proj = temp_dir / f"proj-{agent_key}"
@@ -630,3 +630,65 @@ class TestCliValidation:
         plain = re.sub(r'\x1b\[[0-9;]*m', '', result.output)
         assert "--ai-skills" in plain
         assert "agent skills" in plain.lower()
+
+
+class TestParameterOrderingIssue:
+    """Test fix for GitHub issue #1641: parameter ordering issues."""
+
+    def test_ai_flag_consuming_here_flag(self):
+        """--ai without value should not consume --here flag (issue #1641)."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        # This used to fail with "Must specify project name" because --here was consumed by --ai
+        result = runner.invoke(app, ["init", "--ai-skills", "--ai", "--here"])
+
+        assert result.exit_code == 1
+        assert "Invalid value for --ai" in result.output
+        assert "--here" in result.output  # Should mention the invalid value
+
+    def test_ai_flag_consuming_ai_skills_flag(self):
+        """--ai without value should not consume --ai-skills flag."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        # This should fail with helpful error about missing --ai value
+        result = runner.invoke(app, ["init", "--here", "--ai", "--ai-skills"])
+
+        assert result.exit_code == 1
+        assert "Invalid value for --ai" in result.output
+        assert "--ai-skills" in result.output  # Should mention the invalid value
+
+    def test_error_message_provides_hint(self):
+        """Error message should provide helpful hint about missing value."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "--ai", "--here"])
+
+        assert result.exit_code == 1
+        assert "Hint:" in result.output or "hint" in result.output.lower()
+        assert "forget to provide a value" in result.output.lower()
+
+    def test_error_message_lists_available_agents(self):
+        """Error message should list available agents."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "--ai", "--here"])
+
+        assert result.exit_code == 1
+        # Should mention some known agents
+        output_lower = result.output.lower()
+        assert any(agent in output_lower for agent in ["claude", "copilot", "gemini"])
+
+    def test_ai_commands_dir_consuming_flag(self):
+        """--ai-commands-dir without value should not consume next flag."""
+        from typer.testing import CliRunner
+
+        runner = CliRunner()
+        result = runner.invoke(app, ["init", "myproject", "--ai", "generic", "--ai-commands-dir", "--here"])
+
+        assert result.exit_code == 1
+        assert "Invalid value for --ai-commands-dir" in result.output
+        assert "--here" in result.output