@dezkareid/osddt 1.11.0 → 1.11.1

package/AGENTS.md

@@ -111,7 +111,8 @@ osddt/
 │   │   ├── claude.ts              # Formats COMMAND_DEFINITIONS as Markdown (.claude/commands/osddt.<name>.md)
 │   │   └── gemini.ts              # Formats COMMAND_DEFINITIONS as TOML (.gemini/commands/osddt.<name>.toml)
 │   └── utils/
-│       └── prompt.ts              # Inquirer prompts: askAgents() (checkbox) and askRepoType() (select)
+│       ├── prompt.ts              # Inquirer prompts: askAgents() (checkbox), askRepoType() (select), askWorktreeUrl() (input)
+│       └── worktree.ts            # Shared worktree helpers: git version check, not-a-worktree check, writable check, state file init
 ├── dist/                          # Compiled output (single ESM bundle, gitignored)
 ├── rollup.config.js               # Bundles src/index.ts → dist/index.js (ESM, shebang injected)
 ├── tsconfig.json                  # TypeScript config
@@ -125,7 +126,7 @@ osddt/
 #### Key relationships
 
 - **`shared.ts` is the single source of truth** for all command template content. Both `claude.ts` and `gemini.ts` import `COMMAND_DEFINITIONS` from it and only differ in file format (Markdown vs TOML) and argument placeholder (`$ARGUMENTS` vs `{{args}}`).
-- **`setup.ts`** orchestrates setup: reads `--agents`/`--repo-type` flags when provided (non-interactive), otherwise calls `askAgents()` → `askRepoType()` → writes selected agent files → writes `.osddtrc`.
+- **`setup.ts`** orchestrates setup: reads `--agents`/`--repo-type`/`--worktree-repository` flags when provided (non-interactive), otherwise calls `askAgents()` → `askRepoType()` → `askWorktreeUrl()` → if URL provided, runs worktree environment checks via `worktree.ts` → writes selected agent files → writes `.osddtrc`.
 - **`meta-info.ts`** is referenced inside the generated templates so agents can fetch live branch/date at invocation time (not baked in at build time).
 - **Test files** (`.spec.ts`) live next to the source file they cover. Template tests are pure (no mocks); command tests mock `fs-extra` and `child_process`.
 
@@ -146,28 +147,28 @@ The selected agents are saved in `.osddtrc` alongside `repoType`. When `osddt up
 
 #### Available commands
 
-| Command                                                              | Context       | Description                                                   |
-| -------------------------------------------------------------------- | ------------- | ------------------------------------------------------------- |
-| `osddt setup`                                                        | Local dev     | Generate agent command files for Claude and Gemini            |
-| `osddt setup --agents <list> --repo-type <type>`                     | Local dev     | Non-interactive setup (for CI/scripted environments)          |
-| `npx @dezkareid/osddt setup`                                         | External      | Generate agent command files for Claude and Gemini            |
-| `npx @dezkareid/osddt setup --agents <list> --repo-type <type>`      | External      | Non-interactive setup (for CI/scripted environments)          |
-| `osddt meta-info`                                                    | Local dev     | Output current branch and date as JSON                        |
-| `npx @dezkareid/osddt meta-info`                                     | External      | Output current branch and date as JSON                        |
-| `osddt done <feature-name> --dir <project-path>`                              | Local dev     | Move `working-on/<feature>` to `done/<feature>`               |
-| `npx @dezkareid/osddt done <feature-name> --dir <project-path>`               | External      | Move `working-on/<feature>` to `done/<feature>`               |
-| `osddt done <feature-name> --dir <project-path> --worktree`                   | Local dev     | Archive feature, remove git worktree, and clean state file    |
-| `npx @dezkareid/osddt done <feature-name> --dir <project-path> --worktree`    | External      | Archive feature, remove git worktree, and clean state file    |
-| `osddt update`                                                                | Local dev     | Regenerate agent command files from the existing `.osddtrc`   |
-| `npx @dezkareid/osddt update`                                                 | External      | Regenerate agent command files from the existing `.osddtrc`   |
-| `osddt start-worktree <feature-name>`                                         | Local dev     | Create a git worktree for a feature and scaffold working-on/  |
-| `npx @dezkareid/osddt start-worktree <feature-name>`                          | External      | Create a git worktree for a feature and scaffold working-on/  |
-| `osddt start-worktree <feature-name> --dir <package-path>`                    | Local dev     | Same, specifying the package path in a monorepo               |
-| `npx @dezkareid/osddt start-worktree <feature-name> --dir <package-path>`     | External      | Same, specifying the package path in a monorepo               |
-| `osddt worktree-info <feature-name>`                                          | Local dev     | Look up worktree paths for a feature (JSON output)            |
-| `npx @dezkareid/osddt worktree-info <feature-name>`                           | External      | Look up worktree paths for a feature (JSON output)            |
-| `osddt setup-worktree`                                                        | Local dev     | Validate environment for git worktree usage                   |
-| `npx @dezkareid/osddt setup-worktree`                                         | External      | Validate environment for git worktree usage                   |
+| Command                                                                                        | Context       | Description                                                   |
+| ---------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------- |
+| `osddt setup`                                                                                  | Local dev     | Generate agent command files for Claude and Gemini            |
+| `osddt setup --agents <list> --repo-type <type>`                                               | Local dev     | Non-interactive setup (for CI/scripted environments)          |
+| `osddt setup --worktree-repository <url>`                                                      | Local dev     | Setup with worktree workflow enabled                          |
+| `npx @dezkareid/osddt setup`                                                                   | External      | Generate agent command files for Claude and Gemini            |
+| `npx @dezkareid/osddt setup --agents <list> --repo-type <type>`                                | External      | Non-interactive setup (for CI/scripted environments)          |
+| `npx @dezkareid/osddt setup --worktree-repository <url>`                                       | External      | Setup with worktree workflow enabled                          |
+| `osddt meta-info`                                                                              | Local dev     | Output current branch and date as JSON                        |
+| `npx @dezkareid/osddt meta-info`                                                               | External      | Output current branch and date as JSON                        |
+| `osddt done <feature-name> --dir <project-path>`                                               | Local dev     | Move `working-on/<feature>` to `done/<feature>`               |
+| `npx @dezkareid/osddt done <feature-name> --dir <project-path>`                                | External      | Move `working-on/<feature>` to `done/<feature>`               |
+| `osddt done <feature-name> --dir <project-path> --worktree`                                    | Local dev     | Archive feature, remove git worktree, and clean state file    |
+| `npx @dezkareid/osddt done <feature-name> --dir <project-path> --worktree`                     | External      | Archive feature, remove git worktree, and clean state file    |
+| `osddt update`                                                                                 | Local dev     | Regenerate agent command files from the existing `.osddtrc`   |
+| `npx @dezkareid/osddt update`                                                                  | External      | Regenerate agent command files from the existing `.osddtrc`   |
+| `osddt start-worktree <feature-name>`                                                          | Local dev     | Create a git worktree for a feature and scaffold working-on/  |
+| `npx @dezkareid/osddt start-worktree <feature-name>`                                           | External      | Create a git worktree for a feature and scaffold working-on/  |
+| `osddt start-worktree <feature-name> --dir <package-path>`                                     | Local dev     | Same, specifying the package path in a monorepo               |
+| `npx @dezkareid/osddt start-worktree <feature-name> --dir <package-path>`                      | External      | Same, specifying the package path in a monorepo               |
+| `osddt worktree-info <feature-name>`                                                           | Local dev     | Look up worktree paths for a feature (JSON output)            |
+| `npx @dezkareid/osddt worktree-info <feature-name>`                                            | External      | Look up worktree paths for a feature (JSON output)            |
 
 #### `osddt setup` options
 
@@ -175,27 +176,27 @@ The selected agents are saved in `.osddtrc` alongside `repoType`. When `osddt up
 | ---- | ------ | ----------- |
 | `--agents <list>` | `claude`, `gemini` (comma-separated) | Skip the agents prompt and use the provided value(s) |
 | `--repo-type <type>` | `single`, `monorepo` | Skip the repo type prompt and use the provided value |
+| `--worktree-repository <url>` | any git URL | Enable worktree workflow; saves URL as `"worktree-repository"` in `.osddtrc` |
 | `-d, --dir <directory>` | any path | Target directory (defaults to current working directory) |
 
-Both flags are optional. Providing neither runs the fully interactive mode. Providing both skips all prompts.
+All flags are optional. Providing neither runs the fully interactive mode. When `--worktree-repository` is provided, environment checks run and `.osddt-worktrees` is initialised.
 
 ### Command Templates
 
 Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent's commands directory. Each template corresponds to a step in the spec-driven workflow.
 
-| Template           | Description                                                        |
-| ------------------ | ------------------------------------------------------------------ |
-| `osddt.continue`   | Detect the current workflow phase and prompt the next command      |
-| `osddt.research`   | Research a topic and write a research file to inform the spec      |
-| `osddt.start`           | Start a new feature by creating a branch and working-on folder     |
-| `osddt.start-worktree`  | Start a new feature using a git worktree for parallel development  |
-| `osddt.spec`            | Analyze requirements and write a feature specification             |
-| `osddt.clarify`    | Resolve open questions in the spec and record decisions (optional) |
-| `osddt.plan`       | Create a technical implementation plan from a specification        |
-| `osddt.tasks`      | Generate actionable tasks from an implementation plan              |
-| `osddt.implement`  | Execute tasks from the task list one by one                        |
-| `osddt.fast`       | Bootstrap all planning artifacts (spec, plan, tasks) in one shot   |
-| `osddt.done`       | Resolve project path, verify tasks, and move the feature to done   |
+| Template         | Description                                                                              |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| `osddt.continue` | Detect the current workflow phase and prompt the next command                            |
+| `osddt.research` | Research a topic and write a research file to inform the spec                            |
+| `osddt.start`    | Start a new feature — uses standard or worktree workflow based on `.osddtrc`             |
+| `osddt.spec`     | Analyze requirements and write a feature specification                                   |
+| `osddt.clarify`  | Resolve open questions in the spec and record decisions (optional)                       |
+| `osddt.plan`     | Create a technical implementation plan from a specification                              |
+| `osddt.tasks`    | Generate actionable tasks from an implementation plan                                    |
+| `osddt.implement`| Execute tasks from the task list one by one                                              |
+| `osddt.fast`     | Bootstrap all planning artifacts (spec, plan, tasks) in one shot                         |
+| `osddt.done`     | Resolve project path, verify tasks, and move the feature to done                         |
 
 #### Template Workflow
 
@@ -261,18 +262,16 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 
 ##### Example D — Parallel feature workflow (git worktree)
 
-Use `osddt.start-worktree` to work on multiple features simultaneously. Each feature gets its own isolated directory (a git worktree), so you can keep multiple editor windows open without switching branches.
-
-Before using worktrees for the first time, validate your environment:
+Enable worktree mode once during setup by providing the repository URL:
 
 ```bash
-npx @dezkareid/osddt setup-worktree
+npx @dezkareid/osddt setup --agents claude --repo-type single --worktree-repository https://github.com/org/repo.git
 ```
 
-Then start a feature in its own worktree:
+From that point on, `/osddt.start` automatically uses the worktree workflow:
 
 ```
-/osddt.start-worktree add-payment-gateway
+/osddt.start add-payment-gateway
 /osddt.spec
 /osddt.plan use Stripe SDK, REST endpoints
 /osddt.tasks
@@ -285,7 +284,7 @@ The worktree is created as a sibling of the repo root (e.g. `../my-repo-add-paym
 You can customise the worktree base directory via `worktreeBase` in `.osddtrc`:
 
 ```json
-{ "repoType": "single", "worktreeBase": "/Users/me/worktrees" }
+{ "repoType": "single", "worktree-repository": "https://github.com/org/repo.git", "worktreeBase": "/Users/me/worktrees" }
 ```
 
 ---
@@ -315,13 +314,16 @@ You can customise the worktree base directory via `worktreeBase` in `.osddtrc`:
 
 - **Input**: Either a human-readable feature description (e.g. `"Add user authentication"`) or an existing branch name (e.g. `feat/add-user-auth`).
 - **Branch name resolution**: input is used as-is if it looks like a branch name; otherwise a name is derived (lowercased, hyphens, prefixed with `feat/`), subject to the 30-character feature name limit.
-- **Actions performed by the agent**:
+- **Workflow mode**: determined by reading `.osddtrc`. If `"worktree-repository"` is present, the worktree workflow is used; otherwise the standard branch workflow is used. The user is never prompted to choose.
+- **Standard workflow** (no `"worktree-repository"` in `.osddtrc`):
   1. Checks for an existing branch — offers **Resume** (`git checkout`) or **Abort** if found, otherwise runs `git checkout -b <branch-name>`.
-  2. Reads `.osddtrc` to resolve the project path (single vs monorepo).
-  3. Checks for an existing `working-on/<feature-name>/` folder — offers **Resume** or **Abort** if found, otherwise creates it.
-  4. Reports the branch and working directory, then shows a context-aware next step:
-     - If input was a **human-readable description**: informs the user their description will be used as the starting point for the spec and suggests running `/osddt.spec` (with an optional-context note).
-     - If input was a **branch name** (or no arguments): prompts the user to run `/osddt.spec` with an optional-context note.
+  2. Checks for an existing `working-on/<feature-name>/` folder — offers **Resume** or **Abort** if found, otherwise creates it.
+  3. Reports the branch and working directory.
+- **Worktree workflow** (`"worktree-repository"` present in `.osddtrc`):
+  1. Derives the branch and feature name.
+  2. Runs `npx @dezkareid/osddt start-worktree <feature-name> [--dir <package-path>]`.
+  3. Navigates into the created worktree directory to locate the project root.
+  4. Reports the branch, worktree path, project root, and working directory.
 
 #### osddt.research behaviour
 
@@ -343,17 +345,6 @@ You can customise the worktree base directory via `worktreeBase` in `.osddtrc`:
   4. Records all new answers in a `## Decisions` section of `osddt.spec.md` and removes each answered question from the **Open Questions** section (removing the section heading too if it becomes empty).
   5. Always prompts the user to run (or re-run) `osddt.plan` to reflect the updated decisions.
 
-#### osddt.start-worktree behaviour
-
-- **Input**: Either a human-readable feature description or an existing branch name.
-- **Branch name resolution**: same rules as `osddt.start`.
-- **Actions performed by the agent**:
-  1. Derives the branch and feature name.
-  2. Runs `npx @dezkareid/osddt start-worktree <feature-name> [--dir <package-path>]`.
-  3. The CLI creates the git worktree as a sibling of the repo root (`../<repo-name>-<feature-name>`, overridable via `worktreeBase` in `.osddtrc`), scaffolds `working-on/<feature-name>/` inside the worktree, and writes an entry to `.osddt-worktrees` (sibling to repo root).
-  4. Reports the branch, worktree path, and working directory.
-  5. Next step: `/osddt.spec`.
-
 #### osddt.done behaviour
 
 - **Input**: None — the feature is identified automatically.

package/README.md

@@ -7,6 +7,7 @@ Other spec driven development tool but for monorepo
 | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
 | `@dezkareid/osddt setup`                                                         | Generate agent command files for Claude and Gemini            |
 | `@dezkareid/osddt setup --agents <list> --repo-type <type>`                      | Non-interactive setup (for CI/scripted environments)          |
+| `@dezkareid/osddt setup --worktree-repository <url>`                             | Setup with worktree workflow enabled                          |
 | `@dezkareid/osddt meta-info`                                                     | Output current branch and date as JSON                        |
 | `@dezkareid/osddt done <feature-name> --dir <project-path>`                      | Move `working-on/<feature>` to `done/<feature>`               |
 | `@dezkareid/osddt done <feature-name> --dir <project-path> --worktree`           | Archive feature, remove git worktree, and clean state file    |
@@ -14,7 +15,6 @@ Other spec driven development tool but for monorepo
 | `@dezkareid/osddt start-worktree <feature-name>`                                 | Create a git worktree for a feature and scaffold working-on/  |
 | `@dezkareid/osddt start-worktree <feature-name> --dir <package-path>`            | Same, specifying the package path in a monorepo               |
 | `@dezkareid/osddt worktree-info <feature-name>`                                  | Look up worktree paths for a feature (JSON output)            |
-| `@dezkareid/osddt setup-worktree`                                                | Validate environment for git worktree usage                   |
 
 ### `osddt setup` options
 
@@ -22,11 +22,20 @@ Other spec driven development tool but for monorepo
 | ---- | ------ | ----------- |
 | `--agents <list>` | `claude`, `gemini` (comma-separated) | Skip the agents prompt and use the provided value(s) |
 | `--repo-type <type>` | `single`, `monorepo` | Skip the repo type prompt and use the provided value |
+| `--worktree-repository <url>` | any git URL | Enable worktree workflow and save the repository URL |
 | `-d, --dir <directory>` | any path | Target directory (defaults to current working directory) |
 
-Both flags are optional. Providing neither runs the fully interactive mode. Providing both skips all prompts.
+All flags are optional. Providing neither runs the fully interactive mode. Providing `--agents` and `--repo-type` together skips all standard prompts. Adding `--worktree-repository` also runs environment checks and initialises the worktree state file.
 
-The selected agents are saved in `.osddtrc` alongside `repoType` so that `osddt update` can regenerate the correct files without prompting.
+The selected agents and config are saved in `.osddtrc` so that `osddt update` can regenerate the correct files without prompting.
+
+```json
+// Standard mode
+{ "repoType": "single", "agents": ["claude"] }
+
+// Worktree mode — the "worktree-repository" field enables the worktree workflow
+{ "repoType": "single", "agents": ["claude"], "worktree-repository": "https://github.com/org/repo.git" }
+```
 
 ```bash
 # Interactive (default)
@@ -113,18 +122,16 @@ flowchart LR
 
 #### Parallel feature workflow (git worktree)
 
-Use `osddt.start-worktree` when you want to work on multiple features simultaneously. Each feature gets its own isolated directory so you can keep multiple editor windows open without switching branches.
-
-Before using worktrees for the first time, validate your environment:
+Enable worktree mode by providing the repository URL during setup:
 
 ```bash
-npx @dezkareid/osddt setup-worktree
+npx @dezkareid/osddt setup --agents claude --repo-type single --worktree-repository https://github.com/org/repo.git
 ```
 
-Then start a feature in its own worktree:
+This saves `"worktree-repository"` in `.osddtrc`, runs environment checks, and initialises the `.osddt-worktrees` state file. From that point on, `/osddt.start` automatically uses the worktree workflow:
 
 ```
-/osddt.start-worktree add-payment-gateway
+/osddt.start add-payment-gateway
 /osddt.spec
 /osddt.plan use Stripe SDK, REST endpoints
 /osddt.tasks
@@ -139,12 +146,15 @@ You can customise the worktree base directory by adding `worktreeBase` to `.osdd
 ```json
 {
   "repoType": "single",
+  "worktree-repository": "https://github.com/org/repo.git",
   "worktreeBase": "/Users/me/worktrees"
 }
 ```
 
 Active worktrees are tracked in `.osddt-worktrees` (sibling to the repo root), a JSON array with entries containing `featureName`, `branch`, `worktreePath`, `workingDir`, and `repoRoot`. This file is the single source of truth used by `osddt.continue` and `osddt.done` to resolve the correct paths.
 
+> **Migration note**: If you previously used `osddt setup-worktree` or `/osddt.start-worktree`, those commands have been removed. Re-run `osddt setup --worktree-repository <url>` to configure the new unified workflow. Manually delete any `osddt.start-worktree.*` files from your agent command directories — `osddt update` will not regenerate them.
+
 #### Resuming after closing a session
 
 ```
@@ -157,19 +167,18 @@ Active worktrees are tracked in `.osddt-worktrees` (sibling to the repo root), a
 /osddt.done
 ```
 
-| Template                | Description                                                        |
-| ----------------------- | ------------------------------------------------------------------ |
-| `osddt.continue`        | Detect the current workflow phase and prompt the next command      |
-| `osddt.research`        | Research a topic and write a research file to inform the spec      |
-| `osddt.start`           | Start a new feature by creating a branch and working-on folder     |
-| `osddt.start-worktree`  | Start a new feature using a git worktree for parallel development  |
-| `osddt.spec`            | Analyze requirements and write a feature specification             |
-| `osddt.clarify`         | Resolve open questions in the spec and record decisions (optional) |
-| `osddt.plan`            | Create a technical implementation plan from a specification        |
-| `osddt.tasks`           | Generate actionable tasks from an implementation plan              |
-| `osddt.implement`       | Execute tasks from the task list one by one                        |
-| `osddt.fast`            | Bootstrap all planning artifacts (spec, plan, tasks) in one shot   |
-| `osddt.done`            | Resolve project path, verify tasks, and move the feature to done   |
+| Template         | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `osddt.continue` | Detect the current workflow phase and prompt the next command      |
+| `osddt.research` | Research a topic and write a research file to inform the spec      |
+| `osddt.start`    | Start a new feature — uses standard or worktree workflow based on `.osddtrc` |
+| `osddt.spec`     | Analyze requirements and write a feature specification             |
+| `osddt.clarify`  | Resolve open questions in the spec and record decisions (optional) |
+| `osddt.plan`     | Create a technical implementation plan from a specification        |
+| `osddt.tasks`    | Generate actionable tasks from an implementation plan              |
+| `osddt.implement`| Execute tasks from the task list one by one                        |
+| `osddt.fast`     | Bootstrap all planning artifacts (spec, plan, tasks) in one shot   |
+| `osddt.done`     | Resolve project path, verify tasks, and move the feature to done   |
 
 Generated files are placed in:
 

package/dist/index.js

@@ -5,6 +5,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import select from '@inquirer/select';
 import checkbox from '@inquirer/checkbox';
+import input from '@inquirer/input';
 import { execSync } from 'child_process';
 import readline from 'readline';
 
@@ -19,15 +20,22 @@ ${npxCommand} meta-info
 
 ## Repository Configuration
 
-Before proceeding, read the \`.osddtrc\` file in the root of the repository to determine the project path.
+Before proceeding, read the \`.osddtrc\` file in the root of the repository to determine the project path and workflow mode.
 
 \`\`\`json
-// .osddtrc example
-{ "repoType": "monorepo" | "single" }
+// standard mode
+{ "repoType": "monorepo" | "single", "agents": ["claude"] }
+
+// worktree mode — "worktree-repository" presence determines the workflow
+{ "repoType": "monorepo" | "single", "agents": ["claude"], "worktree-repository": "https://github.com/org/repo.git" }
 \`\`\`
 
 - If \`repoType\` is \`"single"\`: the project path is the repository root.
 - If \`repoType\` is \`"monorepo"\`: ask the user which package to work on (e.g. \`packages/my-package\`), then use \`<repo-root>/<package>\` as the project path.
+- If \`"worktree-repository"\` is **present**: once the feature name is known, run \`${npxCommand} worktree-info <feature-name>\` to resolve the working directory:
+  - exit code **0**: parse the JSON and use the returned \`workingDir\` as the working directory.
+  - exit code **1**: the feature is not yet in a worktree — proceed as standard.
+- If \`"worktree-repository"\` is **absent**: use the standard project path from \`.osddtrc\`.
 
 ## Working Directory
 
@@ -122,15 +130,6 @@ const COMMAND_DEFINITIONS = [
 
 ## Instructions
 
-Before checking the working directory, run the following command to check whether this feature uses a git worktree:
-
-\`\`\`
-${npxCommand} worktree-info <feature-name>
-\`\`\`
-
-- If it exits with code **0**: parse the JSON output and use the returned \`workingDir\` as \`<project-path>/working-on/<feature-name>\`. Skip the main-tree scan below.
-- If it exits with code **1**: the feature is not a worktree feature. Use the standard project path from \`.osddtrc\` and scan the main tree as usual.
-
 Check the working directory \`<project-path>/working-on/<feature-name>\` for the files listed below **in order** to determine the current phase. Use the first matching condition:
 
 | Condition | Current phase | Run next |
@@ -169,7 +168,9 @@ ${FEATURE_NAME_RULES}
 
 Once the feature name is determined:
 
-3. ${WORKING_DIR_STEP}
+3. Resolve the working directory:
+   - If \`"worktree-repository"\` is present in \`.osddtrc\`: run \`${npxCommand} worktree-info <feature-name>\` and use the returned \`workingDir\` if it exits with code 0; otherwise fall through to the standard path.
+   - Otherwise: ${WORKING_DIR_STEP}
 
 4. Research the topic thoroughly:
    - Explore the existing codebase for relevant patterns, conventions, and prior art
@@ -211,61 +212,54 @@ Apply the constraints below to the feature name (the segment after the last \`/\
 
 ${FEATURE_NAME_RULES}
 
-Once the branch name is determined:
-
-3. Check whether the branch already exists locally or remotely:
-   - If it **does not exist**, create and switch to it:
-     \`\`\`
-     git checkout -b <branch-name>
-     \`\`\`
-   - If it **already exists**, warn the user and ask whether to:
-     - **Resume** — switch to the existing branch (\`git checkout <branch-name>\`) and continue
-     - **Abort** — stop and do nothing
-
-4. ${WORKING_DIR_STEP}
+Once the branch name is determined, choose the workflow based on \`.osddtrc\`:
 
-Where \`<feature-name>\` is the last segment of the branch name (after the last \`/\`, or the full branch name if no \`/\` is present).
+---
 
-5. Report the branch name and working directory that were created or resumed.
+### If \`worktree-repository\` is **present** — Worktree workflow
 
-${getCustomContextStep(npxCommand, 'start')}## Arguments
+3. Run the following command to create the git worktree, scaffold the working directory, and register the feature in the state file:
 
-${args}
+\`\`\`
+${npxCommand} start-worktree <feature-name>
+\`\`\`
 
-${getNextStepToSpec(args)}
-`,
-    },
-    {
-        name: 'osddt.start-worktree',
-        description: 'Start a new feature using a git worktree for parallel development',
-        body: ({ args, npxCommand }) => `${getRepoPreamble(npxCommand)}## Instructions
+For monorepos, pass the package path:
 
-The argument provided is: ${args}
+\`\`\`
+${npxCommand} start-worktree <feature-name> --dir <package-path>
+\`\`\`
 
-Determine the branch name using the following logic:
+4. Parse the command output to extract \`worktreePath\` and \`workingDir\`.
 
-1. If ${args} looks like a branch name (e.g. \`feat/my-feature\`, \`fix/some-bug\`, \`my-feature-branch\` — no spaces, kebab-case or slash-separated), use it as-is.
-2. Otherwise treat ${args} as a human-readable feature description, convert it to a feature name, and use the format \`feat/<derived-name>\` as the branch name.
+5. Navigate into the worktree directory to locate the project:
+   - Enter \`<worktreePath>\` — this is the isolated git worktree for this feature.
+   - If \`repoType\` is \`"single"\`: the project root is \`<worktreePath>\`.
+   - If \`repoType\` is \`"monorepo"\`: the project root is \`<worktreePath>/<package-path>\`.
+   - The planning files will live under \`<workingDir>\` (i.e. \`<project-root>/working-on/<feature-name>/\`).
 
-Apply the constraints below to the feature name (the segment after the last \`/\`) before using it:
+6. Report the branch name, worktree path, project root, and working directory.
 
-${FEATURE_NAME_RULES}
+---
 
-Once the branch name is determined:
+### If \`worktree-repository\` is **absent** — Standard workflow
 
-3. Run the following command to create the git worktree, scaffold the working directory, and register the feature in the state file:
+3. Check whether the branch already exists locally or remotely:
+   - If it **does not exist**, create and switch to it:
+     \`\`\`
+     git checkout -b <branch-name>
+     \`\`\`
+   - If it **already exists**, warn the user and ask whether to:
+     - **Resume** — switch to the existing branch (\`git checkout <branch-name>\`) and continue
+     - **Abort** — stop and do nothing
 
-\`\`\`
-${npxCommand} start-worktree <feature-name>
-\`\`\`
+4. ${WORKING_DIR_STEP}
 
-For monorepos, pass the package path:
+Where \`<feature-name>\` is the last segment of the branch name (after the last \`/\`, or the full branch name if no \`/\` is present).
 
-\`\`\`
-${npxCommand} start-worktree <feature-name> --dir <package-path>
-\`\`\`
+5. Report the branch name and working directory that were created or resumed.
 
-4. Report the branch name, worktree path, and working directory shown in the command output.
+---
 
 ${getCustomContextStep(npxCommand, 'start')}## Arguments
 
@@ -485,6 +479,26 @@ ${FEATURE_NAME_RULES}
 
 ### Step 2 — Create branch and working directory
 
+Choose the workflow based on \`.osddtrc\`:
+
+#### If \`worktree-repository\` is **present** — Worktree workflow
+
+3. Run the following command to create the git worktree, scaffold the working directory, and register the feature in the state file:
+
+\`\`\`
+${npxCommand} start-worktree <feature-name>
+\`\`\`
+
+For monorepos, pass the package path:
+
+\`\`\`
+${npxCommand} start-worktree <feature-name> --dir <package-path>
+\`\`\`
+
+4. Parse the command output to extract \`worktreePath\` and \`workingDir\`. Navigate into \`<worktreePath>\` to locate the project root.
+
+#### If \`worktree-repository\` is **absent** — Standard workflow
+
 3. Check whether the branch already exists locally or remotely:
    - If it **does not exist**, create and switch to it:
      \`\`\`
@@ -652,6 +666,12 @@ async function askRepoType() {
         ],
     });
 }
+async function askWorktreeUrl() {
+    return input({
+        message: 'Remote repository URL for worktree workflow (leave blank to skip):',
+        default: '',
+    });
+}
 async function askAgents() {
     return checkbox({
         message: 'Which AI assistant tools do you want to set up?',
@@ -676,6 +696,102 @@ async function askAgents() {
     });
 }
 
+function checkGitVersion() {
+    try {
+        const output = execSync('git --version', { encoding: 'utf-8' }).trim();
+        const match = output.match(/git version (\d+)\.(\d+)/);
+        if (!match) {
+            return { label: 'Git version >= 2.5', passed: false, detail: `Could not parse git version: ${output}` };
+        }
+        const major = parseInt(match[1], 10);
+        const minor = parseInt(match[2], 10);
+        const ok = major > 2 || (major === 2 && minor >= 5);
+        return {
+            label: 'Git version >= 2.5',
+            passed: ok,
+            detail: ok ? output : `Found ${output} — git worktree requires >= 2.5`,
+        };
+    }
+    catch {
+        return { label: 'Git version >= 2.5', passed: false, detail: 'git not found or not executable' };
+    }
+}
+function checkNotAWorktree(cwd) {
+    try {
+        const gitCommonDir = execSync('git rev-parse --git-common-dir', { cwd, encoding: 'utf-8' }).trim();
+        const gitDir = execSync('git rev-parse --git-dir', { cwd, encoding: 'utf-8' }).trim();
+        const isWorktree = gitDir !== gitCommonDir && gitDir !== '.git';
+        return {
+            label: 'Current directory is not a worktree',
+            passed: !isWorktree,
+            detail: isWorktree
+                ? `This directory is itself a worktree (git-dir: ${gitDir}). Run setup from the main repository.`
+                : 'OK',
+        };
+    }
+    catch {
+        return { label: 'Current directory is not a worktree', passed: false, detail: 'Not inside a git repository' };
+    }
+}
+async function checkTargetWritable(cwd) {
+    let targetBase;
+    try {
+        const repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim();
+        const rcPath = path.join(repoRoot, '.osddtrc');
+        if (await fs.pathExists(rcPath)) {
+            const rc = await fs.readJson(rcPath);
+            targetBase = rc.worktreeBase ?? path.dirname(repoRoot);
+        }
+        else {
+            targetBase = path.dirname(repoRoot);
+        }
+    }
+    catch {
+        return { label: 'Worktree target directory is writable', passed: false, detail: 'Could not resolve repo root' };
+    }
+    try {
+        await fs.access(targetBase, fs.constants.W_OK);
+        return { label: 'Worktree target directory is writable', passed: true, detail: `${targetBase} is writable` };
+    }
+    catch {
+        return { label: 'Worktree target directory is writable', passed: false, detail: `${targetBase} is not writable` };
+    }
+}
+async function initStateFile(cwd) {
+    try {
+        const repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim();
+        const stateFile = path.join(path.dirname(repoRoot), '.osddt-worktrees');
+        if (!(await fs.pathExists(stateFile))) {
+            await fs.writeJson(stateFile, [], { spaces: 2 });
+            console.log(`  ✓ Initialized worktree state file: ${stateFile}`);
+        }
+        else {
+            console.log(`  ✓ Worktree state file already exists: ${stateFile}`);
+        }
+    }
+    catch {
+        console.log('  ✗ Could not initialize worktree state file');
+    }
+}
+function printCheckResult(result) {
+    const icon = result.passed ? '✓' : '✗';
+    console.log(`  ${icon} ${result.label}`);
+    if (!result.passed) {
+        console.log(`    → ${result.detail}`);
+    }
+}
+async function runWorktreeChecks(cwd) {
+    const results = [
+        checkGitVersion(),
+        checkNotAWorktree(cwd),
+        await checkTargetWritable(cwd),
+    ];
+    for (const result of results) {
+        printCheckResult(result);
+    }
+    return results.every(r => r.passed);
+}
+
 const CANONICAL_PACKAGE_NAME = '@dezkareid/osddt';
 const NPX_COMMAND = 'npx osddt';
 const NPX_COMMAND_FALLBACK = `npx ${CANONICAL_PACKAGE_NAME}`;
@@ -723,15 +839,7 @@ async function writeConfig(cwd, config) {
     await fs.writeJson(configPath, config, { spaces: 2 });
     console.log(`\nSaved config: ${configPath}`);
 }
-async function runSetup(cwd, rawAgents, rawRepoType) {
-    const agents = rawAgents !== undefined ? parseAgents(rawAgents) : await askAgents();
-    if (rawAgents === undefined)
-        console.log('');
-    const repoType = rawRepoType !== undefined ? parseRepoType(rawRepoType) : await askRepoType();
-    if (rawRepoType === undefined)
-        console.log('');
-    const npxCommand = await resolveNpxCommand(cwd);
-    console.log('Setting up OSDDT command files...\n');
+async function writeAgentFiles(cwd, agents, npxCommand) {
     if (agents.includes('claude')) {
         const claudeFiles = getClaudeTemplates(cwd, npxCommand);
         console.log('Claude Code commands (.claude/commands/):');
@@ -748,7 +856,38 @@ async function runSetup(cwd, rawAgents, rawRepoType) {
         }
         console.log('');
     }
-    await writeConfig(cwd, { repoType, agents });
+}
+async function setupWorktreeEnvironment(cwd, _worktreeRepository) {
+    console.log('Checking environment for git worktree support...\n');
+    const allPassed = await runWorktreeChecks(cwd);
+    console.log('');
+    if (!allPassed) {
+        console.log('Some checks failed. Resolve the issues above before using the worktree workflow.');
+        process.exit(1);
+    }
+    await initStateFile(cwd);
+    console.log('');
+}
+async function runSetup(cwd, rawAgents, rawRepoType, rawWorktreeRepository) {
+    const agents = rawAgents !== undefined ? parseAgents(rawAgents) : await askAgents();
+    if (rawAgents === undefined)
+        console.log('');
+    const repoType = rawRepoType !== undefined ? parseRepoType(rawRepoType) : await askRepoType();
+    if (rawRepoType === undefined)
+        console.log('');
+    const worktreeRepository = rawWorktreeRepository !== undefined ? rawWorktreeRepository : (await askWorktreeUrl()) || undefined;
+    if (rawWorktreeRepository === undefined)
+        console.log('');
+    if (worktreeRepository) {
+        await setupWorktreeEnvironment(cwd);
+    }
+    const npxCommand = await resolveNpxCommand(cwd);
+    console.log('Setting up OSDDT command files...\n');
+    await writeAgentFiles(cwd, agents, npxCommand);
+    const config = { repoType, agents };
+    if (worktreeRepository)
+        config['worktree-repository'] = worktreeRepository;
+    await writeConfig(cwd, config);
     console.log('\nSetup complete!');
     console.log('Commands created: osddt.spec, osddt.plan, osddt.tasks, osddt.implement');
 }
@@ -759,9 +898,10 @@ function setupCommand() {
         .option('-d, --dir <directory>', 'target directory', process.cwd())
         .option('--agents <list>', 'comma-separated agents to set up (claude, gemini)')
         .option('--repo-type <type>', 'repository type (single, monorepo)')
+        .option('--worktree-repository <url>', 'remote repository URL to enable worktree workflow')
         .action(async (options) => {
         const targetDir = path.resolve(options.dir);
-        await runSetup(targetDir, options.agents, options.repoType);
+        await runSetup(targetDir, options.agents, options.repoType, options.worktreeRepository);
     });
     return cmd;
 }
@@ -1148,106 +1288,6 @@ function worktreeInfoCommand() {
     return cmd;
 }
 
-function checkGitVersion() {
-    try {
-        const output = execSync('git --version', { encoding: 'utf-8' }).trim();
-        // e.g. "git version 2.39.3"
-        const match = output.match(/git version (\d+)\.(\d+)/);
-        if (!match) {
-            return { label: 'Git version >= 2.5', passed: false, detail: `Could not parse git version: ${output}` };
-        }
-        const major = parseInt(match[1], 10);
-        const minor = parseInt(match[2], 10);
-        const ok = major > 2 || (major === 2 && minor >= 5);
-        return {
-            label: 'Git version >= 2.5',
-            passed: ok,
-            detail: ok ? output : `Found ${output} — git worktree requires >= 2.5`,
-        };
-    }
-    catch {
-        return { label: 'Git version >= 2.5', passed: false, detail: 'git not found or not executable' };
-    }
-}
-function checkNotAWorktree(cwd) {
-    try {
-        const gitCommonDir = execSync('git rev-parse --git-common-dir', { cwd, encoding: 'utf-8' }).trim();
-        const gitDir = execSync('git rev-parse --git-dir', { cwd, encoding: 'utf-8' }).trim();
-        const isWorktree = gitDir !== gitCommonDir && gitDir !== '.git';
-        return {
-            label: 'Current directory is not a worktree',
-            passed: !isWorktree,
-            detail: isWorktree
-                ? `This directory is itself a worktree (git-dir: ${gitDir}). Run setup-worktree from the main repository.`
-                : 'OK',
-        };
-    }
-    catch {
-        return { label: 'Current directory is not a worktree', passed: false, detail: 'Not inside a git repository' };
-    }
-}
-async function checkTargetWritable(cwd) {
-    let targetBase;
-    try {
-        const repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim();
-        const rcPath = path.join(repoRoot, '.osddtrc');
-        if (await fs.pathExists(rcPath)) {
-            const rc = await fs.readJson(rcPath);
-            targetBase = rc.worktreeBase ?? path.dirname(repoRoot);
-        }
-        else {
-            targetBase = path.dirname(repoRoot);
-        }
-    }
-    catch {
-        return { label: 'Worktree target directory is writable', passed: false, detail: 'Could not resolve repo root' };
-    }
-    try {
-        await fs.access(targetBase, fs.constants.W_OK);
-        return { label: 'Worktree target directory is writable', passed: true, detail: `${targetBase} is writable` };
-    }
-    catch {
-        return { label: 'Worktree target directory is writable', passed: false, detail: `${targetBase} is not writable` };
-    }
-}
-function printResult(result) {
-    const icon = result.passed ? '✓' : '✗';
-    console.log(`  ${icon} ${result.label}`);
-    if (!result.passed) {
-        console.log(`    → ${result.detail}`);
-    }
-}
-async function runSetupWorktree(cwd) {
-    console.log('Checking environment for git worktree support...\n');
-    const results = [
-        checkGitVersion(),
-        checkNotAWorktree(cwd),
-        await checkTargetWritable(cwd),
-    ];
-    for (const result of results) {
-        printResult(result);
-    }
-    const allPassed = results.every(r => r.passed);
-    console.log('');
-    if (allPassed) {
-        console.log('All checks passed. You can use the worktree workflow.');
-    }
-    else {
-        console.log('Some checks failed. Resolve the issues above before using the worktree workflow.');
-        process.exit(1);
-    }
-}
-function setupWorktreeCommand() {
-    const cmd = new Command('setup-worktree');
-    cmd
-        .description('Validate the environment for git worktree usage')
-        .option('-d, --dir <directory>', 'directory to check', process.cwd())
-        .action(async (options) => {
-        await runSetupWorktree(path.resolve(options.dir));
-    });
-    return cmd;
-}
-
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);
 const pkgPath = path.join(__dirname$1, '..', 'package.json');
@@ -1264,5 +1304,4 @@ program.addCommand(updateCommand());
 program.addCommand(contextCommand());
 program.addCommand(startWorktreeCommand());
 program.addCommand(worktreeInfoCommand());
-program.addCommand(setupWorktreeCommand());
 program.parse(process.argv);

package/dist/utils/prompt.d.ts

@@ -1,4 +1,5 @@
 export type RepoType = 'monorepo' | 'single';
 export type AgentType = 'claude' | 'gemini';
 export declare function askRepoType(): Promise<RepoType>;
+export declare function askWorktreeUrl(): Promise<string>;
 export declare function askAgents(): Promise<AgentType[]>;

package/dist/utils/worktree.d.ts

@@ -0,0 +1,11 @@
+export interface CheckResult {
+    label: string;
+    passed: boolean;
+    detail: string;
+}
+export declare function checkGitVersion(): CheckResult;
+export declare function checkNotAWorktree(cwd: string): CheckResult;
+export declare function checkTargetWritable(cwd: string): Promise<CheckResult>;
+export declare function initStateFile(cwd: string): Promise<void>;
+export declare function printCheckResult(result: CheckResult): void;
+export declare function runWorktreeChecks(cwd: string): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/osddt",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "description": "Package for Spec-Driven Development workflow",
   "keywords": [
     "spec-driven",
@@ -34,6 +34,7 @@
   "main": "./dist/index.js",
   "dependencies": {
     "@inquirer/checkbox": "5.0.7",
+    "@inquirer/input": "5.0.7",
     "@inquirer/select": "5.0.7",
     "commander": "12.0.0",
     "fs-extra": "11.2.0",

package/dist/commands/setup-worktree.d.ts

@@ -1,2 +0,0 @@
-import { Command } from 'commander';
-export declare function setupWorktreeCommand(): Command;