Merge pull request #94 from paullen/patch-1

Update README.md

.github/workflows/release.yml

@@ -11,12 +11,14 @@ jobs:
     
     permissions:
       contents: write
+      pull-requests: write
       
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
+        token: ${{ secrets.GITHUB_TOKEN }}
         
     - name: Get latest tag
       id: get_tag
@@ -204,7 +206,7 @@ jobs:
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         
-    - name: Update version in pyproject.toml
+    - name: Update version in pyproject.toml (for release artifacts only)
       if: steps.check_release.outputs.exists == 'false'
       run: |
         # Update version in pyproject.toml (remove 'v' prefix for Python versioning)
@@ -213,19 +215,8 @@ jobs:
         
         if [ -f "pyproject.toml" ]; then
           sed -i "s/version = \".*\"/version = \"$PYTHON_VERSION\"/" pyproject.toml
-          echo "Updated pyproject.toml version to $PYTHON_VERSION"
+          echo "Updated pyproject.toml version to $PYTHON_VERSION (for release artifacts only)"
         fi
         
-    - name: Commit version update
-      if: steps.check_release.outputs.exists == 'false'
-      run: |
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action"
-        
-        if git diff --quiet; then
-          echo "No changes to commit"
-        else
-          git add pyproject.toml
-          git commit -m "chore: bump version to ${{ steps.get_tag.outputs.new_version }}"
-          git push
-        fi
+    # Note: No longer committing version changes back to main branch
+    # The version is only updated in the release artifacts

README.md

@@ -2,14 +2,14 @@
     <img src="./media/logo_small.webp"/>
     <h1>🌱 Spec Kit</h1>
     <h3><em>Build high-quality software faster.</em></h3>
-    
-    [![Release](https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg)](https://github.com/github/spec-kit/actions/workflows/release.yml)
 </div>
 
 <p align="center">
     <strong>An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.</strong>
 </p>
 
+[![Release](https://github.com/github/spec-kit/actions/workflows/release.yml/badge.svg)](https://github.com/github/spec-kit/actions/workflows/release.yml)
+
 ---
 
 ## Table of Contents
@@ -21,8 +21,12 @@
 - [🎯 Experimental goals](#-experimental-goals)
 - [🔧 Prerequisites](#-prerequisites)
 - [📖 Learn more](#-learn-more)
-- [Detailed process](#detailed-process)
-- [Troubleshooting](#troubleshooting)
+- [📋 Detailed process](#-detailed-process)
+- [🔍 Troubleshooting](#-troubleshooting)
+- [👥 Maintainers](#-maintainers)
+- [💬 Support](#-support)
+- [🙏 Acknowledgements](#-acknowledgements)
+- [📄 License](#-license)
 
 ## 🤔 What is Spec-Driven Development?
 
@@ -43,7 +47,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 Use the `/specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
 
 ```bash
-/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 never other nested albums. Within each album, photos are previewed in a tile-like interface.
+/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.
 ```
 
 ### 3. Create a technical implementation plan
@@ -118,7 +122,7 @@ Our research and experimentation focus on:
 
 ---
 
-## Detailed process
+## 📋 Detailed process
 
 <details>
 <summary>Click to expand the detailed step-by-step walkthrough</summary>
@@ -207,7 +211,7 @@ At this stage, your project folder contents should resemble the following:
 │	 ├── setup-plan.sh
 │	 └── update-claude-md.sh
 ├── specs
-│	 └── 002-create-taskify
+│	 └── 001-create-taskify
 │	     └── spec.md
 └── templates
     ├── CLAUDE-template.md
@@ -260,7 +264,7 @@ The output of this step will include a number of implementation detail documents
 │	 ├── setup-plan.sh
 │	 └── update-claude-md.sh
 ├── specs
-│	 └── 002-create-taskify
+│	 └── 001-create-taskify
 │	     ├── contracts
 │	     │	 ├── api-spec.json
 │	     │	 └── signalr-spec.md
@@ -341,14 +345,14 @@ Once the implementation step is done, ask Claude Code to try to run the applicat
 
 ---
 
-## Troubleshooting
+## 🔍 Troubleshooting
 
 ### Git Credential Manager on Linux
 
 If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
 
 ```bash
-#!/bin/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
@@ -360,19 +364,19 @@ echo "Cleaning up..."
 rm gcm-linux_amd64.2.6.1.deb
 ```
 
-## Maintainers
+## 👥 Maintainers
 
 - Den Delimarsky ([@localden](https://github.com/localden))
 - John Lam ([@jflam](https://github.com/jflam))
 
-## Support
+## 💬 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
+## 🙏 Acknowledgements
 
 This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam).
 
-## License
+## 📄 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.

scripts/check-task-prerequisites.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Check that implementation plan exists and find optional design documents
 # Usage: ./check-task-prerequisites.sh [--json]
 

scripts/common.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Common functions and variables for all scripts
 
 # Get repository root

scripts/create-new-feature.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Create a new feature with branch, directory structure, and template
 # Usage: ./create-new-feature.sh "feature description"
 #        ./create-new-feature.sh --json "feature description"

scripts/get-feature-paths.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Get paths for current feature branch without creating anything
 # Used by commands that need to find existing feature files
 

scripts/setup-plan.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Setup implementation plan structure for current branch
 # Returns paths needed for implementation plan generation
 # Usage: ./setup-plan.sh [--json]

scripts/update-agent-context.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Incrementally update agent context files based on new feature plan
 # Supports: CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md
 # O(1) operation - only reads current context file and new plan.md

spec-driven.md

@@ -2,7 +2,7 @@
 
 ## The Power Inversion
 
-For decades, code has been king. Specifications served code—they were the scaffolding we built and then discarded once the "real work" of coding began. We wrote PRDs to guide development, created design docs to inform implementation, drew diagrams to visualize architecture. But these were always subordinate to the code itself. Code was truth. Everything else was, at best, good intentions. Code was the source of truth, as it mvoed forward, and spec's rarely kept pace. As the asset (code) and the implementation are one, it's not easy to have a parallel implementation without trying to build from the code.
+For decades, code has been king. Specifications served code—they were the scaffolding we built and then discarded once the "real work" of coding began. We wrote PRDs to guide development, created design docs to inform implementation, drew diagrams to visualize architecture. But these were always subordinate to the code itself. Code was truth. Everything else was, at best, good intentions. Code was the source of truth, as it moved forward, and spec's rarely kept pace. As the asset (code) and the implementation are one, it's not easy to have a parallel implementation without trying to build from the code.
 
 Spec-Driven Development (SDD) inverts this power structure. Specifications don't serve code—code serves specifications. The (Product Requirements Document-Specification) PRD isn't a guide for implementation; it's the source that generates implementation. Technical plans aren't documents that inform coding; they're precise definitions that produce code. This isn't an incremental improvement to how we build software. It's a fundamental rethinking of what drives development.
 
@@ -34,13 +34,13 @@ The feedback loop extends beyond initial development. Production metrics and inc
 
 Three trends make SDD not just possible but necessary:
 
-First, AI capabilities have reached a threshold where natural language specifications can reliably generate working code. This isn't about replacing developers—it's about amplifying their effectiveness by automating the mechanical translation from specification to implementation. It can amplify exploration and creativity, it can support "start-over" easily, it supports addition substraction and critical thinking.
+First, AI capabilities have reached a threshold where natural language specifications can reliably generate working code. This isn't about replacing developers—it's about amplifying their effectiveness by automating the mechanical translation from specification to implementation. It can amplify exploration and creativity, it can support "start-over" easily, it supports addition subtraction and critical thinking.
 
-Second, software complexity continues to grow exponentially. Modern systems integrate dozens of services, frameworks, and dependencies. Keeping all these pieces aligned with original intent through manual processes becomes increasingly difficult. SDD provides systematic alignment through specification-driven generation. Frameworks may eviolve to provide AI-first support, not human-first support, or architect around reusable components. 
+Second, software complexity continues to grow exponentially. Modern systems integrate dozens of services, frameworks, and dependencies. Keeping all these pieces aligned with original intent through manual processes becomes increasingly difficult. SDD provides systematic alignment through specification-driven generation. Frameworks may evolve to provide AI-first support, not human-first support, or architect around reusable components.
 
 Third, the pace of change accelerates. Requirements change far more rapidly today than ever before. Pivoting is no longer exceptional—it's expected. Modern product development demands rapid iteration based on user feedback, market conditions, and competitive pressures. Traditional development treats these changes as disruptions. Each pivot requires manually propagating changes through documentation, design, and code. The result is either slow, careful updates that limit velocity, or fast, reckless changes that accumulate technical debt.
 
-SDD can support what-if/simulation experiments, "If we need to re-implement of change the application to promote a business need to sell more T-shirts, how would we implement and experiment for that?". 
+SDD can support what-if/simulation experiments, "If we need to re-implement or change the application to promote a business need to sell more T-shirts, how would we implement and experiment for that?".
 
 SDD transforms requirement changes from obstacles into normal workflow. When specifications drive implementation, pivots become systematic regenerations rather than manual rewrites. Change a core requirement in the PRD, and affected implementation plans update automatically. Modify a user story, and corresponding API endpoints regenerate. This isn't just about initial development—it's about maintaining engineering velocity through inevitable changes.
 
@@ -256,7 +256,7 @@ The constitution defines nine articles that shape every aspect of the developmen
 #### Article I: Library-First Principle
 Every feature must begin as a standalone library—no exceptions. This forces modular design from the start:
 ```
-Every feature in Specify2 MUST begin its existence as a standalone library. 
+Every feature in Specify MUST begin its existence as a standalone library. 
 No feature shall be implemented directly within application code without 
 first being abstracted into a reusable library component.
 ```

src/specify_cli/__init__.py

@@ -15,7 +15,7 @@ Specify CLI - Setup tool for Specify projects
 Usage:
     uvx specify-cli.py init <project-name>
     uvx specify-cli.py init --here
-    
+
 Or install globally:
     uv tool install --from specify-cli.py specify-cli
     specify init <project-name>
@@ -813,12 +813,12 @@ def init(
     if selected_ai == "claude":
         steps_lines.append(f"{step_num}. Open in Visual Studio Code and start using / commands with Claude Code")
         steps_lines.append("   - Type / in any file to see available commands")
-        steps_lines.append("   - Use /spec to create specifications")
+        steps_lines.append("   - Use /specify to create specifications")
         steps_lines.append("   - Use /plan to create implementation plans")
         steps_lines.append("   - Use /tasks to generate tasks")
     elif selected_ai == "gemini":
         steps_lines.append(f"{step_num}. Use / commands with Gemini CLI")
-        steps_lines.append("   - Run gemini /spec to create specifications")
+        steps_lines.append("   - Run gemini /specify to create specifications")
         steps_lines.append("   - Run gemini /plan to create implementation plans")
         steps_lines.append("   - See GEMINI.md for all available commands")
     elif selected_ai == "copilot":
@@ -868,4 +868,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

templates/commands/plan.md

@@ -19,7 +19,7 @@ Given the implementation details provided as an argument, do this:
 3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.
 
 4. Execute the implementation plan template:
-   - Load `/templates/implementation-plan-template.md` (already copied to IMPL_PLAN path)
+   - Load `/templates/plan-template.md` (already copied to IMPL_PLAN path)
    - Set Input path to FEATURE_SPEC
    - Run the Execution Flow (main) function steps 1-10
    - The template is self-contained and executable

templates/commands/tasks.md

@@ -13,10 +13,10 @@ Given the context provided as an argument, do this:
 2. Load and analyze available design documents:
    - Always read plan.md for tech stack and libraries
    - IF EXISTS: Read data-model.md for entities
-   - IF EXISTS: Read contracts/ for API endpoints  
+   - IF EXISTS: Read contracts/ for API endpoints
    - IF EXISTS: Read research.md for technical decisions
    - IF EXISTS: Read quickstart.md for test scenarios
-   
+
    Note: Not all projects have all documents. For example:
    - CLI tools might not have contracts/
    - Simple libraries might not need data-model.md