@dezkareid/osddt 1.1.0 → 1.3.0

package/AGENTS.md

@@ -0,0 +1,249 @@
+# 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 (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>
+│   ├── 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 setup: reads `--agents`/`--repo-type` flags when provided (non-interactive), otherwise 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 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>`                               | Move `working-on/<feature>` to `done/<feature>`               |
+
+#### `osddt setup` options
+
+| Flag | Values | Description |
+| ---- | ------ | ----------- |
+| `--agents <list>` | `claude`, `gemini` (comma-separated) | Skip the agents prompt and use the provided value(s) |
+| `--repo-type <type>` | `single`, `monorepo` | Skip the repo type prompt and use the provided value |
+| `-d, --dir <directory>` | any path | Target directory (defaults to current working directory) |
+
+Both flags are optional. Providing neither runs the fully interactive mode. Providing both skips all prompts.
+
+### 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

@@ -3,11 +3,30 @@ Other spec driven development tool but for monorepo
 
 ## CLI Commands
 
-| 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                                                              | 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>`                               | Move `working-on/<feature>` to `done/<feature>`               |
+
+### `osddt setup` options
+
+| Flag | Values | Description |
+| ---- | ------ | ----------- |
+| `--agents <list>` | `claude`, `gemini` (comma-separated) | Skip the agents prompt and use the provided value(s) |
+| `--repo-type <type>` | `single`, `monorepo` | Skip the repo type prompt and use the provided value |
+| `-d, --dir <directory>` | any path | Target directory (defaults to current working directory) |
+
+Both flags are optional. Providing neither runs the fully interactive mode. Providing both skips all prompts.
+
+```bash
+# Interactive (default)
+npx @dezkareid/osddt setup
+
+# Non-interactive (CI-friendly)
+npx @dezkareid/osddt setup --agents claude,gemini --repo-type single
+```
 
 ## Command Templates
 
@@ -38,3 +57,25 @@ Generated files are placed in:
 
 - `.claude/commands/osddt.<name>.md` (Claude Code)
 - `.gemini/commands/osddt.<name>.toml` (Gemini CLI)
+
+## Development
+
+### Running Tests
+
+```bash
+# Run the full test suite once
+pnpm test
+
+# Run in watch mode during development
+pnpm run test:watch
+```
+
+### Local Setup
+
+After making changes to the source, rebuild and regenerate the agent command files in the repository:
+
+```bash
+pnpm run setup-local
+```
+
+This runs `pnpm run build` followed by `npx osddt setup`, prompting you to select which agents to configure and the repo type.

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

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

package/dist/index.js

@@ -224,10 +224,16 @@ Run the following command to create the implementation plan:
         description: 'Create a technical implementation plan from a specification',
         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
+1. 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
+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
 
 ## Plan Format
 
@@ -256,10 +262,16 @@ Run the following command to generate the task list:
         description: 'Generate actionable tasks from an implementation plan',
         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
+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
+4. Estimate complexity (S/M/L) for each task
+5. Write the task list to \`osddt.tasks.md\` in the working directory
 
 ## Tasks Format
 
@@ -287,11 +299,13 @@ 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.
+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
 
@@ -410,6 +424,28 @@ async function askAgents() {
     });
 }
 
+const VALID_AGENTS = ['claude', 'gemini'];
+const VALID_REPO_TYPES = ['single', 'monorepo'];
+function parseAgents(raw) {
+    const values = raw.split(',').map((s) => s.trim());
+    if (values.length === 0) {
+        console.error('Error: --agents requires at least one value.');
+        process.exit(1);
+    }
+    const invalid = values.filter((v) => !VALID_AGENTS.includes(v));
+    if (invalid.length > 0) {
+        console.error(`Error: Invalid agent(s): ${invalid.join(', ')}. Valid values: ${VALID_AGENTS.join(', ')}.`);
+        process.exit(1);
+    }
+    return values;
+}
+function parseRepoType(raw) {
+    if (!VALID_REPO_TYPES.includes(raw)) {
+        console.error(`Error: Invalid repo type: "${raw}". Valid values: ${VALID_REPO_TYPES.join(', ')}.`);
+        process.exit(1);
+    }
+    return raw;
+}
 async function writeCommandFile(file) {
     await fs.ensureDir(path.dirname(file.filePath));
     await fs.writeFile(file.filePath, file.content, 'utf-8');
@@ -420,11 +456,13 @@ async function writeConfig(cwd, config) {
     await fs.writeJson(configPath, config, { spaces: 2 });
     console.log(`\nSaved config: ${configPath}`);
 }
-async function runSetup(cwd) {
-    const agents = await askAgents();
-    console.log('');
-    const repoType = await askRepoType();
-    console.log('');
+async function runSetup(cwd, rawAgents, rawRepoType) {
+    const agents = rawAgents !== undefined ? parseAgents(rawAgents) : await askAgents();
+    if (rawAgents === undefined)
+        console.log('');
+    const repoType = rawRepoType !== undefined ? parseRepoType(rawRepoType) : await askRepoType();
+    if (rawRepoType === undefined)
+        console.log('');
     console.log('Setting up OSDDT command files...\n');
     if (agents.includes('claude')) {
         const claudeFiles = getClaudeTemplates(cwd);
@@ -451,9 +489,11 @@ function setupCommand() {
     cmd
         .description('Create OSDDT command files for Claude and Gemini CLI agents')
         .option('-d, --dir <directory>', 'target directory', process.cwd())
+        .option('--agents <list>', 'comma-separated agents to set up (claude, gemini)')
+        .option('--repo-type <type>', 'repository type (single, monorepo)')
         .action(async (options) => {
         const targetDir = path.resolve(options.dir);
-        await runSetup(targetDir);
+        await runSetup(targetDir, options.agents, options.repoType);
     });
     return cmd;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/osddt",
-  "version": "1.1.0",
+  "version": "1.3.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",
@@ -52,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 --agents claude --repo-type single"
   }
 }