feat(workflow): standardize worktree-first development flow

.claude/skills/openspec-workflows/SKILL.md

@@ -35,7 +35,7 @@ Turns an implementation plan document into a fully formed OpenSpec change with p
 2. Cross-reference against existing plans and validate targets
 3. Resolve any issues interactively
 4. Create the OpenSpec change via `opsx:ff` skill
-5. Review and improve: enforce TDD-first, add git workflow tasks (branch first, PR last), validate against `openspec/config.yaml`
+5. Review and improve: enforce TDD-first, add git worktree tasks (worktree creation first, PR last, cleanup after merge), validate against `openspec/config.yaml`
 6. Create GitHub issue (public repos only)
 
 ## Validate Change
@@ -62,5 +62,5 @@ Performs dry-run simulation to detect breaking changes, analyze dependencies, an
 - Never modify production code during validation — use temp workspaces
 - Never proceed with ambiguities — ask for clarification
 - Enforce TDD-first ordering in tasks (per config.yaml)
-- Enforce git workflow: branch creation first task, PR creation last task
+- Enforce git worktree workflow: worktree creation first task, PR creation last task, worktree cleanup after merge — never switch the primary checkout away from `dev`
 - Only create GitHub issues in the target repository specified by the plan

.claude/skills/openspec-workflows/references/create-change-from-plan.md

@@ -20,7 +20,7 @@
 - Do not write code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, spec deltas).
 - Always validate alignment against existing plans and implementation reality before proceeding.
 - **CRITICAL**: Only create GitHub issues in the target repository specified by the plan.
-- **CRITICAL Git Workflow**: Add tasks to create a git branch (feature/bugfix/hotfix based on change-id) BEFORE any code modifications, and create a PR to `dev` AFTER all tasks complete. Never work on protected branches (main/dev). Branch naming: `<branch-type>/<change-id>`.
+- **CRITICAL Git Workflow (Worktree Policy)**: Use git worktrees for parallel development — never switch the primary checkout away from `dev`. Add a worktree creation task as the FIRST task, and PR creation as the LAST task. Never work on protected branches (`main`/`dev`) directly. Branch naming: `<branch-type>/<change-id>`. Worktree path: `../specfact-cli-worktrees/<branch-type>/<change-id>`. All subsequent tasks execute inside the worktree directory.
 - **CRITICAL TDD**: Per config.yaml, test tasks MUST come before implementation tasks.
 
 ## Step 1: Plan Selection
@@ -137,20 +137,30 @@ Invoke the `opsx:ff` skill with the change name:
 
 Branch name: `<branch-type>/<change-id>`. Target: `dev`.
 
-#### 5.2.2: Add Git Branch Creation Task (FIRST TASK)
+#### 5.2.2: Add Git Worktree Creation Task (FIRST TASK)
 
 Add as first task in tasks.md:
 
 ```markdown
-## 1. Create git branch from dev
+## 1. Create git worktree for this change
+
+- [ ] 1.1 Fetch latest and create a worktree with a new branch from `origin/dev`.
+  - [ ] 1.1.1 `git fetch origin`
+  - [ ] 1.1.2 `git worktree add ../specfact-cli-worktrees/<branch-type>/<change-id> -b <branch-type>/<change-id> origin/dev`
+  - [ ] 1.1.3 Change into the worktree: `cd ../specfact-cli-worktrees/<branch-type>/<change-id>`
+  - [ ] 1.1.4 Create a virtual environment: `python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"`
+  - [ ] 1.1.5 `git branch --show-current` (verify correct branch)
+```
+
+**If a GitHub issue exists**, use `gh issue develop` to link the branch before creating the worktree:
 
-- [ ] 1.1 Ensure on dev and up to date; create branch `<branch-type>/<change-id>`; verify.
-  - [ ] 1.1.1 `git checkout dev && git pull origin dev`
-  - [ ] 1.1.2 `gh issue develop <issue-number> --repo <target-repo> --name <branch-type>/<change-id> --checkout` (if issue exists)
-  - [ ] 1.1.3 Or: `git checkout -b <branch-type>/<change-id>` (if no issue)
-  - [ ] 1.1.4 `git branch --show-current`
+```markdown
+  - [ ] 1.1.2a `gh issue develop <issue-number> --repo <target-repo> --name <branch-type>/<change-id>` (creates remote branch linked to issue)
+  - [ ] 1.1.2b `git fetch origin && git worktree add ../specfact-cli-worktrees/<branch-type>/<change-id> <branch-type>/<change-id>`
 ```
 
+All remaining tasks in tasks.md MUST run inside the worktree directory, not the primary checkout.
+
 #### 5.2.3: Update Tasks with Quality Standards
 
 For each task, ensure:
@@ -174,8 +184,8 @@ For each task, ensure:
 
 Add as last task in tasks.md. Only create PR if target repo is public (specfact-cli, platform-frontend).
 
-Key steps:
-1. Prepare commit: `git add .`, commit with conventional message, push.
+Key steps (run from inside the worktree directory):
+1. Prepare commit: `git add .`, commit with conventional message, push with `-u`: `git push -u origin <branch-type>/<change-id>`.
 2. Create PR body from `.github/pull_request_template.md`:
    - Use full repo path format for issue refs: `Fixes nold-ai/specfact-cli#<number>`
    - Include OpenSpec change ID in description.
@@ -186,6 +196,21 @@ Key steps:
 
 PR title format: `feat:` for feature/, `fix:` for bugfix/, etc.
 
+#### 5.2.6: Add Worktree Cleanup Task (AFTER MERGE)
+
+Add a note after the PR task for post-merge cleanup:
+
+```markdown
+## Post-merge cleanup (after PR is merged)
+
+- [ ] Return to primary checkout: `cd .../specfact-cli`
+- [ ] `git fetch origin`
+- [ ] `git worktree remove ../specfact-cli-worktrees/<branch-type>/<change-id>`
+- [ ] `git branch -d <branch-type>/<change-id>`
+- [ ] `git worktree prune`
+- [ ] (Optional) `git push origin --delete <branch-type>/<change-id>`
+```
+
 ### 5.3: Update Proposal with Quality Gates
 
 Update proposal.md with: quality standards section, git workflow requirements, acceptance criteria (branch created, tests pass, contracts validated, docs updated, PR created).

.claude/skills/openspec-workflows/references/validate-change.md

@@ -52,9 +52,9 @@
    - Hierarchical numbered sections: `## 1.`, `## 2.`
    - Tasks: `- [ ] 1.1 [Description]`
    - Sub-tasks: `- [ ] 1.1.1 [Description]`
-   - Rules: 2-hour max chunks, contract tasks, test tasks, quality gates, git workflow (branch first, PR last)
+   - Rules: 2-hour max chunks, contract tasks, test tasks, quality gates, git worktree workflow (worktree creation first, PR last, cleanup after merge)
 
-7. **Read tasks.md**: Extract tasks, files to create/modify/delete, task dependencies. Verify branch creation first, PR creation last.
+7. **Read tasks.md**: Extract tasks, files to create/modify/delete, task dependencies. Verify worktree creation first, PR creation last, worktree cleanup after merge.
 
 8. **Read design.md** (if exists): Architectural decisions, interface changes, contracts, migration plans. Verify bridge adapter docs, sequence diagrams for multi-repo.
 

.cursor/commands/wf-create-change-from-plan.md

@@ -24,7 +24,7 @@ Create an OpenSpec change proposal from a plan document (e.g., documentation imp
 - Always validate alignment against existing plans and implementation reality before proceeding.
 - **CRITICAL**: Only create GitHub issues in the target repository specified by the plan. Never create issues in a different repository than the plan's target.
 - For public-facing changes, always sanitize content before creating GitHub issues.
-- **CRITICAL Git Workflow**: Always add tasks to create a git branch (feature/bugfix/hotfix based on change-id) BEFORE any code modifications, and create a Pull Request to `dev` branch AFTER all tasks are complete. Never work directly on protected branches (main/dev). Branch naming: `<branch-type>/<change-id>`.
+- **CRITICAL Git Workflow**: Always add tasks to create a git branch (feature/bugfix/hotfix/chore based on change-id) in a dedicated worktree BEFORE any code modifications, and create a Pull Request to `dev` branch AFTER all tasks are complete. Never work directly on protected branches (main/dev), and avoid implementation work from the primary `specfact-cli` checkout when worktrees are available. Branch naming: `<branch-type>/<change-id>`.
 - **CRITICAL TDD**: Per config.yaml, test tasks MUST come before implementation tasks. Write tests from spec scenarios first; run tests and expect failure; then implement until tests pass.
 
 **Workflow Steps**
@@ -308,6 +308,7 @@ Execute the `/opsx:ff` command to create all artifacts at once:
    - Branch type: `feature`, `bugfix`, `hotfix`, etc.
    - Branch name: `<branch-type>/<change-id>`
    - Target branch: `dev` (default, unless user specifies otherwise)
+   - Worktree path: `../specfact-cli-worktrees/<branch-type>/<change-id>`
 
 **5.2.2: Add Git Branch Creation Task (FIRST TASK)**
 
@@ -317,16 +318,21 @@ Execute the `/opsx:ff` command to create all artifacts at once:
    - Task: "Create git branch `<branch-type>/<change-id>` from `dev` branch"
    - **CRITICAL**: This must be the FIRST task - no code modifications before branch creation
    - **If GitHub issue exists**: Use `gh issue develop` to automatically link branch to issue
-   - **If no GitHub issue**: Use standard `git checkout -b` command
+   - **Use worktree helper**: Prefer `scripts/worktree.sh create <branch-type>/<change-id>`
+   - **If helper is unavailable**: Use `git worktree add` directly (not `git checkout -b` in primary checkout)
    - Steps:
 
-     - [ ] 1.1.1 Ensure we're on dev and up to date: `git checkout dev && git pull origin dev`
-     - [ ] 1.1.2 Create branch with Development link to issue (if exists): `gh issue develop <issue-number> --repo <target-owner>/<target-name> --name <branch-type>/<change-id> --checkout`
-     - [ ] 1.1.3 Or create branch without issue link: `git checkout -b <branch-type>/<change-id>` (if no issue)
-     - [ ] 1.1.4 Verify branch was created: `git branch --show-current`
+     - [ ] 1.1.1 Ensure primary checkout `dev` is up to date: `git checkout dev && git pull origin dev`
+     - [ ] 1.1.2 Create dedicated worktree branch: `scripts/worktree.sh create <branch-type>/<change-id>` (preferred) or `git worktree add ../specfact-cli-worktrees/<branch-type>/<change-id> -b <branch-type>/<change-id> origin/dev`
+     - [ ] 1.1.3 Enter worktree and verify branch: `cd ../specfact-cli-worktrees/<branch-type>/<change-id> && git branch --show-current`
+     - [ ] 1.1.4 Bootstrap worktree environment: `hatch env create`
+     - [ ] 1.1.5 Run pre-flight status checks from worktree root: `hatch run smart-test-status` and `hatch run contract-test-status`
+     - [ ] 1.1.6 If Hatch path permissions fail, set writable overrides (for example `HATCH_DATA_DIR=/tmp/hatch-data`, `HATCH_CACHE_DIR=/tmp/hatch-cache`) and retry pre-flight
+     - [ ] 1.1.7 If issue exists, link branch in GitHub Development section (for example with `gh issue develop` or manual link)
+     - [ ] 1.1.8 Run all implementation commands from the worktree path, not primary `specfact-cli`
 
-   - **Validation**: Verify branch exists and is checked out. If issue exists, verify Development link appears on issue page.
-   - **Rationale**: Prevents accidental commits to protected branches (main/dev) and ensures proper branch isolation. Using `gh issue develop` automatically creates Development link between branch and issue.
+   - **Validation**: Verify branch exists in the worktree path and is checked out there. If issue exists, verify Development link appears on issue page.
+   - **Rationale**: Prevents accidental commits to protected branches (main/dev), ensures branch/path isolation, and avoids mixed changes in the primary checkout.
 
 **5.2.3: Update Existing Tasks with Quality Standards**
 
@@ -536,7 +542,8 @@ Update `proposal.md` to include:
    - Validation requirements
 
 2. **Git workflow requirements:**
-   - Branch creation: Work must be done in feature/bugfix/hotfix branch (not on main/dev)
+   - Branch creation: Work must be done in feature/bugfix/hotfix/chore branch (not on main/dev)
+   - Worktree execution: Run implementation from dedicated worktree path (`../specfact-cli-worktrees/<type>/<change-id>`), not primary checkout
    - Branch protection: `main` and `dev` branches are protected - no direct commits
    - Pull Request: All changes must be merged via PR to `dev` branch
    - Branch naming: `<branch-type>/<change-id>` format
@@ -948,7 +955,7 @@ Validation:
   ✓ Markdown linting passed (auto-fixed where possible)
   ✓ Project rules applied (config.yaml read; TDD-first enforced in tasks.md)
   ✓ Quality standards integrated
-  ✓ Git workflow tasks added (branch creation + PR creation)
+  ✓ Git workflow tasks added (worktree branch creation + PR creation)
   ✓ TDD order section and test-before-code task order applied
 
 GitHub Issue (if target repository supports issues):
@@ -963,7 +970,7 @@ Next Steps:
   3. Verify TDD and git workflow are reflected:
      - tasks.md has "TDD / SDD order (enforced)" section at top
      - For behavior changes: test tasks before implementation tasks
-     - First task: Create branch `<branch-type>/<change-id>`
+     - First task: Create worktree branch `<branch-type>/<change-id>` and switch to worktree path
      - Last task: Create PR to `dev` branch
   4. Apply change when ready: /opsx:apply <change-id> (or /openspec-apply <change-id> for legacy)
 ```

.cursor/commands/wf-validate-change.md

@@ -99,13 +99,15 @@ Perform a dry-run validation of an OpenSpec change proposal to detect breaking c
    - Check task format: Must use `- [ ] 1.1 [Description]` (not `- Task 1:` or `- [ ] Task 1:`)
    - Check sub-task format: Must use `- [ ] 1.1.1 [Description]` (indented, not `- [ ] 1.1.1:` without description)
    - Verify tasks follow config.yaml rules: 2-hour maximum chunks, contract decorator tasks, test tasks, quality gate tasks, git workflow tasks
+   - Verify git workflow tasks are worktree-aware: first task creates `<branch-type>/<change-id>` in dedicated worktree path and subsequent implementation runs from worktree (not primary checkout)
    - If format issues found, note them for reporting
 
 7. **Read `tasks.md`:**
    - Extract: implementation tasks
    - Identify: files to create/modify/delete
    - Note: dependencies between tasks
-   - Verify: Branch creation is first task, PR creation is last task (per config.yaml)
+   - Verify: Worktree branch creation is first task and PR creation is last task (per config.yaml)
+   - Verify: tasks include worktree bootstrap pre-flight before implementation (`hatch env create`, `hatch run smart-test-status`, `hatch run contract-test-status`, with fallback guidance for `HATCH_DATA_DIR` / `HATCH_CACHE_DIR` if needed)
 
 8. **Read `design.md` (if exists):**
    - Extract: architectural decisions, trade-offs
@@ -459,7 +461,7 @@ Impact Assessment: <High/Medium/Low>
        - Contract decorator tasks: <Present/Missing>
        - Test tasks: <Present/Missing>
        - Quality gate tasks: <Present/Missing>
-       - Git workflow tasks: <Present/Missing> (branch creation first, PR creation last)
+       - Git workflow tasks: <Present/Missing> (worktree branch creation first, PR creation last, implementation from worktree path)
        - GitHub issue creation task: <Present/Missing> (if public-facing change per config.yaml)
    - **specs Format**: <Pass/Fail>
      - Given/When/Then format: <Verified/Not verified>

AGENTS.md

@@ -84,6 +84,76 @@ Use `from specfact_cli.common import get_bridge_logger` and avoid `print()` in p
 - `bugfix/your-bugfix-name`
 - `hotfix/your-hotfix-name`
 
+### Git Worktree Policy (Parallel Development)
+
+Use git worktrees for parallel development branches only.
+
+- Allowed branch types in worktrees: `feature/*`, `bugfix/*`, `hotfix/*`, `chore/*`
+- Forbidden in worktrees: `dev`, `main`
+- The primary checkout remains the canonical `dev` workspace
+
+Canonical layout:
+
+- Primary checkout: `.../specfact-cli` (tracks `dev`)
+- Worktrees root: `.../specfact-cli-worktrees/<branch-type>/<branch-slug>`
+- Worktree folder name MUST reflect the branch slug
+
+Preferred helper commands (from repository root):
+
+```bash
+scripts/worktree.sh create feature/<branch-slug>
+scripts/worktree.sh list
+scripts/worktree.sh cleanup feature/<branch-slug>
+```
+
+Create a new worktree from `origin/dev`:
+
+```bash
+git fetch origin
+git worktree add ../specfact-cli-worktrees/feature/<branch-slug> -b feature/<branch-slug> origin/dev
+```
+
+Attach an existing local branch to a worktree:
+
+```bash
+git fetch origin
+git worktree add ../specfact-cli-worktrees/feature/<branch-slug> feature/<branch-slug>
+```
+
+Operational rules:
+
+- Never create a worktree for `dev` or `main`
+- One branch maps to exactly one worktree path at a time
+- Keep branch naming consistent: `<type>/<ticket>-<short-topic>`
+- Keep one active OpenSpec change scope per branch where possible
+- Create a separate virtual environment inside each worktree (for example, `.venv/`)
+- Bootstrap Hatch once per new worktree before running quality gates: `hatch env create`
+- Run quick pre-flight checks from the worktree root: `hatch run smart-test-status` and `hatch run contract-test-status`
+- If Hatch cannot write to default home/cache paths, set writable overrides (for example `HATCH_DATA_DIR=/tmp/hatch-data` and `HATCH_CACHE_DIR=/tmp/hatch-cache`)
+- Run all quality gates from inside the active worktree before commit/PR
+
+Conflict avoidance:
+
+- Check `openspec/CHANGE_ORDER.md` before creating new parallel branches
+- Avoid concurrent branches editing the same `openspec/changes/<change-id>/` directory
+- Rebase frequently on `origin/dev` in each worktree
+- Use `git worktree list` daily to detect stale or incorrect branch/path attachments
+
+Local cleanup after merge to `dev`:
+
+```bash
+git fetch origin
+git worktree remove ../specfact-cli-worktrees/feature/<branch-slug>
+git branch -d feature/<branch-slug>
+git worktree prune
+```
+
+If remote cleanup is needed:
+
+```bash
+git push origin --delete feature/<branch-slug>
+```
+
 ### Pre-Commit Checklist
 
 Run all steps in order before committing. Every step must pass with no errors.

CHANGELOG.md

@@ -9,6 +9,22 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.32.1] - 2026-02-17
+
+### Added
+
+- Git worktree lifecycle helper: `scripts/worktree.sh` with `create`, `list`, `cleanup`, and `help` commands.
+- Worktree helper unit tests: `tests/unit/tools/test_worktree_helper.py` covering protected-branch rejection, branch-type guardrails, deterministic paths, and cleanup behavior.
+- New OpenSpec change package: `workflow-01-git-worktree-management` with proposal, design, spec delta, validation report, and TDD evidence.
+
+### Changed
+
+- Repository instructions now enforce worktree-first development for parallel branches and explicitly block `dev`/`main` worktrees.
+- OpenSpec workflow command docs (`.cursor/commands/wf-create-change-from-plan.md`, `.cursor/commands/wf-validate-change.md`) now require dedicated worktree execution and validate worktree-aware task structure.
+- Active OpenSpec change task files were normalized to worktree-first branch setup commands to reduce direct-work-on-`dev` risk.
+
+---
+
 ## [0.32.0] - 2026-02-16
 
 ### Added