@dezkareid/osddt 1.8.0 → 1.10.0

package/AGENTS.md

@@ -184,17 +184,19 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 | `osddt.plan`       | Create a technical implementation plan from a specification        |
 | `osddt.tasks`      | Generate actionable tasks from an implementation plan              |
 | `osddt.implement`  | Execute tasks from the task list one by one                        |
+| `osddt.fast`       | Bootstrap all planning artifacts (spec, plan, tasks) in one shot   |
 | `osddt.done`       | Resolve project path, verify tasks, and move the feature to done   |
 
 #### Template Workflow
 
-`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.
+`osddt.research`, `osddt.start`, and `osddt.fast` are **entry points**. `osddt.research` and `osddt.start` are peer entry points for the step-by-step workflow. `osddt.fast` is an accelerated entry point that skips manual steps and generates all planning artifacts in a single invocation. 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.
+   - **`osddt.fast <description>`** — create the branch, spec, plan, and task list in one shot without any manual steps.
 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.
@@ -202,6 +204,8 @@ Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent
 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/`.
 
+> **Fast mode:** Steps 1–5 can be replaced by a single `osddt.fast <description>` invocation. The agent derives all decisions automatically and records them in an `## Assumptions` section of the plan for review before implementing.
+
 > **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:**

package/README.md

@@ -44,6 +44,7 @@ flowchart LR
     subgraph entry[Entry points]
         research([osddt.research])
         start([osddt.start])
+        fast([osddt.fast])
     end
 
     spec([osddt.spec])
@@ -55,6 +56,7 @@ flowchart LR
 
     research --> spec
     start --> spec
+    fast --> implement
     spec --> clarify
     clarify --> plan
     spec --> plan
@@ -93,6 +95,17 @@ flowchart LR
 /osddt.done
 ```
 
+#### Fast mode (spec + plan + tasks in one shot)
+
+```
+/osddt.fast add payment gateway
+# → creates branch, writes spec, plan (with Assumptions), and task list automatically
+/osddt.implement
+/osddt.done
+```
+
+> Review the `## Assumptions` section of `osddt.plan.md` before implementing. Run `/osddt.clarify` if any Open Questions in the spec need resolving first.
+
 #### Resuming after closing a session
 
 ```
@@ -115,6 +128,7 @@ flowchart LR
 | `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/context.d.ts

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

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

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

package/dist/index.js

@@ -99,6 +99,19 @@ function getNextStepToSpec(args) {
 
   > Add a short description of what you're building so the spec has the right starting point.`;
 }
+function getCustomContextStep(npxCommand, commandName) {
+    return `## Custom Context
+
+Run the following command and, if it returns content, use it as additional context before proceeding:
+
+\`\`\`
+${npxCommand} context ${commandName}
+\`\`\`
+
+If the command returns no output, skip this section and continue.
+
+`;
+}
 const COMMAND_DEFINITIONS = [
     {
         name: 'osddt.continue',
@@ -122,7 +135,7 @@ Report which file was found, which phase that corresponds to, and the exact comm
 
 > **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
+${getCustomContextStep(npxCommand, 'continue')}## Arguments
 
 ${args}
 `,
@@ -164,7 +177,7 @@ The research file should include:
 - **Constraints & Risks**: Known limitations or risks uncovered during research
 - **Open Questions**: Ambiguities that the specification phase should resolve
 
-## Arguments
+${getCustomContextStep(npxCommand, 'research')}## Arguments
 
 ${args}
 
@@ -204,7 +217,7 @@ Where \`<feature-name>\` is the last segment of the branch name (after the last
 
 5. Report the branch name and working directory that were created or resumed.
 
-## Arguments
+${getCustomContextStep(npxCommand, 'start')}## Arguments
 
 ${args}
 
@@ -214,7 +227,7 @@ ${getNextStepToSpec(args)}
     {
         name: 'osddt.spec',
         description: 'Analyze requirements and write a feature specification',
-        body: ({ args }) => `## Instructions
+        body: ({ args, npxCommand }) => `## Instructions
 
 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.
@@ -242,7 +255,7 @@ The spec should include:
 > 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
+${getCustomContextStep(npxCommand, 'spec')}## Arguments
 
 ${args}
 
@@ -258,7 +271,7 @@ Run the following command to create the implementation plan:
     {
         name: 'osddt.clarify',
         description: 'Resolve open questions in the spec and record decisions',
-        body: () => `## Instructions
+        body: ({ npxCommand }) => `## 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.
@@ -287,12 +300,13 @@ Run the following command to create the implementation plan:
 \`\`\`
 
 > Note: if \`osddt.plan.md\` already exists, the plan should be regenerated to incorporate the decisions.
-`,
+
+${getCustomContextStep(npxCommand, 'clarify')}`,
     },
     {
         name: 'osddt.plan',
         description: 'Create a technical implementation plan from a specification',
-        body: ({ args }) => `${RESOLVE_FEATURE_NAME}
+        body: ({ args, npxCommand }) => `${RESOLVE_FEATURE_NAME}
 
 ## Instructions
 
@@ -323,7 +337,7 @@ The plan should include:
 - **Risks & Mitigations**: Known risks and how to address them
 - **Out of Scope**: Explicitly what will not be built
 
-## Arguments
+${getCustomContextStep(npxCommand, 'plan')}## Arguments
 
 ${args}
 
@@ -339,7 +353,7 @@ Run the following command to generate the task list:
     {
         name: 'osddt.tasks',
         description: 'Generate actionable tasks from an implementation plan',
-        body: () => `${RESOLVE_FEATURE_NAME}
+        body: ({ npxCommand }) => `${RESOLVE_FEATURE_NAME}
 
 ## Instructions
 
@@ -361,7 +375,7 @@ The task list should include:
 - **Dependencies**: Note which tasks must complete before others
 - **Definition of Done**: Clear completion criteria per phase
 
-## Next Step
+${getCustomContextStep(npxCommand, 'tasks')}## Next Step
 
 Run the following command to start implementing tasks:
 
@@ -373,7 +387,7 @@ Run the following command to start implementing tasks:
     {
         name: 'osddt.implement',
         description: 'Execute tasks from the task list one by one',
-        body: () => `## Instructions
+        body: ({ npxCommand }) => `## 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\` first.
@@ -390,13 +404,95 @@ Run the following command to start implementing tasks:
 - Write tests for new functionality when applicable
 - Ask for clarification if requirements are ambiguous
 
-## Next Step
+${getCustomContextStep(npxCommand, 'implement')}## Next Step
 
 Once all tasks are checked off, run the following command to mark the feature as done:
 
 \`\`\`
 /osddt.done
 \`\`\`
+`,
+    },
+    {
+        name: 'osddt.fast',
+        description: 'Bootstrap all planning artifacts (spec, plan, tasks) from a single description',
+        body: ({ args, npxCommand }) => `${getRepoPreamble(npxCommand)}## Instructions
+
+The argument provided is: ${args}
+
+This command runs the full spec-driven setup sequence in one shot — branch creation, spec, plan, and task list — without pausing for user input. Follow each step below in order without asking the user for clarification or confirmation between steps.
+
+### Step 1 — Derive branch and feature name
+
+Determine the branch name from ${args}:
+
+1. If ${args} looks like a branch name (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 \`/\`):
+
+${FEATURE_NAME_RULES}
+
+### Step 2 — Create branch and working directory
+
+3. Check whether the branch already exists locally or remotely:
+   - If it **does not exist**, create and switch to it:
+     \`\`\`
+     git checkout -b <branch-name>
+     \`\`\`
+   - If it **already exists**, warn the user and ask whether to:
+     - **Resume** — switch to the existing branch (\`git checkout <branch-name>\`) and continue
+     - **Abort** — stop and do nothing
+
+4. ${WORKING_DIR_STEP}
+
+Where \`<feature-name>\` is the last segment of the branch name (after the last \`/\`, or the full branch name if no \`/\` is present).
+
+### Step 3 — Generate spec
+
+Write \`osddt.spec.md\` to the working directory. Base it entirely on ${args} and any codebase context you can gather. Do **not** ask the user any questions. If there are ambiguities, record them in an **Open Questions** section and continue.
+
+The spec must include:
+- **Overview**: What the feature is and why it is needed
+- **Requirements**: Functional requirements expressed as user-observable behaviours
+- **Scope**: In scope and out of scope in product terms
+- **Acceptance Criteria**: Clear, testable criteria from a user or business perspective
+- **Open Questions** (if any): Ambiguities to resolve later — do not block on these
+
+### Step 4 — Generate plan
+
+Write \`osddt.plan.md\` to the working directory. Derive all technical decisions from the spec and codebase inspection. Do **not** ask the user for input.
+
+The plan must include:
+- **Assumptions**: Document every technical decision made automatically (e.g. library choices, architecture patterns) so the user can review them before implementing
+- **Architecture Overview**: High-level design decisions
+- **Implementation Phases**: Ordered phases with goals
+- **Technical Dependencies**: Libraries, APIs, services needed
+- **Risks & Mitigations**: Known risks and mitigations
+- **Out of Scope**: What will not be built
+
+### Step 5 — Generate task list
+
+Write \`osddt.tasks.md\` to the working directory based on \`osddt.plan.md\`.
+
+The task list must include:
+- A checklist of tasks grouped by phase: \`- [ ] [S/M/L] Description\`
+- Dependencies between tasks noted where relevant
+- A Definition of Done per phase
+
+### Step 6 — Report
+
+Display the full contents of \`osddt.tasks.md\` to the user. Then prompt them to run:
+
+\`\`\`
+/osddt.implement
+\`\`\`
+
+> You can optionally run \`/osddt.clarify\` before implementing to resolve any Open Questions recorded in the spec.
+
+${getCustomContextStep(npxCommand, 'fast')}## Arguments
+
+${args}
 `,
     },
     {
@@ -415,7 +511,8 @@ ${npxCommand} done <feature-name> --dir <project-path>
    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
-`,
+
+${getCustomContextStep(npxCommand, 'done')}`,
     },
 ];
 
@@ -712,6 +809,64 @@ function updateCommand() {
     return cmd;
 }
 
+const CONTEXT_DIR = 'osddt-context';
+function stubContent(name) {
+    return `<!-- osddt context: ${name}
+     The content of this file will be shown to the agent under the "## Custom Context" section
+     when the osddt.${name} command is invoked. Add your project-specific instructions below. -->
+`;
+}
+async function runRead(name, cwd) {
+    const filePath = path.join(cwd, CONTEXT_DIR, `${name}.md`);
+    let content;
+    try {
+        content = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return;
+        }
+        throw err;
+    }
+    process.stdout.write(content);
+}
+async function runInit(cwd) {
+    const contextDir = path.join(cwd, CONTEXT_DIR);
+    await fs.ensureDir(contextDir);
+    for (const cmd of COMMAND_DEFINITIONS) {
+        const name = cmd.name.replace(/^osddt\./, '');
+        const filePath = path.join(contextDir, `${name}.md`);
+        if (await fs.pathExists(filePath)) {
+            console.log(`  Skipped (exists): ${CONTEXT_DIR}/${name}.md`);
+        }
+        else {
+            await fs.writeFile(filePath, stubContent(name), 'utf-8');
+            console.log(`  Created: ${CONTEXT_DIR}/${name}.md`);
+        }
+    }
+}
+function contextCommand() {
+    const cmd = new Command('context');
+    cmd
+        .description('Output a custom context file or scaffold context stubs')
+        .argument('[name]', 'command name to read context for (e.g. plan, spec)')
+        .option('-d, --dir <directory>', 'project directory', process.cwd())
+        .option('--init', 'scaffold osddt-context/ with stub files for all commands')
+        .action(async (name, options) => {
+        const targetDir = path.resolve(options.dir);
+        if (options.init) {
+            await runInit(targetDir);
+        }
+        else if (name) {
+            await runRead(name, targetDir);
+        }
+        else {
+            cmd.help();
+        }
+    });
+    return cmd;
+}
+
 const program = new Command();
 program
     .name('osddt')
@@ -721,4 +876,5 @@ program.addCommand(setupCommand());
 program.addCommand(metaInfoCommand());
 program.addCommand(doneCommand());
 program.addCommand(updateCommand());
+program.addCommand(contextCommand());
 program.parse(process.argv);

package/dist/templates/shared.d.ts

@@ -3,6 +3,7 @@ export declare const FEATURE_NAME_RULES = "### Feature Name Constraints\n\nWhen
 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 declare function getCustomContextStep(npxCommand: string, commandName: string): string;
 export type ArgPlaceholder = '$ARGUMENTS' | '{{args}}';
 export interface CommandDefinitionContext {
     args: ArgPlaceholder;

package/package.json

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