@dezkareid/osddt 1.4.0 → 1.6.0

package/AGENTS.md

@@ -183,17 +183,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.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
 ```
-osddt.continue ──────────────────────────────────────────────────────────────────────────────────────┐
-                                                                                                      │
-osddt.research ──┐                                                                                    │
-                 ├──► osddt.spec → [osddt.clarify] → osddt.plan → osddt.tasks → osddt.implement → osddt.done ◄─┘
-osddt.start    ──┘
+
+##### 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
 ```
 
-- 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 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 +271,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,15 +282,17 @@ 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.
   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).
+  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.done behaviour

package/README.md

@@ -32,14 +32,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/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
 
@@ -257,11 +270,12 @@ Run the following command to create the implementation plan:
 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\`:
+5. Update \`osddt.spec.md\`:
+   - Remove each answered question from the **Open Questions** section.
+   - If the **Open Questions** section becomes empty after removal, remove the section heading as well.
    - 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:
 

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.4.0",
+  "version": "1.6.0",
   "description": "Package for Spec-Driven Development workflow",
   "keywords": [
     "spec-driven",