feat: align extension hooks documentation and templates for specify/plan (#1788)

- Update EXTENSION-API-REFERENCE.md to reflect current hook implementation status.
- Add before_tasks and before_implement hooks to EXTENSION-DEVELOPMENT-GUIDE.md.
- Standardize CRITICAL execution instructions for mandatory hooks across all templates (specify, plan, tasks, implement).
- Sync documentation versions and pyproject.toml to 0.2.1 to match upstream.
- Update Last Updated dates in extension guides.

Author: davidniu-0914

extensions/EXTENSION-API-REFERENCE.md

@@ -539,6 +539,12 @@ Examples:
 
 ```yaml
 hooks:
+  before_specify:
+    command: "speckit.research.pre-spec"
+    optional: true
+    prompt: "Perform pre-specification research?"
+    description: "Search context before writing spec"
+
   after_tasks:
     command: "speckit.jira.specstoissues"
     optional: true
@@ -551,17 +557,30 @@ hooks:
 
 Standard events (defined by core):
 
+- `before_specify` - Before specification generation
+- `after_specify` - After specification generation
+- `before_plan` - Before implementation planning
+- `after_plan` - After implementation planning
+- `before_tasks` - Before task generation
 - `after_tasks` - After task generation
+- `before_implement` - Before implementation
 - `after_implement` - After implementation
-- `before_commit` - Before git commit
-- `after_commit` - After git commit
+- `before_commit` - Before git commit (future)
+- `after_commit` - After git commit (future)
 
 ### Hook Configuration
 
 **In `.specify/extensions.yml`**:
 
 ```yaml
 hooks:
+  before_specify:
+    - extension: research
+      command: speckit.research.pre-spec
+      enabled: true
+      optional: true
+      prompt: "Perform pre-specification research?"
+
   after_tasks:
     - extension: jira
       command: speckit.jira.specstoissues
@@ -591,6 +610,8 @@ Or for mandatory hooks:
 **Automatic Hook**: {extension}
 Executing: `/{command}`
 EXECUTE_COMMAND: {command}
+
+**CRITICAL**: You MUST execute the command above immediately after outputting it. Do not end the response until the hook has been triggered.
 ```
 
 ---
@@ -811,6 +832,6 @@ satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0")  # bool
 
 ---
 
-*Last Updated: 2026-01-28*
+*Last Updated: 2026-03-13*
 *API Version: 1.0*
-*Spec Kit Version: 0.1.0*
+*Spec Kit Version: 0.2.1*

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -203,7 +203,7 @@ Available hook points:
 - `before_tasks`: Before `/speckit.tasks` starts
 - `after_tasks`: After `/speckit.tasks` completes
 - `before_implement`: Before `/speckit.implement` starts
-- `after_implement`: After `/speckit.implement` completes (future)
+- `after_implement`: After `/speckit.implement` completes
 
 Hook object:
 
@@ -645,11 +645,25 @@ echo "Using endpoint: $endpoint"
 
 ### Extension with Hooks
 
-Extension that runs automatically:
+Extension that runs automatically at different lifecycle stages:
 
 ```yaml
 # extension.yml
 hooks:
+  # Pre-hook: runs before specification starts
+  before_specify:
+    command: "speckit.research.pre-spec"
+    optional: true
+    prompt: "Perform pre-specification research?"
+    description: "Gather context from codebase before writing spec"
+
+  # Post-hook: runs after planning completes
+  after_plan:
+    command: "speckit.architect.validate"
+    optional: false  # Mandatory execution
+    description: "Validate architecture against project standards"
+
+  # Post-hook: runs after task generation
   after_tasks:
     command: "speckit.auto.analyze"
     optional: false  # Always run

extensions/EXTENSION-USER-GUIDE.md

@@ -40,14 +40,14 @@ Extensions are modular packages that add new commands and functionality to Spec
 
 ### Prerequisites
 
-- Spec Kit version 0.1.0 or higher
+- Spec Kit version 0.2.1 or higher
 - A spec-kit project (directory with `.specify/` folder)
 
 ### Check Your Version
 
 ```bash
 specify version
-# Should show 0.1.0 or higher
+# Should show 0.2.1 or higher
 ```
 
 ### First Extension
@@ -388,28 +388,6 @@ settings:
 
 # Hook configuration
 hooks:
-  before_specify:
-    - extension: contextual-research
-      command: speckit.research.pre-spec
-      enabled: true
-      optional: true
-      prompt: "Perform pre-specification research?"
-  after_specify:
-    - extension: linter
-      command: speckit.linter.check-spec
-      enabled: true
-      optional: false
-  before_plan:
-    - extension: setup-env
-      command: speckit.env.prepare
-      enabled: true
-      optional: false
-  after_plan:
-    - extension: architect
-      command: speckit.architect.validate-plan
-      enabled: true
-      optional: true
-      prompt: "Validate architecture before proceeding?"
   after_tasks:
     - extension: jira
       command: speckit.jira.specstoissues
@@ -988,5 +966,5 @@ After creating tasks, sync to Jira:
 
 ---
 
-*Last Updated: 2026-01-28*
-*Spec Kit Version: 0.1.0*
+*Last Updated: 2026-03-13*
+*Spec Kit Version: 0.2.1*

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

templates/commands/implement.md

@@ -45,6 +45,8 @@ You **MUST** consider the user input before proceeding (if not empty).
     
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+
+    **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not proceed until the hook has been triggered.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -198,4 +200,6 @@ Note: This command assumes a complete task breakdown exists in tasks.md. If task
         Executing: `/{command}`
         EXECUTE_COMMAND: {command}
         ```
+
+        **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not end the response until the hook has been triggered.
     - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

templates/commands/plan.md

@@ -56,6 +56,8 @@ You **MUST** consider the user input before proceeding (if not empty).
     
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+
+    **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not proceed until the hook has been triggered.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -102,6 +104,8 @@ You **MUST** consider the user input before proceeding (if not empty).
        Executing: `/{command}`
        EXECUTE_COMMAND: {command}
        ```
+
+       **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not end the response until the hook has been triggered.
    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Phases

templates/commands/specify.md

@@ -53,6 +53,8 @@ You **MUST** consider the user input before proceeding (if not empty).
     
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+    
+    **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not proceed until the hook has been triggered.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -237,6 +239,8 @@ Given that feature description, do this:
        Executing: `/{command}`
        EXECUTE_COMMAND: {command}
        ```
+
+       **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not end the response until the hook has been triggered.
    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 **NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.

templates/commands/tasks.md

@@ -54,6 +54,8 @@ You **MUST** consider the user input before proceeding (if not empty).
     
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+
+    **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not proceed until the hook has been triggered.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -124,6 +126,8 @@ You **MUST** consider the user input before proceeding (if not empty).
        Executing: `/{command}`
        EXECUTE_COMMAND: {command}
        ```
+
+       **CRITICAL**: You MUST execute the command above immediately after outputting it. Do not end the response until the hook has been triggered.
    - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 Context for task generation: {ARGS}