@dezkareid/osddt 1.10.0 → 1.11.0

package/AGENTS.md

@@ -82,7 +82,6 @@ Always prefer use exact versions for dependencies. Do not use `^` or `~`.
 
 #### Linting & Formatting
 - **ESLint**: `9.39.2`
-- **Prettier**: `3.8.1`
 
 #### Type Definitions
 - **@types/node**: `25.0.10`
@@ -155,10 +154,20 @@ The selected agents are saved in `.osddtrc` alongside `repoType`. When `osddt up
 | `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 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 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                   |
 
 #### `osddt setup` options
 
@@ -178,8 +187,9 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 | ------------------ | ------------------------------------------------------------------ |
 | `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.spec`       | Analyze requirements and write a feature specification             |
+| `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              |
@@ -249,6 +259,35 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 /osddt.done
 ```
 
+##### 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:
+
+```bash
+npx @dezkareid/osddt setup-worktree
+```
+
+Then start a feature in its own worktree:
+
+```
+/osddt.start-worktree add-payment-gateway
+/osddt.spec
+/osddt.plan use Stripe SDK, REST endpoints
+/osddt.tasks
+/osddt.implement
+/osddt.done
+```
+
+The worktree is created as a sibling of the repo root (e.g. `../my-repo-add-payment-gateway`). Active worktrees are tracked in `.osddt-worktrees` (sibling to the repo root) — a JSON array with entries containing `featureName`, `branch`, `worktreePath`, `workingDir`, and `repoRoot`. `osddt.continue` and `osddt.done` read this file to resolve the correct paths. When `osddt.done` runs, it archives the planning folder **and** removes the worktree automatically.
+
+You can customise the worktree base directory via `worktreeBase` in `.osddtrc`:
+
+```json
+{ "repoType": "single", "worktreeBase": "/Users/me/worktrees" }
+```
+
 ---
 
 - Use **`osddt.research`** when you want to explore the codebase and gather findings before writing the spec. It creates the `working-on/<feature-name>/` folder and writes `osddt.research.md`.
@@ -304,6 +343,17 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
   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.
@@ -311,7 +361,9 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
   1. Reads `.osddtrc` to resolve the project path (single vs monorepo). For monorepos, asks the user which package.
   2. Lists all folders under `working-on/`. If there is only one, uses it automatically; if there are multiple, asks the user to pick one.
   3. Confirms all tasks in `osddt.tasks.md` are checked off (`- [x]`).
-  4. Runs `npx @dezkareid/osddt done <feature-name> --dir <project-path>` to move the folder.
+  4. Runs `npx @dezkareid/osddt worktree-info <feature-name>` to check if this is a worktree feature.
+     - If found: runs `npx @dezkareid/osddt done <feature-name> --dir <project-path> --worktree` (archives folder, removes worktree, cleans state file).
+     - If not found: runs `npx @dezkareid/osddt done <feature-name> --dir <project-path>` (existing behaviour).
 
 Note: the `osddt done` CLI command does **not** read `.osddtrc` — project path resolution is the agent's responsibility, handled in step 1 above.
 

package/README.md

@@ -3,13 +3,18 @@ Other spec driven development tool but for monorepo
 
 ## CLI Commands
 
-| Command                                                              | Description                                                   |
-| -------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `@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 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 update`                                            | Regenerate agent command files from the existing `.osddtrc`   |
+| Command                                                                          | Description                                                   |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `@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 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    |
+| `@dezkareid/osddt update`                                                        | Regenerate agent command files from the existing `.osddtrc`   |
+| `@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
 
@@ -106,6 +111,40 @@ flowchart LR
 
 > Review the `## Assumptions` section of `osddt.plan.md` before implementing. Run `/osddt.clarify` if any Open Questions in the spec need resolving first.
 
+#### 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:
+
+```bash
+npx @dezkareid/osddt setup-worktree
+```
+
+Then start a feature in its own worktree:
+
+```
+/osddt.start-worktree add-payment-gateway
+/osddt.spec
+/osddt.plan use Stripe SDK, REST endpoints
+/osddt.tasks
+/osddt.implement
+/osddt.done
+```
+
+The worktree is created as a sibling of your repo (e.g. `../my-repo-add-payment-gateway`). The `working-on/` planning folder lives inside the worktree alongside the code. When `osddt.done` runs, it archives the planning folder **and** removes the worktree automatically.
+
+You can customise the worktree base directory by adding `worktreeBase` to `.osddtrc`:
+
+```json
+{
+  "repoType": "single",
+  "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.
+
 #### Resuming after closing a session
 
 ```
@@ -118,18 +157,19 @@ flowchart LR
 /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.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 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   |
 
 Generated files are placed in:
 

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

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

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

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+export interface WorktreeEntry {
+    featureName: string;
+    branch: string;
+    worktreePath: string;
+    workingDir: string;
+    repoRoot: string;
+}
+export declare function startWorktreeCommand(): Command;

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

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

package/dist/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import path from 'path';
 import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
 import select from '@inquirer/select';
 import checkbox from '@inquirer/checkbox';
 import { execSync } from 'child_process';
+import readline from 'readline';
 
 function getRepoPreamble(npxCommand) {
     return `## Context
@@ -120,6 +122,15 @@ 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 |
@@ -221,6 +232,45 @@ ${getCustomContextStep(npxCommand, 'start')}## Arguments
 
 ${args}
 
+${getNextStepToSpec(args)}
+`,
+    },
+    {
+        name: 'osddt.start-worktree',
+        description: 'Start a new feature using a git worktree for parallel development',
+        body: ({ args, npxCommand }) => `${getRepoPreamble(npxCommand)}## Instructions
+
+The argument provided is: ${args}
+
+Determine the branch name using the following logic:
+
+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.
+
+Apply the constraints below to the feature name (the segment after the last \`/\`) before using it:
+
+${FEATURE_NAME_RULES}
+
+Once the branch name is determined:
+
+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. Report the branch name, worktree path, and working directory shown in the command output.
+
+${getCustomContextStep(npxCommand, 'start')}## Arguments
+
+${args}
+
 ${getNextStepToSpec(args)}
 `,
     },
@@ -501,16 +551,53 @@ ${args}
         body: ({ npxCommand }) => `## Instructions
 
 1. Confirm all tasks in \`osddt.tasks.md\` are checked off (\`- [x]\`)
-2. Run the following command to move the feature folder from \`working-on\` to \`done\`:
+2. Run the following command to check whether this feature uses a git worktree:
 
 \`\`\`
-${npxCommand} done <feature-name> --dir <project-path>
+${npxCommand} worktree-info <feature-name>
 \`\`\`
 
-   The command will automatically prefix the destination folder name with today's date in \`YYYY-MM-DD\` format.
+3. Based on the result:
+
+   **If it exits with code 1 (standard feature):** use the project path from \`.osddtrc\`, then run:
+   \`\`\`
+   ${npxCommand} done <feature-name> --dir <project-path>
+   \`\`\`
+   Skip to step 8.
+
+   **If it exits with code 0 (worktree feature):** parse the JSON to get \`worktreePath\` and \`branch\`, derive \`<project-path>\` from \`workingDir\`, then continue below.
+
+4. Check for uncommitted changes inside the worktree:
+
+   \`\`\`
+   git -C <worktreePath> status --porcelain
+   \`\`\`
+
+5. If there are **uncommitted changes**:
+   1. Run \`git -C <worktreePath> diff\` to inspect them.
+   2. Derive a concise commit message in **conventional commit** format (e.g. \`feat: add payment gateway integration\`) based on the diff.
+   3. Present the proposed message to the user: _"Use this commit message, or provide your own?"_
+   4. Once confirmed, commit:
+      \`\`\`
+      git -C <worktreePath> add -A
+      git -C <worktreePath> commit -m "<confirmed-message>"
+      \`\`\`
+
+6. Push the branch to remote (covers both first push and subsequent pushes):
+
+   \`\`\`
+   git -C <worktreePath> push --set-upstream origin <branch>
+   \`\`\`
+
+7. Run the done command with the \`--worktree\` flag:
+   \`\`\`
+   ${npxCommand} done <feature-name> --dir <project-path> --worktree
+   \`\`\`
+
+8. The command will automatically prefix the destination folder name with today's date in \`YYYY-MM-DD\` format.
    For example, \`working-on/feature-a\` will be moved to \`done/YYYY-MM-DD-feature-a\`.
 
-3. Report the result of the command, including the full destination path
+9. Report the result of the command, including the full destination path
 
 ${getCustomContextStep(npxCommand, 'done')}`,
     },
@@ -526,7 +613,7 @@ ${body}`;
 }
 function getClaudeTemplates(cwd, npxCommand) {
     const dir = path.join(cwd, CLAUDE_COMMANDS_DIR);
-    return COMMAND_DEFINITIONS.map((cmd) => ({
+    return COMMAND_DEFINITIONS.map(cmd => ({
         filePath: path.join(dir, `${cmd.name}.md`),
         content: formatClaudeCommand(cmd.description, cmd.body({ args: '$ARGUMENTS', npxCommand })),
     }));
@@ -542,7 +629,7 @@ ${body}"""
 }
 function getGeminiTemplates(cwd, npxCommand) {
     const dir = path.join(cwd, GEMINI_COMMANDS_DIR);
-    return COMMAND_DEFINITIONS.map((cmd) => ({
+    return COMMAND_DEFINITIONS.map(cmd => ({
         filePath: path.join(dir, `${cmd.name}.toml`),
         content: formatGeminiCommand(cmd.description, cmd.body({ args: '{{args}}', npxCommand })),
     }));
@@ -607,12 +694,12 @@ async function resolveNpxCommand(cwd) {
 const VALID_AGENTS = ['claude', 'gemini'];
 const VALID_REPO_TYPES = ['single', 'monorepo'];
 function parseAgents(raw) {
-    const values = raw.split(',').map((s) => s.trim());
+    const values = raw.split(',').map(s => s.trim());
     if (values.length === 0) {
         console.error('Error: --agents requires at least one value.');
         process.exit(1);
     }
-    const invalid = values.filter((v) => !VALID_AGENTS.includes(v));
+    const invalid = values.filter(v => !VALID_AGENTS.includes(v));
     if (invalid.length > 0) {
         console.error(`Error: Invalid agent(s): ${invalid.join(', ')}. Valid values: ${VALID_AGENTS.join(', ')}.`);
         process.exit(1);
@@ -711,7 +798,13 @@ function todayPrefix() {
     const dd = String(now.getDate()).padStart(2, '0');
     return `${yyyy}-${mm}-${dd}`;
 }
-async function runDone(featureName, cwd) {
+function resolveRepoRoot$2(cwd) {
+    return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim();
+}
+function stateFilePath$2(repoRoot) {
+    return path.join(path.dirname(repoRoot), '.osddt-worktrees');
+}
+async function runDone(featureName, cwd, worktree) {
     const src = path.join(cwd, 'working-on', featureName);
     const destName = `${todayPrefix()}-${featureName}`;
     const dest = path.join(cwd, 'done', destName);
@@ -722,6 +815,30 @@ async function runDone(featureName, cwd) {
     await fs.ensureDir(path.dirname(dest));
     await fs.move(src, dest);
     console.log(`Moved: working-on/${featureName} → done/${destName}`);
+    if (!worktree)
+        return;
+    const repoRoot = resolveRepoRoot$2(process.cwd());
+    const stateFile = stateFilePath$2(repoRoot);
+    if (!(await fs.pathExists(stateFile))) {
+        console.error(`Warning: .osddt-worktrees not found at ${stateFile}. Skipping worktree cleanup.`);
+        return;
+    }
+    const entries = await fs.readJson(stateFile);
+    const entry = entries.find(e => e.featureName === featureName);
+    if (!entry) {
+        console.error(`Warning: No worktree entry found for "${featureName}". Skipping worktree cleanup.`);
+        return;
+    }
+    if (await fs.pathExists(entry.worktreePath)) {
+        execSync(`git worktree remove "${entry.worktreePath}" --force`, { cwd: repoRoot, stdio: 'inherit' });
+        console.log(`Removed worktree: ${entry.worktreePath}`);
+    }
+    else {
+        console.log(`Worktree path not found on filesystem, skipping git worktree remove.`);
+    }
+    const updated = entries.filter(e => e.featureName !== featureName);
+    await fs.writeJson(stateFile, updated, { spaces: 2 });
+    console.log(`Removed state entry for "${featureName}" from .osddt-worktrees`);
 }
 function doneCommand() {
     const cmd = new Command('done');
@@ -729,9 +846,10 @@ function doneCommand() {
         .description('Move a feature from working-on/<feature-name> to done/<feature-name>')
         .argument('<feature-name>', 'name of the feature to mark as done')
         .option('-d, --dir <directory>', 'project directory', process.cwd())
+        .option('--worktree', 'also remove the git worktree and clean up the state file')
         .action(async (featureName, options) => {
         const targetDir = path.resolve(options.dir);
-        await runDone(featureName, targetDir);
+        await runDone(featureName, targetDir, options.worktree ?? false);
     });
     return cmd;
 }
@@ -744,7 +862,7 @@ async function hasOsddtCommandFile(dir, pattern) {
     if (!(await fs.pathExists(dir)))
         return false;
     const entries = await fs.readdir(dir);
-    return entries.some((f) => pattern.test(f));
+    return entries.some(f => pattern.test(f));
 }
 async function inferAgents(cwd) {
     const detected = [];
@@ -867,14 +985,284 @@ function contextCommand() {
     return cmd;
 }
 
+function resolveRepoRoot$1(cwd) {
+    return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim();
+}
+function repoName(repoRoot) {
+    return path.basename(repoRoot);
+}
+function stateFilePath$1(repoRoot) {
+    return path.join(path.dirname(repoRoot), '.osddt-worktrees');
+}
+async function readStateFile(stateFile) {
+    if (!(await fs.pathExists(stateFile)))
+        return [];
+    return fs.readJson(stateFile);
+}
+async function writeStateFile(stateFile, entries) {
+    await fs.writeJson(stateFile, entries, { spaces: 2 });
+}
+function branchExists(branch, cwd) {
+    try {
+        execSync(`git rev-parse --verify ${branch}`, { cwd, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function remoteBranchExists(branch, cwd) {
+    try {
+        execSync(`git ls-remote --exit-code --heads origin ${branch}`, { cwd, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function createWorktree(branch, worktreePath, repoRoot) {
+    if (await fs.pathExists(worktreePath)) {
+        console.log(`\nDirectory already exists at: ${worktreePath}`);
+        const answer = await prompt('Resume or Abort? [R/a] ');
+        if (answer.toLowerCase() === 'a') {
+            console.log('Aborted.');
+            process.exit(0);
+        }
+        return;
+    }
+    const localExists = branchExists(branch, repoRoot);
+    const remoteExists = !localExists && remoteBranchExists(branch, repoRoot);
+    if (localExists || remoteExists) {
+        console.log(`\nBranch "${branch}" already exists ${localExists ? 'locally' : 'on remote'}.`);
+        const answer = await prompt('Resume or Abort? [R/a] ');
+        if (answer.toLowerCase() === 'a') {
+            console.log('Aborted.');
+            process.exit(0);
+        }
+        execSync(`git worktree add "${worktreePath}" ${branch}`, { cwd: repoRoot, stdio: 'inherit' });
+    }
+    else {
+        execSync(`git worktree add "${worktreePath}" -b ${branch}`, { cwd: repoRoot, stdio: 'inherit' });
+    }
+}
+async function runStartWorktree(featureName, options) {
+    const cwd = process.cwd();
+    const repoRoot = resolveRepoRoot$1(cwd);
+    const branch = `feat/${featureName}`;
+    // Read .osddtrc
+    const rcPath = path.join(repoRoot, '.osddtrc');
+    let rc = { repoType: 'single' };
+    if (await fs.pathExists(rcPath)) {
+        rc = await fs.readJson(rcPath);
+    }
+    // Resolve worktree path
+    const base = rc.worktreeBase ?? path.dirname(repoRoot);
+    const worktreePath = path.join(base, `${repoName(repoRoot)}-${featureName}`);
+    // Check state file for existing entry
+    const stateFile = stateFilePath$1(repoRoot);
+    const entries = await readStateFile(stateFile);
+    const existing = entries.find(e => e.featureName === featureName);
+    if (existing) {
+        console.log(`\nWorktree for "${featureName}" already exists at: ${existing.worktreePath}`);
+        const answer = await prompt('Resume or Abort? [R/a] ');
+        if (answer.toLowerCase() === 'a') {
+            console.log('Aborted.');
+            process.exit(0);
+        }
+        console.log(`\nResuming existing worktree.`);
+        console.log(`  Branch:          ${existing.branch}`);
+        console.log(`  Worktree path:   ${existing.worktreePath}`);
+        console.log(`  Working dir:     ${existing.workingDir}`);
+        return;
+    }
+    await createWorktree(branch, worktreePath, repoRoot);
+    // Resolve working dir
+    let projectPath;
+    if (rc.repoType === 'monorepo') {
+        const pkg = options.dir ?? await prompt('Package path (e.g. packages/my-package): ');
+        projectPath = path.join(worktreePath, pkg);
+    }
+    else {
+        projectPath = worktreePath;
+    }
+    const workingDir = path.join(projectPath, 'working-on', featureName);
+    await fs.ensureDir(workingDir);
+    // Write state file entry
+    entries.push({ featureName, branch, worktreePath, workingDir, repoRoot });
+    await writeStateFile(stateFile, entries);
+    console.log(`\nWorktree feature started:`);
+    console.log(`  Branch:          ${branch}`);
+    console.log(`  Worktree path:   ${worktreePath}`);
+    console.log(`  Working dir:     ${workingDir}`);
+}
+function startWorktreeCommand() {
+    const cmd = new Command('start-worktree');
+    cmd
+        .description('Start a new feature using a git worktree')
+        .argument('<feature-name>', 'feature name (kebab-case, max 30 chars)')
+        .option('-d, --dir <package>', 'package path within monorepo (skips prompt)')
+        .action(async (featureName, options) => {
+        await runStartWorktree(featureName, options);
+    });
+    return cmd;
+}
+
+function resolveRepoRoot(cwd) {
+    return execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim();
+}
+function stateFilePath(repoRoot) {
+    return path.join(path.dirname(repoRoot), '.osddt-worktrees');
+}
+async function runWorktreeInfo(featureName) {
+    const repoRoot = resolveRepoRoot(process.cwd());
+    const stateFile = stateFilePath(repoRoot);
+    if (!(await fs.pathExists(stateFile))) {
+        console.error(`No .osddt-worktrees file found at: ${stateFile}`);
+        process.exit(1);
+    }
+    const entries = await fs.readJson(stateFile);
+    const entry = entries.find(e => e.featureName === featureName);
+    if (!entry) {
+        console.error(`No worktree entry found for feature: ${featureName}`);
+        process.exit(1);
+    }
+    console.log(JSON.stringify({ worktreePath: entry.worktreePath, workingDir: entry.workingDir, branch: entry.branch }));
+}
+function worktreeInfoCommand() {
+    const cmd = new Command('worktree-info');
+    cmd
+        .description('Look up worktree paths for a feature from the state file')
+        .argument('<feature-name>', 'feature name to look up')
+        .action(async (featureName) => {
+        await runWorktreeInfo(featureName);
+    });
+    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');
+const pkg = fs.readJsonSync(pkgPath);
 const program = new Command();
 program
     .name('osddt')
     .description('Spec-Driven Development tooling for monorepos and single-package repos')
-    .version('0.0.0');
+    .version(pkg.version);
 program.addCommand(setupCommand());
 program.addCommand(metaInfoCommand());
 program.addCommand(doneCommand());
 program.addCommand(updateCommand());
 program.addCommand(contextCommand());
+program.addCommand(startWorktreeCommand());
+program.addCommand(worktreeInfoCommand());
+program.addCommand(setupWorktreeCommand());
 program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/osddt",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Package for Spec-Driven Development workflow",
   "keywords": [
     "spec-driven",
@@ -40,11 +40,14 @@
     "tslib": "2.8.1"
   },
   "devDependencies": {
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-conventional": "20.5.0",
+    "@dezkareid/eslint-plugin-web": "1.0.0",
     "@rollup/plugin-typescript": "12.1.4",
     "@types/fs-extra": "11.0.4",
     "@types/node": "25.0.10",
     "eslint": "9.39.2",
-    "prettier": "3.8.1",
+    "husky": "9.1.7",
     "rollup": "4.56.0",
     "typescript": "5.9.3",
     "vitest": "4.0.18"
@@ -55,7 +58,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src",
-    "format": "prettier --write src",
-    "setup-local": "pnpm run build && npx osddt setup --agents claude --repo-type single"
+    "lint:fix": "eslint src --fix",
+    "setup-local": "pnpm run build && npx osddt setup --agents claude --repo-type single",
+    "update-local": "pnpm run build && npx osddt update"
   }
 }

package/dist/commands/context.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/commands/done.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/commands/meta-info.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/commands/setup.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/commands/update.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/templates/claude.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/templates/gemini.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/templates/shared.spec.d.ts

@@ -1 +0,0 @@
-export {};