@dezkareid/osddt 1.5.0 → 1.7.0

package/AGENTS.md

@@ -105,7 +105,8 @@ osddt/
 │   ├── commands/
 │   │   ├── setup.ts               # `osddt setup` — prompts for agents & repo type (or reads --agents/--repo-type flags), writes command files and .osddtrc
 │   │   ├── meta-info.ts           # `osddt meta-info` — outputs { branch, date } as JSON (consumed by generated templates)
-│   │   └── done.ts                # `osddt done <feature>` — moves working-on/<feature> → done/YYYY-MM-DD-<feature>
+│   │   ├── done.ts                # `osddt done <feature>` — moves working-on/<feature> → done/YYYY-MM-DD-<feature>
+│   │   └── update.ts              # `osddt update` — reads .osddtrc and regenerates agent command files for detected agents
 │   ├── templates/
 │   │   ├── shared.ts              # REPO_PREAMBLE, FEATURE_NAME_RULES, WORKING_DIR_STEP, and COMMAND_DEFINITIONS array
 │   │   ├── claude.ts              # Formats COMMAND_DEFINITIONS as Markdown (.claude/commands/osddt.<name>.md)
@@ -117,7 +118,7 @@ osddt/
 ├── tsconfig.json                  # TypeScript config
 ├── vitest.config.ts               # Vitest config
 ├── package.json                   # Package name: @dezkareid/osddt, bin: osddt → dist/index.js
-├── .osddtrc                       # Runtime config written by setup (repoType: "single" | "monorepo")
+├── .osddtrc                       # Runtime config written by setup (repoType: "single" | "monorepo", agents: ["claude", "gemini"])
 ├── AGENTS.md / CLAUDE.md / GEMINI.md  # Agent-specific instructions (kept in sync)
 └── README.md                      # Public-facing documentation
 ```
@@ -142,6 +143,8 @@ There are two contexts in which osddt commands are invoked:
 
 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`.
 
+The selected agents are saved in `.osddtrc` alongside `repoType`. When `osddt update` is run, if `.osddtrc` has no `agents` key, it scans each agent's command directory for any command files to infer the active agents and writes the result back into `.osddtrc`.
+
 #### Available commands
 
 | Command                                                              | Context       | Description                                                   |
@@ -154,6 +157,8 @@ When `osddt setup` is run, it reads the `name` field of `package.json` in the ta
 | `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 setup` options
 
@@ -183,17 +188,65 @@ 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`. If you close the coding session, you should execute the `osddt.continue` command to resume the workflow.
+`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, execute `osddt.continue` to resume the workflow.
+
+**Standard steps:**
+
+1. Pick an entry point:
+   - **`osddt.research <topic>`** — explore the codebase or gather external findings first, then proceed to spec.
+   - **`osddt.start <feature>`** — jump straight to creating the branch and working directory, then write the spec.
+2. **`osddt.spec <feature>`** — analyse requirements and write the feature specification.
+3. *(optional)* **`osddt.clarify <feature>`** — resolve any Open Questions in the spec and record decisions.
+4. **`osddt.plan <tech decisions>`** — create a technical implementation plan from the spec.
+5. **`osddt.tasks`** — generate a checklist of actionable tasks from the plan.
+6. **`osddt.implement`** — execute tasks one by one until all are checked off.
+7. **`osddt.done`** — verify all tasks are complete and move the feature folder to `done/`.
+
+> **Note:** You can re-run any step to go back and revise it — except once `osddt.done` has been executed, the feature is considered finished and cannot be revisited.
+
+**If you close a session:**
+
+- Run **`osddt.continue <feature>`** — it inspects the `working-on/<feature-name>/` folder, identifies the current phase, and tells you the exact next command to run.
+
+---
+
+##### Example A — Starting with research
 
 ```
-osddt.continue ──────────────────────────────────────────────────────────────────────────────────────┐
-                                                                                                      │
-osddt.research ──┐                                                                                    │
-                 ├──► osddt.spec → [osddt.clarify] → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
-osddt.start    ──┘
+/osddt.research add payment gateway
+/osddt.spec add-payment-gateway
+/osddt.clarify add-payment-gateway   # optional — resolve open questions
+/osddt.plan use Stripe SDK, REST endpoints, no webhooks
+/osddt.tasks
+/osddt.implement
+/osddt.done
 ```
 
-- 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.
+##### Example B — Starting directly
+
+```
+/osddt.start add user profile page
+/osddt.spec add-user-profile-page
+/osddt.plan React with React Query, REST API
+/osddt.tasks
+/osddt.implement
+/osddt.done
+```
+
+##### Example C — Resuming after closing a session
+
+```
+# You closed Claude and want to pick up where you left off:
+/osddt.continue add-payment-gateway
+# → osddt.continue detects osddt.plan.md exists and reports:
+#   "Planning phase complete. Run: /osddt.tasks"
+/osddt.tasks
+/osddt.implement
+/osddt.done
+```
+
+---
+
 - 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.
@@ -223,6 +276,9 @@ osddt.start    ──┘
   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.
 
 #### osddt.research behaviour
 
@@ -231,10 +287,12 @@ osddt.start    ──┘
   1. Derives the feature name (subject to the 30-character limit).
   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`.
+  4. 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.
 
 #### 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.

package/README.md

@@ -9,6 +9,7 @@ Other spec driven development tool but for monorepo
 | `@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`   |
 
 ### `osddt setup` options
 
@@ -20,6 +21,8 @@ Other spec driven development tool but for monorepo
 
 Both flags are optional. Providing neither runs the fully interactive mode. Providing both skips all prompts.
 
+The selected agents are saved in `.osddtrc` alongside `repoType` so that `osddt update` can regenerate the correct files without prompting.
+
 ```bash
 # Interactive (default)
 npx @dezkareid/osddt setup
@@ -32,14 +35,74 @@ 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`. If you close the coding session, you should execute the `osddt.continue` command to resume the workflow.
+`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, execute `osddt.continue` to resume the workflow.
+
+```mermaid
+flowchart LR
+    continue([osddt.continue])
+
+    subgraph entry[Entry points]
+        research([osddt.research])
+        start([osddt.start])
+    end
+
+    spec([osddt.spec])
+    clarify([osddt.clarify\noptional])
+    plan([osddt.plan])
+    tasks([osddt.tasks])
+    implement([osddt.implement])
+    done([osddt.done])
+
+    research --> spec
+    start --> spec
+    spec --> clarify
+    clarify --> plan
+    spec --> plan
+    plan --> tasks
+    tasks --> implement
+    implement --> done
+    done --> continue
+    continue -.resume.-> spec & plan & tasks & implement & done
+
+    note["⚠️ You can go back to any step,\nbut once osddt.done runs\nthe feature is finished."]
+    done --- note
+```
+
+### Example workflows
+
+#### Starting with research
+
+```
+/osddt.research add payment gateway
+/osddt.spec add-payment-gateway
+/osddt.clarify add-payment-gateway   # optional — resolve open questions
+/osddt.plan use Stripe SDK, REST endpoints, no webhooks
+/osddt.tasks
+/osddt.implement
+/osddt.done
+```
+
+#### Starting directly
+
+```
+/osddt.start add user profile page
+/osddt.spec add-user-profile-page
+/osddt.plan React with React Query, REST API
+/osddt.tasks
+/osddt.implement
+/osddt.done
+```
+
+#### Resuming after closing a session
 
 ```
-osddt.continue ──────────────────────────────────────────────────────────────────────────────────────┐
-                                                                                                      │
-osddt.research ──┐                                                                                    │
-                 ├──► osddt.spec → [osddt.clarify] → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
-osddt.start    ──┘
+# You closed your agent session and want to pick up where you left off:
+/osddt.continue add-payment-gateway
+# → detects osddt.plan.md exists and reports:
+#   "Planning phase complete. Run: /osddt.tasks"
+/osddt.tasks
+/osddt.implement
+/osddt.done
 ```
 
 | Template           | Description                                                        |

package/dist/commands/setup.d.ts

@@ -1,2 +1,3 @@
 import { Command } from 'commander';
+export declare function resolveNpxCommand(cwd: string): Promise<string>;
 export declare function setupCommand(): Command;

package/dist/commands/update.d.ts

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

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

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

package/dist/index.js

@@ -76,6 +76,29 @@ Use the following logic to determine \`<feature-name>\`:
    - 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.`;
+function getNextStepToSpec(args) {
+    return `## Next Step
+
+- If ${args} was a **human-readable description** (not a branch name):
+
+  Your description will be used as the starting point for the spec. Run:
+
+  \`\`\`
+  /osddt.spec
+  \`\`\`
+
+  > You can append more details if you want the spec to capture additional context.
+
+- If ${args} was a **branch name** (or no arguments were provided):
+
+  Run the following command to write the feature specification:
+
+  \`\`\`
+  /osddt.spec <brief feature description, e.g. "add user authentication with JWT">
+  \`\`\`
+
+  > Add a short description of what you're building so the spec has the right starting point.`;
+}
 const COMMAND_DEFINITIONS = [
     {
         name: 'osddt.continue',
@@ -145,13 +168,7 @@ The research file should include:
 
 ${args}
 
-## Next Step
-
-Run the following command to write the feature specification:
-
-\`\`\`
-/osddt.spec <brief description of the feature or topic researched>
-\`\`\`
+${getNextStepToSpec(args)}
 `,
     },
     {
@@ -191,13 +208,7 @@ Where \`<feature-name>\` is the last segment of the branch name (after the last
 
 ${args}
 
-## Next Step
-
-Run the following command to write the feature specification:
-
-\`\`\`
-/osddt.spec <brief description of the feature being built>
-\`\`\`
+${getNextStepToSpec(args)}
 `,
     },
     {
@@ -205,10 +216,11 @@ Run the following command to write the feature specification:
         description: 'Analyze requirements and write a feature specification',
         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.
-   - If it does not exist, proceed using only the requirements provided in ${args}.
-2. Analyze the requirements provided in ${args}
+1. Gather requirements from all available sources — combine them when multiple sources are present:
+   - **Arguments** (${args}): use as the primary description of the feature, if provided.
+   - **Conversation context**: consider any additional details, clarifications, or constraints discussed in the current session that are not captured in ${args}.
+   - **Research file**: if \`osddt.research.md\` exists in the working directory, read it and incorporate its findings (key insights, constraints, open questions, codebase findings).
+2. Analyze the combined requirements
 3. Identify the core problem being solved
 4. Define the scope, user-facing constraints, and acceptance criteria
 5. Write the specification to \`osddt.spec.md\` in the working directory
@@ -225,6 +237,7 @@ The spec should include:
 - **Open Questions**: Ambiguities about desired behaviour or product decisions to resolve
 
 > If \`osddt.research.md\` was found, add a **Research Summary** section that briefly references the key insights and user-facing constraints it identified.
+> If additional context was gathered from the conversation session, add a **Session Context** section summarising any extra details, decisions, or constraints discussed beyond what was passed as arguments.
 
 ## Arguments
 
@@ -513,7 +526,7 @@ function parseRepoType(raw) {
     }
     return raw;
 }
-async function writeCommandFile(file) {
+async function writeCommandFile$1(file) {
     await fs.ensureDir(path.dirname(file.filePath));
     await fs.writeFile(file.filePath, file.content, 'utf-8');
     console.log(`  Created: ${file.filePath}`);
@@ -536,7 +549,7 @@ async function runSetup(cwd, rawAgents, rawRepoType) {
         const claudeFiles = getClaudeTemplates(cwd, npxCommand);
         console.log('Claude Code commands (.claude/commands/):');
         for (const file of claudeFiles) {
-            await writeCommandFile(file);
+            await writeCommandFile$1(file);
         }
         console.log('');
     }
@@ -544,11 +557,11 @@ async function runSetup(cwd, rawAgents, rawRepoType) {
         const geminiFiles = getGeminiTemplates(cwd, npxCommand);
         console.log('Gemini CLI commands (.gemini/commands/):');
         for (const file of geminiFiles) {
-            await writeCommandFile(file);
+            await writeCommandFile$1(file);
         }
         console.log('');
     }
-    await writeConfig(cwd, { repoType });
+    await writeConfig(cwd, { repoType, agents });
     console.log('\nSetup complete!');
     console.log('Commands created: osddt.spec, osddt.plan, osddt.tasks, osddt.implement');
 }
@@ -623,6 +636,79 @@ function doneCommand() {
     return cmd;
 }
 
+const AGENT_CONFIGS = {
+    claude: { dir: ['.claude', 'commands'], filePattern: /^osddt\..+\.md$/ },
+    gemini: { dir: ['.gemini', 'commands'], filePattern: /^osddt\..+\.toml$/ },
+};
+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));
+}
+async function inferAgents(cwd) {
+    const detected = [];
+    for (const [agent, config] of Object.entries(AGENT_CONFIGS)) {
+        const dir = path.join(cwd, ...config.dir);
+        if (await hasOsddtCommandFile(dir, config.filePattern)) {
+            detected.push(agent);
+        }
+    }
+    return detected;
+}
+async function writeCommandFile(file) {
+    await fs.writeFile(file.filePath, file.content, 'utf-8');
+    console.log(`  Updated: ${file.filePath}`);
+}
+async function runUpdate(cwd) {
+    const configPath = path.join(cwd, '.osddtrc');
+    if (!(await fs.pathExists(configPath))) {
+        console.error('Error: .osddtrc not found. Run `osddt setup` first.');
+        process.exit(1);
+    }
+    const config = await fs.readJson(configPath);
+    const npxCommand = await resolveNpxCommand(cwd);
+    let agents = config.agents;
+    if (!agents || agents.length === 0) {
+        agents = await inferAgents(cwd);
+        if (agents.length === 0) {
+            console.error('Error: No agent command directories found. Run `osddt setup` first.');
+            process.exit(1);
+        }
+        await fs.writeJson(configPath, { ...config, agents }, { spaces: 2 });
+        console.log(`Inferred agents from command directories and saved to .osddtrc: ${agents.join(', ')}\n`);
+    }
+    console.log('Updating OSDDT command files...\n');
+    if (agents.includes('claude')) {
+        const claudeFiles = getClaudeTemplates(cwd, npxCommand);
+        console.log('Claude Code commands (.claude/commands/):');
+        for (const file of claudeFiles) {
+            await writeCommandFile(file);
+        }
+        console.log('');
+    }
+    if (agents.includes('gemini')) {
+        const geminiFiles = getGeminiTemplates(cwd, npxCommand);
+        console.log('Gemini CLI commands (.gemini/commands/):');
+        for (const file of geminiFiles) {
+            await writeCommandFile(file);
+        }
+        console.log('');
+    }
+    console.log('Update complete!');
+}
+function updateCommand() {
+    const cmd = new Command('update');
+    cmd
+        .description('Regenerate agent command files from the existing .osddtrc configuration')
+        .option('-d, --dir <directory>', 'target directory', process.cwd())
+        .action(async (options) => {
+        const targetDir = path.resolve(options.dir);
+        await runUpdate(targetDir);
+    });
+    return cmd;
+}
+
 const program = new Command();
 program
     .name('osddt')
@@ -631,4 +717,5 @@ program
 program.addCommand(setupCommand());
 program.addCommand(metaInfoCommand());
 program.addCommand(doneCommand());
+program.addCommand(updateCommand());
 program.parse(process.argv);

package/dist/templates/shared.d.ts

@@ -2,6 +2,7 @@ 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 declare function getNextStepToSpec(args: ArgPlaceholder): string;
 export type ArgPlaceholder = '$ARGUMENTS' | '{{args}}';
 export interface CommandDefinitionContext {
     args: ArgPlaceholder;

package/package.json

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