[codex] add worktree-first specify command

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+### Added
+- `/speckit.worktrees.specify` command for a worktree-first specify workflow: create or reuse the feature worktree before writing spec artifacts, then continue the normal Spec Kit flow from the worktree root
+
+### Changed
+- README now documents the recommended response to "pre-hook for specify": use an explicit worktree-first command unless Spec Kit itself can also switch the active project root for the rest of `/speckit.specify`
+
 ## 1.3.2 (2026-04-15)
 
 ### Added

README.md

@@ -126,10 +126,31 @@ dotworktrees_dir: ".worktrees"
 
 | Command | Description | Modifies files? |
 |---------|-------------|-----------------|
+| `/speckit.worktrees.specify` | Worktree-first specify flow: create/reuse a worktree, then write the spec inside it | Yes |
 | `/speckit.worktrees.create` | Spawn a worktree for a feature branch | Yes |
 | `/speckit.worktrees.list` | Dashboard: status, artifacts, tasks | No |
 | `/speckit.worktrees.clean` | Remove merged/stale worktrees | Yes |
 
+## Worktree-first specify workflow
+
+If you want the spec itself isolated from the start, use `/speckit.worktrees.specify` instead of `/speckit.specify` from the primary checkout:
+
+```text
+/speckit.worktrees.specify 005-user-auth Build sign-in with email and passkeys
+```
+
+That command creates or reuses the feature worktree first, then treats the returned worktree path as the project root for the normal specify flow. The spec should be written under `<worktree>/specs/<branch>/`, and all follow-up `/speckit.plan`, `/speckit.tasks`, implementation, commit, push, and PR work should run from that worktree.
+
+This is the recommended answer to the "pre-hook for specify" workflow: creating the worktree as an explicit command is predictable because it can pin the branch and path before any spec artifacts are written. A `before_specify` hook alone is not enough unless the surrounding product also changes the active project root for the rest of the specify command.
+
+For VS Code, the most reliable variant remains one window per active worktree:
+
+1. Run `/speckit.worktrees.specify <branch> <feature description>` from the primary checkout.
+2. Open the returned worktree path in a new VS Code window.
+3. Continue `/speckit.plan` and later steps in that worktree window.
+4. Commit, push, and open the PR from the worktree.
+5. Close the worktree window and run `/speckit.worktrees.clean` from the primary checkout when done.
+
 ## Hook
 
 **`after_specify`** — automatically creates a worktree after a new feature is specified. Controlled by the `auto_create` config value.

commands/speckit.worktrees.specify.md

@@ -0,0 +1,87 @@
+---
+description: "Create a git worktree first, then write the feature spec inside that isolated checkout"
+---
+
+# Worktree-First Specify
+
+Create an isolated git worktree before writing the feature specification. Use this command when several features or agents may run in parallel and you want the spec files, plan, tasks, commits, and terminal cwd to all belong to the same worktree from the start.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding. The user input should include:
+- A feature branch name or slug (for example `005-user-auth`)
+- The feature description to specify
+- Optional worktree flags accepted by `/speckit.worktrees.create`, such as `--layout sibling`, `--path <dir>`, or `--base-ref HEAD`
+
+If the branch name is missing, ask for it before creating anything. If the feature description is missing, create the worktree only after the user confirms they want to continue specifying in that worktree.
+
+## Prerequisites
+
+1. Verify the current directory is the primary git repository (`git rev-parse --show-toplevel`)
+2. Verify the working tree has the intended base state for the new feature
+3. Verify `git worktree` is available (`git worktree list` succeeds)
+
+## Outline
+
+1. **Parse the request**:
+   - Extract the target branch name
+   - Extract any worktree flags
+   - Preserve the remaining text as the feature description
+
+2. **Create the worktree first**:
+   Run the deterministic worktree script:
+
+   ```bash
+   bash "$(dirname "$0")/../scripts/bash/create-worktree.sh" \
+     --json \
+     [--layout sibling|nested] \
+     [--base-ref HEAD|main|origin/main|...] \
+     [--path <override>] \
+     "$BRANCH_NAME"
+   ```
+
+   If the worktree already exists for that branch, use the existing path and continue there.
+
+3. **Switch all follow-up work to the worktree**:
+   - Treat the returned worktree path as the project root for this feature
+   - Run all file reads, writes, scripts, git commands, and follow-up Spec Kit steps from that path
+   - If using an IDE, open the returned path as its own window before continuing
+
+4. **Write the spec inside the worktree**:
+   Continue the normal `/speckit.specify` workflow from the worktree root using the feature description. Spec artifacts should be created under:
+
+   ```text
+   <worktree>/specs/<branch>/
+   ```
+
+   Do not write spec artifacts to the primary checkout.
+
+5. **Report**:
+   Output a concise summary:
+
+   ```markdown
+   ## Worktree-First Spec Ready
+
+   | Field | Value |
+   |-------|-------|
+   | **Branch** | 005-user-auth |
+   | **Worktree path** | /Users/me/code/my-project/.worktrees/005-user-auth |
+   | **Spec root** | /Users/me/code/my-project/.worktrees/005-user-auth/specs/005-user-auth |
+
+   **Next steps:**
+   - Continue `/speckit.plan` from the worktree root
+   - Keep commits and PR work inside that worktree
+   - Return to the primary checkout only for `/speckit.worktrees.clean`
+   ```
+
+## Rules
+
+- Create or reuse the worktree before writing any spec files
+- Never run `git checkout` in the primary checkout as part of this workflow
+- Prefer `--base-ref HEAD` when the primary checkout has committed spec seed work that the new worktree must include
+- Keep all generated artifacts, plans, tasks, implementation changes, commits, and PR operations in the worktree
+- Use `/speckit.worktrees.clean` from the primary checkout after the PR is merged or the worktree is no longer needed

extension.yml

@@ -22,6 +22,9 @@ requires:
 
 provides:
   commands:
+    - name: speckit.worktrees.specify
+      file: commands/speckit.worktrees.specify.md
+      description: "Create a worktree before writing the feature spec"
     - name: speckit.worktrees.create
       file: commands/speckit.worktrees.create.md
       description: "Spawn an isolated git worktree for a feature branch"