@dezkareid/osddt 1.0.0 → 1.2.0

package/AGENTS.md

@@ -0,0 +1,238 @@
+# Agent Instructions: Other Spec-Driven Development Tooling (OSDDT)
+
+This project is a command line utility for spec-driven development. It is intended to be used in monorepos or single package repos.
+
+## Overview
+
+### Agents Support
+Each agent has its own conventions for:
+
+- **Command file formats** (Markdown, TOML, etc.)
+- **Directory structures** (`.claude/commands/`, `.windsurf/workflows/`, etc.)
+- **Command invocation patterns** (slash commands, CLI tools, etc.)
+- **Argument passing conventions** (`$ARGUMENTS`, `{{args}}`, etc.)
+
+| Agent                      | Directory              | Format   | CLI Tool        | Description                 |
+| -------------------------- | ---------------------- | -------- | --------------- | --------------------------- |
+| **Claude Code**            | `.claude/commands/`    | Markdown | `claude`        | Anthropic's Claude Code CLI |
+| **Gemini CLI**             | `.gemini/commands/`    | TOML     | `gemini`        | Google's Gemini CLI         |
+
+
+### Command File Formats
+
+#### Markdown Format
+
+Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer, Amp, SHAI, IBM Bob
+
+**Standard format:**
+
+```markdown
+---
+description: "Command description"
+---
+
+Command content with {SCRIPT} and $ARGUMENTS placeholders.
+```
+
+#### TOML Format
+
+Used by: Gemini
+
+```toml
+description = "Command description"
+
+prompt = """
+Command content with {SCRIPT} and {{args}} placeholders.
+"""
+```
+
+### Directory Conventions
+
+- **CLI agents**: Usually `.<agent-name>/commands/`
+
+### Argument Patterns
+
+Different agents use different argument placeholders:
+
+- **Markdown/prompt-based**: `$ARGUMENTS`
+- **TOML-based**: `{{args}}`
+
+## Development
+
+### Commit Rules
+
+Always use Conventional Commits format for commit messages.
+
+Never commit directly to `main` or `master`. If the current branch is one of them, propose creating a new branch before committing.
+
+### Critical Dependency Versions
+
+The following versions are established across the project's packages and should be respected when adding new dependencies or troubleshooting.
+
+Always prefer use exact versions for dependencies. Do not use `^` or `~`.
+
+#### Core Languages & Runtimes
+- **TypeScript**: `5.9.3`
+
+#### Build & Bundling Tools
+- **Rollup**: `4.56.0`
+
+#### Testing Frameworks
+- **Vitest**: `4.0.18`
+
+#### Linting & Formatting
+- **ESLint**: `9.39.2`
+- **Prettier**: `3.8.1`
+
+#### Type Definitions
+- **@types/node**: `25.0.10`
+- **@types/fs-extra**: `11.0.4`
+
+#### Key Libraries
+- **Commander**: `12.0.0` (for CLI tools)
+- **fs-extra**: `11.2.0`
+- **globby**: `14.0.1`
+
+### Project Structure & Conventions
+- **Package Manager**: `pnpm` is the required package manager.
+
+### Codebase Structure
+
+```
+osddt/
+├── src/
+│   ├── index.ts                   # CLI entry point — wires Commander program and registers all commands
+│   ├── commands/
+│   │   ├── setup.ts               # `osddt setup` — prompts for agents & repo type, 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>
+│   ├── 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)
+│   │   └── gemini.ts              # Formats COMMAND_DEFINITIONS as TOML (.gemini/commands/osddt.<name>.toml)
+│   └── utils/
+│       └── prompt.ts              # Inquirer prompts: askAgents() (checkbox) and askRepoType() (select)
+├── dist/                          # Compiled output (single ESM bundle, gitignored)
+├── rollup.config.js               # Bundles src/index.ts → dist/index.js (ESM, shebang injected)
+├── 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")
+├── AGENTS.md / CLAUDE.md / GEMINI.md  # Agent-specific instructions (kept in sync)
+└── README.md                      # Public-facing documentation
+```
+
+#### Key relationships
+
+- **`shared.ts` is the single source of truth** for all command template content. Both `claude.ts` and `gemini.ts` import `COMMAND_DEFINITIONS` from it and only differ in file format (Markdown vs TOML) and argument placeholder (`$ARGUMENTS` vs `{{args}}`).
+- **`setup.ts`** orchestrates the interactive setup: calls `askAgents()` → `askRepoType()` → writes selected agent files → writes `.osddtrc`.
+- **`meta-info.ts`** is referenced inside the generated templates so agents can fetch live branch/date at invocation time (not baked in at build time).
+- **Test files** (`.spec.ts`) live next to the source file they cover. Template tests are pure (no mocks); command tests mock `fs-extra` and `child_process`.
+
+### CLI Commands
+
+All commands available via `npx @dezkareid/osddt <command>`:
+
+| Command                        | Description                                                   |
+| ------------------------------ | ------------------------------------------------------------- |
+| `@dezkareid/osddt setup`                  | Generate agent command files for Claude and Gemini            |
+| `@dezkareid/osddt meta-info`              | Output current branch and date as JSON                        |
+| `@dezkareid/osddt done <feature-name>`    | Move `working-on/<feature>` to `done/<feature>`               |
+
+### Command Templates
+
+Templates are generated by `npx @dezkareid/osddt setup` and placed in each agent's commands directory. Each template corresponds to a step in the spec-driven workflow.
+
+| Template           | Description                                                        |
+| ------------------ | ------------------------------------------------------------------ |
+| `osddt.continue`   | Detect the current workflow phase and prompt the next command      |
+| `osddt.research`   | Research a topic and write a research file to inform the spec      |
+| `osddt.start`      | Start a new feature by creating a branch and working-on folder     |
+| `osddt.spec`       | Analyze requirements and write a feature specification             |
+| `osddt.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.done`       | Mark a feature as done and move it from working-on to done         |
+
+#### 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.continue ──────────────────────────────────────────────────────────────────────────────┐
+                                                                                              │
+osddt.research ──┐                                                                            │
+                 ├──► osddt.spec → 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.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.
+
+#### Generated File Locations
+
+| Agent       | Directory           | File pattern               |
+| ----------- | ------------------- | -------------------------- |
+| Claude Code | `.claude/commands/` | `osddt.<name>.md`          |
+| Gemini CLI  | `.gemini/commands/` | `osddt.<name>.toml`        |
+
+#### osddt.continue behaviour
+
+- **Input**: A feature name or branch name to locate the working directory.
+- **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.
+
+#### osddt.start behaviour
+
+- **Input**: Either a human-readable feature description (e.g. `"Add user authentication"`) or an existing branch name (e.g. `feat/add-user-auth`).
+- **Branch name resolution**: input is used as-is if it looks like a branch name; otherwise a name is derived (lowercased, hyphens, prefixed with `feat/`), subject to the 30-character feature name limit.
+- **Actions performed by the agent**:
+  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.
+
+#### osddt.research behaviour
+
+- **Input**: Either a human-readable topic description or a branch/feature name.
+- **Actions performed by the agent**:
+  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`.
+
+### Template Data Convention
+
+When a template needs dynamic information (e.g. current branch, date, repo config), **do not pass it as a build-time argument**. Instead:
+
+1. Create an `npx @dezkareid/osddt <command>` that outputs the data (preferably as JSON).
+2. Reference that command in the template body, instructing the agent to run it at invocation time.
+
+This keeps generated files deterministic and ensures agents always get live values.
+
+## Testing
+
+### Approach
+
+Tests are written using **Vitest** and follow **BDD (Behaviour-Driven Development)** conventions:
+
+- Test files live next to the source files they cover, using the `.spec.ts` suffix.
+- Tests are structured with `describe` blocks that express the context ("given …") and `it` blocks that express the expected behaviour ("should …").
+- Side effects (filesystem, child processes, `process.exit`) are isolated with `vi.mock` / `vi.spyOn` so tests remain fast and deterministic.
+- Pure functions (template generators) are tested without mocks.
+
+### Running Tests
+
+```bash
+# Run the full test suite once
+pnpm test
+
+# Run in watch mode during development
+pnpm run test:watch
+```
+
+## Documentation
+
+When a command in templates or npx commands are added/updated/removed/renamed/deprecated, ask to update the AGENTS.md and README.md files.

package/README.md

@@ -5,13 +5,13 @@ Other spec driven development tool but for monorepo
 
 | Command                        | Description                                                   |
 | ------------------------------ | ------------------------------------------------------------- |
-| `osddt setup`                  | Generate agent command files for Claude and Gemini            |
-| `osddt meta-info`              | Output current branch and date as JSON                        |
-| `osddt done <feature-name>`    | Move `working-on/<feature>` to `done/<feature>`               |
+| `@dezkareid/osddt setup`                  | Generate agent command files for Claude and Gemini            |
+| `@dezkareid/osddt meta-info`              | Output current branch and date as JSON                        |
+| `@dezkareid/osddt done <feature-name>`    | Move `working-on/<feature>` to `done/<feature>`               |
 
 ## Command Templates
 
-Run `osddt setup` once to generate the agent command files.
+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.
 

package/dist/index.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import path from 'path';
 import fs from 'fs-extra';
 import select from '@inquirer/select';
+import checkbox from '@inquirer/checkbox';
 import { execSync } from 'child_process';
 
 const REPO_PREAMBLE = `## Context
@@ -10,7 +11,7 @@ const REPO_PREAMBLE = `## Context
 Before proceeding, run the following command and parse the JSON output to get the current branch and date:
 
 \`\`\`
-npx osddt meta-info
+npx @dezkareid/osddt meta-info
 \`\`\`
 
 ## Repository Configuration
@@ -224,9 +225,15 @@ Run the following command to create the implementation plan:
         body: (args) => `## Instructions
 
 1. Read \`osddt.spec.md\` from the working directory
-2. Break down the implementation into logical phases and steps
-3. Identify technical decisions, dependencies, and risks
-4. Write the plan to \`osddt.plan.md\` in the working directory
+2. Check whether \`osddt.plan.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 plan from scratch
+     - **Update** — read the existing file and apply targeted changes based on ${args}
+     - **Do nothing** — stop here and leave the file as-is
+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
 
 ## Plan Format
 
@@ -256,9 +263,15 @@ Run the following command to generate the task list:
         body: (args) => `## Instructions
 
 1. Read \`osddt.plan.md\` from the working directory
-2. Break each phase into discrete, executable tasks
-3. Estimate complexity (S/M/L) for each task
-4. Write the task list to \`osddt.tasks.md\` in the working directory
+2. 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
+3. Break each phase into discrete, executable tasks
+4. Estimate complexity (S/M/L) for each task
+5. Write the task list to \`osddt.tasks.md\` in the working directory
 
 ## Tasks Format
 
@@ -286,11 +299,17 @@ Run the following command to start implementing tasks:
         description: 'Execute tasks from the task list one by one',
         body: (args) => `## Instructions
 
-1. Read \`osddt.tasks.md\` from the working directory
-2. Find the next unchecked task (\`- [ ]\`)
-3. Implement that task following the spec (\`osddt.spec.md\`) and plan (\`osddt.plan.md\`) in the working directory
-4. Mark the task as complete (\`- [x]\`) in \`osddt.tasks.md\`
-5. Report what was done and any issues encountered
+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 **already exists**, ask the user whether to:
+     - **Continue** — find the next unchecked task and implement it (default)
+     - **Update tasks** — edit \`osddt.tasks.md\` before implementing (e.g. to add, remove, or reorder tasks)
+     - **Do nothing** — stop here without making any changes
+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
+5. Mark the task as complete (\`- [x]\`) in \`osddt.tasks.md\`
+6. Report what was done and any issues encountered
 
 ## Guidelines
 
@@ -321,7 +340,7 @@ Once all tasks are checked off, run the following command to mark the feature as
 2. Run the following command to move the feature folder from \`working-on\` to \`done\`:
 
 \`\`\`
-npx osddt done ${args}
+npx @dezkareid/osddt done ${args}
 \`\`\`
 
    The command will automatically prefix the destination folder name with today's date in \`YYYY-MM-DD\` format.
@@ -385,6 +404,29 @@ async function askRepoType() {
         ],
     });
 }
+async function askAgents() {
+    return checkbox({
+        message: 'Which AI assistant tools do you want to set up?',
+        choices: [
+            {
+                name: 'Claude Code',
+                value: 'claude',
+                checked: true,
+            },
+            {
+                name: 'Gemini CLI',
+                value: 'gemini',
+                checked: true,
+            },
+        ],
+        validate(choices) {
+            if (choices.length === 0) {
+                return 'You must select at least one agent.';
+            }
+            return true;
+        },
+    });
+}
 
 async function writeCommandFile(file) {
     await fs.ensureDir(path.dirname(file.filePath));
@@ -397,18 +439,26 @@ async function writeConfig(cwd, config) {
     console.log(`\nSaved config: ${configPath}`);
 }
 async function runSetup(cwd) {
+    const agents = await askAgents();
+    console.log('');
     const repoType = await askRepoType();
     console.log('');
     console.log('Setting up OSDDT command files...\n');
-    const claudeFiles = getClaudeTemplates(cwd);
-    const geminiFiles = getGeminiTemplates(cwd);
-    console.log('Claude Code commands (.claude/commands/):');
-    for (const file of claudeFiles) {
-        await writeCommandFile(file);
+    if (agents.includes('claude')) {
+        const claudeFiles = getClaudeTemplates(cwd);
+        console.log('Claude Code commands (.claude/commands/):');
+        for (const file of claudeFiles) {
+            await writeCommandFile(file);
+        }
+        console.log('');
     }
-    console.log('\nGemini CLI commands (.gemini/commands/):');
-    for (const file of geminiFiles) {
-        await writeCommandFile(file);
+    if (agents.includes('gemini')) {
+        const geminiFiles = getGeminiTemplates(cwd);
+        console.log('Gemini CLI commands (.gemini/commands/):');
+        for (const file of geminiFiles) {
+            await writeCommandFile(file);
+        }
+        console.log('');
     }
     await writeConfig(cwd, { repoType });
     console.log('\nSetup complete!');

package/dist/templates/shared.d.ts

@@ -1,4 +1,4 @@
-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 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 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 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 type ArgPlaceholder = '$ARGUMENTS' | '{{args}}';

package/dist/utils/prompt.d.ts

@@ -1,2 +1,4 @@
 export type RepoType = 'monorepo' | 'single';
+export type AgentType = 'claude' | 'gemini';
 export declare function askRepoType(): Promise<RepoType>;
+export declare function askAgents(): Promise<AgentType[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/osddt",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Package for Spec-Driven Development workflow",
   "keywords": [
     "spec-driven",
@@ -8,7 +8,10 @@
   ],
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    "CLAUDE.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -30,6 +33,7 @@
   },
   "main": "./dist/index.js",
   "dependencies": {
+    "@inquirer/checkbox": "5.0.7",
     "@inquirer/select": "5.0.7",
     "commander": "12.0.0",
     "fs-extra": "11.2.0",
@@ -51,6 +55,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src",
-    "format": "prettier --write src"
+    "format": "prettier --write src",
+    "setup-local": "pnpm run build && npx osddt setup"
   }
 }