@dezkareid/osddt 1.3.2 → 1.4.0

package/AGENTS.md

@@ -131,14 +131,29 @@ osddt/
 
 ### CLI Commands
 
-All commands available via `npx @dezkareid/osddt <command>`:
+#### Invocation forms
 
-| 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>`               |
+There are two contexts in which osddt commands are invoked:
+
+| Context | Command prefix | When to use |
+| ------- | -------------- | ----------- |
+| **Local development of this package** | `osddt` | Working inside this repository — the binary is available directly because the package is installed locally |
+| **External project** (using osddt as a dependency) | `npx @dezkareid/osddt` | Running from a project that lists `@dezkareid/osddt` as a dependency |
+
+When `osddt setup` is run, it reads the `name` field of `package.json` in the target directory. If the name is `@dezkareid/osddt`, templates are written with `npx osddt`. Otherwise they fall back to `npx @dezkareid/osddt`. The resolution lives in `resolveNpxCommand()` in `src/commands/setup.ts`.
+
+#### 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 setup` options
 
@@ -160,6 +175,7 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 | `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                        |
@@ -167,20 +183,21 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 
 #### Template Workflow
 
-`osddt.research` and `osddt.start` are **peer entry points** — use whichever fits your situation. Both lead to `osddt.spec`. Use `osddt.continue` to resume an in-progress feature from a new session.
+`osddt.research` and `osddt.start` are **peer entry points** — use whichever fits your situation. Both lead to `osddt.spec`. If you close the coding session, you should execute the `osddt.continue` command to resume the workflow.
 
 ```
-osddt.continue ──────────────────────────────────────────────────────────────────────────────┐
-                                                                                              │
-osddt.research ──┐                                                                            │
-                 ├──► osddt.spec → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
+osddt.continue ──────────────────────────────────────────────────────────────────────────────────────┐
+                                                                                                      │
+osddt.research ──┐                                                                                    │
+                 ├──► osddt.spec → [osddt.clarify] → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
 osddt.start    ──┘
 ```
 
-- Use **`osddt.continue`** at the start of a new session to detect the current phase and get the exact command to run next. It inspects the `working-on/<feature-name>/` folder for phase files and reports which one was found.
+- Use **`osddt.continue`** if you closed the coding session to detect the current phase and get the exact command to run next. It inspects the `working-on/<feature-name>/` folder for phase files and reports which one was found.
 - 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`.
 - Use **`osddt.start`** when you are ready to begin implementation directly. It creates the git branch and the `working-on/<feature-name>/` folder.
 - Both `osddt.research` and `osddt.start` check whether the working directory already exists and ask to **Resume** or **Abort** if it does.
+- Use **`osddt.clarify`** (optional) to resolve any Open Questions in the spec before planning. It can be invoked at any point in the workflow; after each session it always prompts to run (or re-run) `osddt.plan`.
 
 #### Generated File Locations
 
@@ -195,7 +212,8 @@ osddt.start    ──┘
 - **Actions performed by the agent**:
   1. Runs `npx @dezkareid/osddt meta-info` and reads `.osddtrc` to resolve the project path.
   2. Checks the `working-on/<feature-name>/` folder for the following phase files **in order**: `osddt.tasks.md` (with unchecked tasks), `osddt.tasks.md` (all checked), `osddt.plan.md`, `osddt.spec.md`, `osddt.research.md`.
-  3. Reports the file found, the current phase, and the **exact command** the user should run next.
+  3. Reports the file found, the current phase, and the **exact command** the user should run next. Commands that require no further arguments (`/osddt.implement`, `/osddt.done`, `/osddt.tasks`) are suggested without arguments; commands that still need feature context (`/osddt.plan`, `/osddt.spec`, `/osddt.research`, `/osddt.clarify`) are suggested with the feature name.
+  4. If the detected phase is **Spec done** or **Planning done** and the spec has unanswered open questions, additionally recommends running `/osddt.clarify`.
 
 #### osddt.start behaviour
 
@@ -214,12 +232,22 @@ osddt.start    ──┘
   2. Checks for an existing `working-on/<feature-name>/` folder — offers **Resume** or **Abort** if found, otherwise creates it.
   3. Researches the topic (codebase exploration, external references) and writes `osddt.research.md`.
 
+#### osddt.clarify behaviour
+
+- **Input**: A feature name or branch name identifying the feature whose spec to clarify.
+- **Actions performed by the agent**:
+  1. Locates `osddt.spec.md` in `working-on/<feature-name>/`; if absent, suggests running `osddt.spec` first.
+  2. Reads the **Open Questions** section and the **Decisions** section (if present) to determine which questions are already answered.
+  3. Informs the user of any already-resolved questions and only asks the remaining unanswered ones.
+  4. Records all new answers in a `## Decisions` section of `osddt.spec.md` (the Open Questions section is left unchanged).
+  5. Always prompts the user to run (or re-run) `osddt.plan` to reflect the updated decisions.
+
 #### osddt.done behaviour
 
-- **Input**: A feature name or branch name identifying the feature to close.
+- **Input**: None — the feature is identified automatically.
 - **Actions performed by the agent**:
   1. Reads `.osddtrc` to resolve the project path (single vs monorepo). For monorepos, asks the user which package.
-  2. Derives the feature name from the input (same rules as other commands — last segment of a branch name or kebab-cased slug, subject to the 30-character limit). Must match the folder under `working-on/`.
+  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.
 

package/README.md

@@ -32,13 +32,13 @@ npx @dezkareid/osddt setup --agents claude,gemini --repo-type single
 
 Run `npx @dezkareid/osddt setup` once to generate the agent command files.
 
-`osddt.research` and `osddt.start` are **peer entry points** — use whichever fits your situation. Both lead to `osddt.spec`. Use `osddt.continue` to resume an in-progress feature from a new session.
+`osddt.research` and `osddt.start` are **peer entry points** — use whichever fits your situation. Both lead to `osddt.spec`. If you close the coding session, you should execute the `osddt.continue` command to resume the workflow.
 
 ```
-osddt.continue ──────────────────────────────────────────────────────────────────────────────┐
-                                                                                              │
-osddt.research ──┐                                                                            │
-                 ├──► osddt.spec → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
+osddt.continue ──────────────────────────────────────────────────────────────────────────────────────┐
+                                                                                                      │
+osddt.research ──┐                                                                                    │
+                 ├──► osddt.spec → [osddt.clarify] → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
 osddt.start    ──┘
 ```
 
@@ -48,6 +48,7 @@ osddt.start    ──┘
 | `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                        |

package/dist/index.js

@@ -6,12 +6,13 @@ import select from '@inquirer/select';
 import checkbox from '@inquirer/checkbox';
 import { execSync } from 'child_process';
 
-const REPO_PREAMBLE = `## Context
+function getRepoPreamble(npxCommand) {
+    return `## Context
 
 Before proceeding, run the following command and parse the JSON output to get the current branch and date:
 
 \`\`\`
-npx @dezkareid/osddt meta-info
+${npxCommand} meta-info
 \`\`\`
 
 ## Repository Configuration
@@ -28,11 +29,12 @@ Before proceeding, read the \`.osddtrc\` file in the root of the repository to d
 
 ## Working Directory
 
-All generated files live under \`<project-path>/working-on/<feature-name>/\`. The \`<feature-name>\` is derived from the arguments provided. Create the directory if it does not exist.
+All generated files live under \`<project-path>/working-on/<feature-name>/\`.
 
 > All file paths in the instructions below are relative to \`<project-path>/working-on/<feature-name>/\`.
 
 `;
+}
 const FEATURE_NAME_RULES = `### Feature Name Constraints
 
 When deriving a feature name from a description:
@@ -62,25 +64,41 @@ const WORKING_DIR_STEP = `Check whether the working directory \`<project-path>/w
    - If it **already exists**, warn the user and ask whether to:
      - **Resume** — continue into the existing folder (proceed to the next step without recreating it)
      - **Abort** — stop and do nothing`;
+const RESOLVE_FEATURE_NAME = `### Resolving the Feature Name
+
+Use the following logic to determine \`<feature-name>\`:
+
+1. If arguments were provided, derive the feature name from them:
+   - If the argument looks like a branch name (no spaces, kebab-case or slash-separated), use the last segment (after the last \`/\`, or the full value if no \`/\` is present).
+   - Otherwise treat it as a human-readable description and convert it to a feature name following the constraints in the Feature Name Constraints section.
+2. If **no arguments were provided**:
+   - List all folders under \`<project-path>/working-on/\`.
+   - If there is **only one folder**, use it automatically and inform the user.
+   - If there are **multiple folders**, present the list to the user and ask them to pick one.
+   - If there are **no folders**, inform the user that no in-progress features were found and stop.`;
 const COMMAND_DEFINITIONS = [
     {
         name: 'osddt.continue',
         description: 'Detect the current workflow phase and prompt the next command to run',
-        body: (args) => `${REPO_PREAMBLE}## Instructions
+        body: ({ args, npxCommand }) => `${getRepoPreamble(npxCommand)}${RESOLVE_FEATURE_NAME}
+
+## Instructions
 
 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 |
 | --------- | ------------- | -------- |
-| \`osddt.tasks.md\` exists **and** has at least one unchecked task (\`- [ ]\`) | Implementing | \`/osddt.implement ${args}\` |
-| \`osddt.tasks.md\` exists **and** all tasks are checked (\`- [x]\`) | Ready to close | \`/osddt.done ${args}\` |
-| \`osddt.plan.md\` exists | Planning done | \`/osddt.tasks ${args}\` |
-| \`osddt.spec.md\` exists | Spec done | \`/osddt.plan ${args}\` |
-| \`osddt.research.md\` exists | Research done | \`/osddt.spec ${args}\` |
-| None of the above | Not started | \`/osddt.spec ${args}\` (or \`/osddt.research ${args}\` if research is needed first) |
+| \`osddt.tasks.md\` exists **and** has at least one unchecked task (\`- [ ]\`) | Implementing | \`/osddt.implement\` |
+| \`osddt.tasks.md\` exists **and** all tasks are checked (\`- [x]\`) | Ready to close | \`/osddt.done\` |
+| \`osddt.plan.md\` exists | Planning done | \`/osddt.tasks\` |
+| \`osddt.spec.md\` exists | Spec done | \`/osddt.plan <tech stack and key technical decisions>\` |
+| \`osddt.research.md\` exists | Research done | \`/osddt.spec <brief feature description>\` |
+| None of the above | Not started | \`/osddt.spec <brief feature description>\` (or \`/osddt.research <topic>\` if research is needed first) |
 
 Report which file was found, which phase that corresponds to, and the exact command the user should run next.
 
+> **Open Questions check**: After reporting the phase, if the detected phase is **Spec done** or **Planning done**, also check whether \`osddt.spec.md\` contains any unanswered open questions (items in the **Open Questions** section with no corresponding entry in the **Decisions** section). If unanswered questions exist, inform the user and recommend running \`/osddt.clarify <feature-name>\` before (or in addition to) the suggested next command.
+
 ## Arguments
 
 ${args}
@@ -89,7 +107,7 @@ ${args}
     {
         name: 'osddt.research',
         description: 'Research a topic and write a research file to inform the feature specification',
-        body: (args) => `${REPO_PREAMBLE}## Instructions
+        body: ({ args, npxCommand }) => `${getRepoPreamble(npxCommand)}## Instructions
 
 The argument provided is: ${args}
 
@@ -132,14 +150,14 @@ ${args}
 Run the following command to write the feature specification:
 
 \`\`\`
-/osddt.spec ${args}
+/osddt.spec <brief description of the feature or topic researched>
 \`\`\`
 `,
     },
     {
         name: 'osddt.start',
         description: 'Start a new feature by creating a branch and working-on folder',
-        body: (args) => `${REPO_PREAMBLE}## Instructions
+        body: ({ args, npxCommand }) => `${getRepoPreamble(npxCommand)}## Instructions
 
 The argument provided is: ${args}
 
@@ -178,14 +196,14 @@ ${args}
 Run the following command to write the feature specification:
 
 \`\`\`
-/osddt.spec ${args}
+/osddt.spec <brief description of the feature being built>
 \`\`\`
 `,
     },
     {
         name: 'osddt.spec',
         description: 'Analyze requirements and write a feature specification',
-        body: (args) => `## Instructions
+        body: ({ args }) => `## Instructions
 
 1. Check whether \`osddt.research.md\` exists in the working directory.
    - If it exists, read it and use its findings (key insights, constraints, open questions, codebase findings) as additional context when writing the specification.
@@ -217,14 +235,49 @@ ${args}
 Run the following command to create the implementation plan:
 
 \`\`\`
-/osddt.plan ${args}
+/osddt.plan <tech stack and key technical decisions, e.g. "use Node.js with SQLite, REST API, no auth">
+\`\`\`
+`,
+    },
+    {
+        name: 'osddt.clarify',
+        description: 'Resolve open questions in the spec and record decisions',
+        body: () => `## Instructions
+
+1. Check whether \`osddt.spec.md\` exists in the working directory:
+   - If it **does not exist**, inform the user that no spec was found and suggest running \`/osddt.spec <brief feature description>\` first. Stop here.
+
+2. Read \`osddt.spec.md\` and extract all items listed under the **Open Questions** section.
+   - If the **Open Questions** section is absent or empty, inform the user that there are no open questions to resolve. Skip to step 6.
+
+3. Read the **Decisions** section of \`osddt.spec.md\` (if it exists) to determine which questions have already been answered.
+   - A question is considered answered if there is a corresponding numbered entry in the **Decisions** section.
+   - List the already-answered questions to the user and inform them they will be skipped.
+
+4. For each **unanswered** question (in order), present it to the user and collect a response.
+   - If all questions were already answered, inform the user and skip to step 6.
+
+5. Update the **Decisions** section in \`osddt.spec.md\`:
+   - If a **Decisions** section already exists, append new entries to it (do not modify existing entries).
+   - If no **Decisions** section exists, add one at the end of the file.
+   - Each decision entry uses the format: \`N. **<short question summary>**: <answer>\`
+   - The **Open Questions** section is left unchanged.
+
+6. Inform the user that all questions are now resolved (or were already resolved). Then prompt them to run (or re-run) the plan step so it reflects the updated decisions:
+
+\`\`\`
+/osddt.plan <tech stack and key technical decisions, e.g. "use Node.js with SQLite, REST API, no auth">
 \`\`\`
+
+> Note: if \`osddt.plan.md\` already exists, the plan should be regenerated to incorporate the decisions.
 `,
     },
     {
         name: 'osddt.plan',
         description: 'Create a technical implementation plan from a specification',
-        body: (args) => `## Instructions
+        body: ({ args }) => `${RESOLVE_FEATURE_NAME}
+
+## Instructions
 
 1. Check whether \`osddt.plan.md\` already exists in the working directory:
    - If it **does not exist**, proceed to generate it.
@@ -233,9 +286,16 @@ Run the following command to create the implementation plan:
      - **Update** — read the existing file and apply targeted changes based on ${args}
      - **Do nothing** — stop here and leave the file as-is
 2. Read \`osddt.spec.md\` from the working directory
-3. Break down the implementation into logical phases and steps
-4. Identify technical decisions, dependencies, and risks
-5. Write the plan to \`osddt.plan.md\` in the working directory
+3. Check for unanswered open questions in the spec:
+   - Count the items in the **Open Questions** section that have no corresponding entry in the **Decisions** section.
+   - If there are any unanswered questions, inform the user: "This spec has X unanswered open question(s)."
+   - Ask the user whether to:
+     - **Clarify first** — stop here and suggest running \`/osddt.clarify <feature-name>\` instead
+     - **Proceed anyway** — continue with plan generation using the spec as-is
+   - If there are no unanswered questions, proceed silently.
+4. Break down the implementation into logical phases and steps
+5. Identify technical decisions, dependencies, and risks
+6. Write the plan to \`osddt.plan.md\` in the working directory
 
 ## Plan Format
 
@@ -255,20 +315,21 @@ ${args}
 Run the following command to generate the task list:
 
 \`\`\`
-/osddt.tasks ${args}
+/osddt.tasks
 \`\`\`
 `,
     },
     {
         name: 'osddt.tasks',
         description: 'Generate actionable tasks from an implementation plan',
-        body: (args) => `## Instructions
+        body: () => `${RESOLVE_FEATURE_NAME}
+
+## Instructions
 
 1. Check whether \`osddt.tasks.md\` already exists in the working directory:
    - If it **does not exist**, proceed to generate it.
    - If it **already exists**, ask the user whether to:
      - **Regenerate** — discard the existing file and create a fresh task list from scratch
-     - **Update** — read the existing file and apply targeted changes based on ${args}
      - **Do nothing** — stop here and leave the file as-is
 2. Read \`osddt.plan.md\` from the working directory
 3. Break each phase into discrete, executable tasks
@@ -283,26 +344,22 @@ The task list should include:
 - **Dependencies**: Note which tasks must complete before others
 - **Definition of Done**: Clear completion criteria per phase
 
-## Arguments
-
-${args}
-
 ## Next Step
 
 Run the following command to start implementing tasks:
 
 \`\`\`
-/osddt.implement ${args}
+/osddt.implement
 \`\`\`
 `,
     },
     {
         name: 'osddt.implement',
         description: 'Execute tasks from the task list one by one',
-        body: (args) => `## Instructions
+        body: () => `## Instructions
 
 1. Check whether \`osddt.tasks.md\` exists in the working directory:
-   - If it **does not exist**, stop and ask the user to run \`/osddt.tasks ${args}\` first.
+   - If it **does not exist**, stop and ask the user to run \`/osddt.tasks\` first.
 2. Read \`osddt.tasks.md\` from the working directory
 3. Find the next unchecked task (\`- [ ]\`)
 4. Implement that task following the spec (\`osddt.spec.md\`) and plan (\`osddt.plan.md\`) in the working directory
@@ -316,44 +373,31 @@ Run the following command to start implementing tasks:
 - Write tests for new functionality when applicable
 - Ask for clarification if requirements are ambiguous
 
-## Arguments
-
-${args}
-
 ## Next Step
 
 Once all tasks are checked off, run the following command to mark the feature as done:
 
 \`\`\`
-/osddt.done ${args}
+/osddt.done
 \`\`\`
 `,
     },
     {
         name: 'osddt.done',
         description: 'Mark a feature as done and move it from working-on to done',
-        body: (args) => `## Instructions
+        body: ({ npxCommand }) => `## Instructions
 
-1. Resolve the project path:
-   - Read \`.osddtrc\` from the repository root.
-   - 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.
-2. Derive the feature name from ${args} using the same rules as the other commands (last segment of a branch name, or a kebab-cased slug — subject to the 30-character limit). This must match the folder name under \`working-on/\`.
-3. Confirm all tasks in \`osddt.tasks.md\` are checked off (\`- [x]\`)
-4. Run the following command to move the feature folder from \`working-on\` to \`done\`:
+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\`:
 
 \`\`\`
-npx @dezkareid/osddt done <feature-name> --dir <project-path>
+${npxCommand} done <feature-name> --dir <project-path>
 \`\`\`
 
    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\`.
 
-5. Report the result of the command, including the full destination path
-
-## Arguments
-
-${args}
+3. Report the result of the command, including the full destination path
 `,
     },
 ];
@@ -366,11 +410,11 @@ description: "${description}"
 
 ${body}`;
 }
-function getClaudeTemplates(cwd) {
+function getClaudeTemplates(cwd, npxCommand) {
     const dir = path.join(cwd, CLAUDE_COMMANDS_DIR);
     return COMMAND_DEFINITIONS.map((cmd) => ({
         filePath: path.join(dir, `${cmd.name}.md`),
-        content: formatClaudeCommand(cmd.description, cmd.body('$ARGUMENTS')),
+        content: formatClaudeCommand(cmd.description, cmd.body({ args: '$ARGUMENTS', npxCommand })),
     }));
 }
 
@@ -382,11 +426,11 @@ prompt = """
 ${body}"""
 `;
 }
-function getGeminiTemplates(cwd) {
+function getGeminiTemplates(cwd, npxCommand) {
     const dir = path.join(cwd, GEMINI_COMMANDS_DIR);
     return COMMAND_DEFINITIONS.map((cmd) => ({
         filePath: path.join(dir, `${cmd.name}.toml`),
-        content: formatGeminiCommand(cmd.description, cmd.body('{{args}}')),
+        content: formatGeminiCommand(cmd.description, cmd.body({ args: '{{args}}', npxCommand })),
     }));
 }
 
@@ -431,6 +475,21 @@ async function askAgents() {
     });
 }
 
+const CANONICAL_PACKAGE_NAME = '@dezkareid/osddt';
+const NPX_COMMAND = 'npx osddt';
+const NPX_COMMAND_FALLBACK = `npx ${CANONICAL_PACKAGE_NAME}`;
+async function resolveNpxCommand(cwd) {
+    const pkgPath = path.join(cwd, 'package.json');
+    try {
+        const pkg = await fs.readJson(pkgPath);
+        if (pkg.name === CANONICAL_PACKAGE_NAME)
+            return NPX_COMMAND;
+    }
+    catch {
+        // no package.json or unreadable — fall through to default
+    }
+    return NPX_COMMAND_FALLBACK;
+}
 const VALID_AGENTS = ['claude', 'gemini'];
 const VALID_REPO_TYPES = ['single', 'monorepo'];
 function parseAgents(raw) {
@@ -470,9 +529,10 @@ async function runSetup(cwd, rawAgents, rawRepoType) {
     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');
     if (agents.includes('claude')) {
-        const claudeFiles = getClaudeTemplates(cwd);
+        const claudeFiles = getClaudeTemplates(cwd, npxCommand);
         console.log('Claude Code commands (.claude/commands/):');
         for (const file of claudeFiles) {
             await writeCommandFile(file);
@@ -480,7 +540,7 @@ async function runSetup(cwd, rawAgents, rawRepoType) {
         console.log('');
     }
     if (agents.includes('gemini')) {
-        const geminiFiles = getGeminiTemplates(cwd);
+        const geminiFiles = getGeminiTemplates(cwd, npxCommand);
         console.log('Gemini CLI commands (.gemini/commands/):');
         for (const file of geminiFiles) {
             await writeCommandFile(file);

package/dist/templates/claude.d.ts

@@ -2,5 +2,5 @@ interface CommandFile {
     filePath: string;
     content: string;
 }
-export declare function getClaudeTemplates(cwd: string): CommandFile[];
+export declare function getClaudeTemplates(cwd: string, npxCommand: string): CommandFile[];
 export {};

package/dist/templates/gemini.d.ts

@@ -2,5 +2,5 @@ interface CommandFile {
     filePath: string;
     content: string;
 }
-export declare function getGeminiTemplates(cwd: string): CommandFile[];
+export declare function getGeminiTemplates(cwd: string, npxCommand: string): CommandFile[];
 export {};

package/dist/templates/shared.d.ts

@@ -1,10 +1,15 @@
-export declare const REPO_PREAMBLE = "## Context\n\nBefore proceeding, run the following command and parse the JSON output to get the current branch and date:\n\n```\nnpx @dezkareid/osddt meta-info\n```\n\n## Repository Configuration\n\nBefore proceeding, read the `.osddtrc` file in the root of the repository to determine the project path.\n\n```json\n// .osddtrc example\n{ \"repoType\": \"monorepo\" | \"single\" }\n```\n\n- If `repoType` is `\"single\"`: the project path is the repository root.\n- 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.\n\n## Working Directory\n\nAll generated files live under `<project-path>/working-on/<feature-name>/`. The `<feature-name>` is derived from the arguments provided. Create the directory if it does not exist.\n\n> All file paths in the instructions below are relative to `<project-path>/working-on/<feature-name>/`.\n\n";
+export declare function getRepoPreamble(npxCommand: string): string;
 export declare const FEATURE_NAME_RULES = "### Feature Name Constraints\n\nWhen deriving a feature name from a description:\n\n- Use only lowercase letters, digits, and hyphens (`a-z`, `0-9`, `-`)\n- Replace spaces and special characters with hyphens\n- Remove consecutive hyphens (e.g. `--` \u2192 `-`)\n- Remove leading and trailing hyphens\n- **Maximum length: 30 characters** \u2014 if the derived name exceeds 30 characters, truncate at the last hyphen boundary before or at the 30th character\n- If the input is already a valid branch name (no spaces, kebab-case or slash-separated), apply the 30-character limit to the last segment only (after the last `/`)\n- Reject (and ask the user to provide a shorter name) if no valid name can be derived after truncation\n\n**Examples:**\n\n| Input | Derived feature name |\n| ----------------------------------------------------- | ---------------------------- |\n| `Add user authentication` | `add-user-authentication` |\n| `Implement real-time notifications for dashboard` | `implement-real-time` |\n| `feat/add-user-authentication` | `add-user-authentication` |\n| `feat/implement-real-time-notifications-for-dashboard` | `implement-real-time` |\n";
 export declare const WORKING_DIR_STEP = "Check whether the working directory `<project-path>/working-on/<feature-name>` already exists:\n   - If it **does not exist**, create it:\n     ```\n     mkdir -p <project-path>/working-on/<feature-name>\n     ```\n   - If it **already exists**, warn the user and ask whether to:\n     - **Resume** \u2014 continue into the existing folder (proceed to the next step without recreating it)\n     - **Abort** \u2014 stop and do nothing";
+export declare const RESOLVE_FEATURE_NAME = "### Resolving the Feature Name\n\nUse the following logic to determine `<feature-name>`:\n\n1. If arguments were provided, derive the feature name from them:\n   - If the argument looks like a branch name (no spaces, kebab-case or slash-separated), use the last segment (after the last `/`, or the full value if no `/` is present).\n   - Otherwise treat it as a human-readable description and convert it to a feature name following the constraints in the Feature Name Constraints section.\n2. If **no arguments were provided**:\n   - List all folders under `<project-path>/working-on/`.\n   - If there is **only one folder**, use it automatically and inform the user.\n   - If there are **multiple folders**, present the list to the user and ask them to pick one.\n   - If there are **no folders**, inform the user that no in-progress features were found and stop.";
 export type ArgPlaceholder = '$ARGUMENTS' | '{{args}}';
+export interface CommandDefinitionContext {
+    args: ArgPlaceholder;
+    npxCommand: string;
+}
 export interface CommandDefinition {
     name: string;
     description: string;
-    body: (args: ArgPlaceholder) => string;
+    body: (ctx: CommandDefinitionContext) => string;
 }
 export declare const COMMAND_DEFINITIONS: CommandDefinition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/osddt",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Package for Spec-Driven Development workflow",
   "keywords": [
     "spec-driven",