docspec 0.2.0 → 0.4.0

package/README.md

@@ -1,22 +1,16 @@
 # docspec
 
-Docspec is a specification format and toolchain for documentation that is maintained by agents.
+Docspec is a specification format and toolchain for documentation that is maintained by agents. **Docspec does not run an LLM**—it produces prompt output that you feed into your own LLM CLI (e.g. Claude, Codex).
 
-## The Docspec Format
+Docspec files live under **`.docspec/`**. For a markdown file `README.md` or `docs/deploy.md`, the docspec is `.docspec/README.docspec.md` or `.docspec/docs/deploy.docspec.md` respectively.
+
+The **format template** is fully up to you: it lives at **`.docspec/docspec.md`**. If you run any docspec command and `.docspec/docspec.md` does not exist, it is seeded from the bundled default (the content of `docspec-format.md` in this repo). Edit `.docspec/docspec.md` to define your own structure.
 
-Each `*.docspec.md` file is a specification for another document. The format is defined in [`docspec-format.md`](docspec-format.md), which serves as both the format definition and a reference example.
+## The Docspec Format
 
-The format includes 5 required sections:
-1. **Document Purpose** - What this document exists to explain or enable
-2. **Update Triggers** - What kinds of changes should cause this document to be updated
-3. **Expected Structure** - The sections this document should contain
-4. **Editing Guidelines** - How edits to this document should be made
-5. **Intentional Omissions** - What this document deliberately does not cover
+Each `*.docspec.md` file is a specification for another document. The **default** format (used when seeding) is defined in [`docspec-format.md`](docspec-format.md). After seeding, your project uses `.docspec/docspec.md`, which you can change.
 
-Each section must be customized. The validator ensures each section contains non-boilerplate content by checking that:
-- Each section differs from the template boilerplate text
-- Content is not just whitespace differences from boilerplate
-- Each section has at least 50 characters of meaningful content
+The default includes 5 sections: Document Purpose, Update Triggers, Expected Structure, Editing Guidelines, Intentional Omissions. Customize the template in `.docspec/docspec.md` to match your needs.
 
 ## Installation
 
@@ -34,162 +28,91 @@ npm install -g docspec
 
 ### CLI Commands
 
-#### Validate docspec files
+#### Generate a docspec file (default)
 
-Validate specific files:
+Pass a markdown file path to create (or overwrite) its docspec under `.docspec/`:
 
 ```bash
-docspec validate path/to/file.docspec.md
+docspec README.md
+docspec docs/deploy.md
 ```
 
-Or validate all `*.docspec.md` files in the current directory tree:
-
-```bash
-docspec validate
-```
+This creates `.docspec/README.docspec.md` and `.docspec/docs/deploy.docspec.md` using the template at `.docspec/docspec.md` (seeded from the default on first run).
 
-The validator will recursively find all docspec files, skipping `node_modules`, `.git`, and `dist` directories. Permission errors are handled gracefully and will not cause validation to fail.
+#### docspec changed (prompt for syncing docs after changes)
 
-#### Generate a new docspec file
+Produce a prompt file that instructs an LLM to sync markdown files with their docspecs given a list of changed files or a git diff:
 
 ```bash
-docspec generate path/to/README.docspec.md
+docspec changed --base <base_sha> --merge <merge_sha> --output prompt.txt
+docspec changed --changed-files "src/foo.ts,README.md" --output prompt.txt
 ```
 
-This will generate a docspec file that references the target markdown file using the naming convention: `filename.docspec.md` targets `filename.md` (e.g., `README.docspec.md` references `README.md`, `docs/guide.docspec.md` references `docs/guide.md`).
+Options: `--max-docspecs`, `--max-diff-chars`. Default output file: `prompt.txt`.
 
-### Library Usage
-
-```typescript
-import { validateDocspec, generateDocspec } from "docspec";
-import type { ValidationResult, DocspecSection } from "docspec";
+#### docspec generate (docspec + prompt for LLM)
 
-// Validate a file
-const result: ValidationResult = await validateDocspec("path/to/file.docspec.md");
-if (!result.valid) {
-  console.error("Validation errors:", result.errors);
-}
-
-// Generate a new docspec file
-await generateDocspec("path/to/README.docspec.md");
-```
-
-The library exports:
-- `validateDocspec()` - Validate a docspec file
-- `generateDocspec()` - Generate a new docspec file
-- `generateDocspecContent()` - Generate docspec content as a string
-- `ValidationResult` - Type for validation results
-- `DocspecSection` - Type for docspec sections
-- `REQUIRED_SECTIONS` - Array of required section names
-- `SECTION_BOILERPLATE` - Boilerplate text for each section
-
-## Pre-commit Integration
-
-To use docspec with [pre-commit](https://pre-commit.com/), see [`.pre-commit-config.yaml`](.pre-commit-config.yaml) for the configuration. The hook uses `docspec validate` as the entry point, targets `\.docspec\.md$` files, and passes filenames to the validate command.
-
-Then install the pre-commit hooks:
+Generate a new docspec for a markdown file and write a prompt you can feed to your LLM to fill or improve it:
 
 ```bash
-pre-commit install
+docspec generate README.md --output-prompt prompt.txt
+docspec generate docs/deploy.md --overwrite --output-prompt prompt.txt
 ```
 
-The hook will automatically validate any modified `*.docspec.md` files on commit. The hook passes filenames to the validate command, which will validate only those specific files. If no filenames are passed, the validator recursively finds all `*.docspec.md` files in the directory tree.
-
-## GitHub Action Integration
-
-Docspec includes two GitHub Actions for different use cases:
-
-1. **Post-merge documentation updates** - Automatically syncs markdown files after PR merges (workflow file: `.github/workflows/docspec-check.yml`, workflow name: "Docspec PR check")
-2. **Manual docspec generation** - Manually triggered workflow to generate and improve docspec files (workflow file: `.github/workflows/docspec-generate.yml`, workflow name: "Docspec generate")
-
-### Post-Merge Documentation Updates
-
-This action automatically updates markdown files based on `*.docspec.md` files after PR merges. It uses Claude Code CLI (not the Anthropic API directly) to explore the repository and generate unified diff patches for documentation updates.
-
-#### Setup
+Use `--overwrite` to replace an existing docspec. Optionally `--output-plan <file>` to write a separate plan prompt.
 
-1. **Add the workflow** to your repository: [`.github/workflows/docspec-check.yml`](.github/workflows/docspec-check.yml)
+Add the `--verbose` flag to any command for detailed logging.
 
-2. **Configure secrets**:
-   - Add `ANTHROPIC_API_KEY` to your repository secrets (Settings → Secrets and variables → Actions)
-   - `GITHUB_TOKEN` is automatically provided by GitHub Actions
-
-#### How It Works
-
-1. When a PR is merged, the workflow triggers
-2. The action discovers relevant `*.docspec.md` files using a three-part discovery strategy:
-   - Files that changed directly in the PR (docspec files modified in the merge)
-   - Files in the same directory as any changed file (sibling docspecs)
-   - Files in parent directories, walking up to the repository root (ancestor docspecs)
-3. For each discovered docspec, Claude Code CLI is invoked with built-in tools to explore the repository and understand the codebase context
-4. Claude generates a unified diff patch to update the target markdown file based on the code changes and docspec requirements
-5. Unified diff patches are validated and applied to update the markdown files
-6. A new PR is opened with the documentation updates
-
-**File naming convention**: The action uses the pattern `filename.docspec.md` → `filename.md`:
-- `README.docspec.md` → targets `README.md`
-- `docs/guide.docspec.md` → targets `docs/guide.md`
-
-#### Configuration Options
-
-The action supports optional inputs:
-
-- `max_docspecs` (default: `10`) - Maximum number of docspec files to process per merge
-- `max_diff_chars` (default: `120000`) - Maximum characters in PR diff before truncation
-- `anthropic_model` (default: `claude-sonnet-4-5`) - Anthropic model to use (short alias for the Claude Sonnet 4.5 model)
-
-See [`.github/workflows/docspec-check.yml`](.github/workflows/docspec-check.yml) for the complete workflow file and [`action.yml`](action.yml) for all available configuration options.
-
-**Note**: For this repository's own workflow files, you can use the local reference `uses: ./` (at the action level in the step) instead of the published action reference. This applies to both the post-merge workflow and the manual improvement workflow.
-
-#### Safety Features
-
-The action includes multiple guardrails to ensure safe operation:
-
-- **Max files limit**: Prevents processing too many files in a single run (default: 10)
-- **Diff truncation**: Large PR diffs are truncated to stay within token limits (default: 120,000 characters)
-- **Unified diff validation**: Only accepts properly formatted patches that start with `diff --git` or `--- ` markers
-- **Path validation**: Patches must reference the expected file path
-- **No new files**: Patches cannot create new files
-- **No non-markdown modifications**: Only markdown files can be modified
-- **Concurrency control**: Prevents multiple workflow runs from conflicting
-- **Controlled environment**: Claude Code CLI runs with built-in tools in a controlled filesystem environment
-
-### Manual Docspec Generation
-
-The docspec-generate workflow allows you to manually trigger generation and improvements to a docspec file and its associated markdown file. This is useful when you want to:
-
-- Update a docspec to better reflect the current state of the markdown
-- Discover gaps in documentation that aren't triggered by code changes
-- Regenerate a docspec from scratch
-
-#### Setup
+### Library Usage
 
-Add the workflow to your repository: [`.github/workflows/docspec-generate.yml`](.github/workflows/docspec-generate.yml)
+```typescript
+import {
+  generateDocspec,
+  buildDocspecChangedPrompt,
+  buildDocspecGeneratePrompts,
+  markdownToDocspecPath,
+  docspecToMarkdownPath,
+} from "docspec";
+
+// Generate a docspec for a markdown file (writes to .docspec/<path>.docspec.md)
+await generateDocspec("README.md");
+
+// Build prompt for docspec changed (e.g. for CI)
+const { prompt, outputPath } = await buildDocspecChangedPrompt({
+  base: "abc123",
+  merge: "def456",
+  outputPath: "prompt.txt",
+});
+
+// Build prompts for docspec generate
+const { implPrompt } = await buildDocspecGeneratePrompts({
+  markdownPath: "README.md",
+  outputPromptPath: "prompt.txt",
+});
+```
 
-#### How It Works
+The library also exports: `generateDocspecContent()`, `REQUIRED_SECTIONS`, `SECTION_BOILERPLATE`, `logger`, `LogLevel`, `isDocspecPath`, and types `DocspecChangedOptions`, `DocspecGenerateOptions`.
 
-The workflow uses a two-phase approach with Claude Code CLI:
+## GitHub Actions
 
-1. **Discovery Phase**: Claude explores the repository using available tools (no editing capabilities) and creates a detailed information discovery plan identifying:
-   - Missing information in the docspec (what should be documented but isn't)
-   - Irrelevant or incorrect information in the docspec (what doesn't match reality)
-   - Missing information in the markdown file (gaps in documentation)
+Docspec’s actions **only produce prompt files**; they do not run an LLM or require API keys.
 
-2. **Implementation Phase**: Claude uses editing tools with `--permission-mode acceptEdits` to update both files based on the discovery plan. It preserves the exact structure of the docspec file (headers, separators, frontmatter, AGENT INSTRUCTIONS section) while only updating the content within sections 1-5.
+- **docspec-changed** (`.github/actions/docspec-check`) – Runs `docspec changed` and writes a prompt file. Outputs `prompt_file` and `has_prompt`.
+- **docspec-generate** (`.github/actions/docspec-generate`) – Runs `docspec generate <markdown_file>` and writes a prompt file.
 
-Before the discovery phase begins, the workflow:
-- Generates or overwrites the docspec file using `docspec generate`
-- Validates the updated docspec file using `docspec validate` after changes are made
+### Example: run docspec changed then Claude
 
-#### Usage
+This repo’s [`.github/workflows/docspec-check.yml`](.github/workflows/docspec-check.yml) runs when a PR is merged: it prepares the prompt with `docspec changed`, then runs the [official Claude Code Action](https://github.com/anthropics/claude-code-action) with that prompt. Add `ANTHROPIC_API_KEY` to your repository secrets if you want the Claude step to run.
 
-1. Go to Actions → "Audit and improve docspec" in your repository
-2. Click "Run workflow"
-3. Enter the path to the markdown file (e.g., `README.md`)
-4. The workflow will generate/update the corresponding docspec file and create a PR with improvements
+### Example: docspec generate (prompt only)
 
-**Note**: This workflow requires the `ANTHROPIC_API_KEY` secret to be configured.
+```yaml
+- uses: actions/checkout@v4
+- uses: docspec-ai/docspec/.github/actions/docspec-generate@main
+  with:
+    markdown_file: README.md
+    overwrite: false
+```
 
 ## Development
 
@@ -214,4 +137,3 @@ npm run build
 ## License
 
 MIT
-

package/dist/__tests__/changed.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=changed.test.d.ts.map

package/dist/__tests__/changed.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/changed.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/changed.test.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const changed_1 = require("../changed");
+describe("changed", () => {
+    let tempDir;
+    let originalCwd;
+    beforeEach(async () => {
+        tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "docspec-changed-test-"));
+        originalCwd = process.cwd();
+        process.chdir(tempDir);
+    });
+    afterEach(async () => {
+        process.chdir(originalCwd);
+        await fs.rm(tempDir, { recursive: true, force: true });
+    });
+    it("returns empty prompt when no docspecs match changed files", async () => {
+        await fs.mkdir(path.join(tempDir, ".docspec", "sub"), { recursive: true });
+        await fs.writeFile(path.join(tempDir, ".docspec", "sub", "bar.docspec.md"), "# DOCSPEC: bar\n\n## 1. Purpose\n\n", "utf-8");
+        await fs.mkdir(path.join(tempDir, "sub"), { recursive: true });
+        await fs.writeFile(path.join(tempDir, "sub", "bar.md"), "# Bar", "utf-8");
+        await fs.writeFile(path.join(tempDir, "root-only.js"), "code", "utf-8");
+        const { prompt } = await (0, changed_1.buildDocspecChangedPrompt)({
+            changedFiles: ["root-only.js"],
+            repoRoot: tempDir,
+        });
+        expect(prompt).toBe("");
+    });
+    it("builds prompt when changed file is the target markdown of a docspec", async () => {
+        await fs.mkdir(path.join(tempDir, ".docspec"), { recursive: true });
+        const docspecContent = "# DOCSPEC: [foo.md](/foo.md)\n\n## 1. Purpose\n\nDescribe foo.";
+        await fs.writeFile(path.join(tempDir, ".docspec", "foo.docspec.md"), docspecContent, "utf-8");
+        await fs.writeFile(path.join(tempDir, "foo.md"), "# Foo content", "utf-8");
+        const { prompt, outputPath } = await (0, changed_1.buildDocspecChangedPrompt)({
+            changedFiles: ["foo.md"],
+            repoRoot: tempDir,
+        });
+        expect(prompt).toContain("<diff>");
+        expect(prompt).toContain("## Docspec: .docspec/foo.docspec.md");
+        expect(prompt).toContain("Target markdown: foo.md");
+        expect(prompt).toContain("<docspec>");
+        expect(prompt).toContain(docspecContent);
+        expect(prompt).toContain("<markdown>");
+        expect(prompt).toContain("# Foo content");
+        expect(prompt).toContain("Task:");
+        expect(outputPath).toBeNull();
+    });
+    it("writes prompt to outputPath when provided", async () => {
+        await fs.mkdir(path.join(tempDir, ".docspec"), { recursive: true });
+        await fs.writeFile(path.join(tempDir, ".docspec", "bar.docspec.md"), "# DOCSPEC: bar\n\n## 1. Purpose\n\n", "utf-8");
+        await fs.writeFile(path.join(tempDir, "bar.md"), "# Bar", "utf-8");
+        const { prompt, outputPath } = await (0, changed_1.buildDocspecChangedPrompt)({
+            changedFiles: ["bar.md"],
+            repoRoot: tempDir,
+            outputPath: "out/prompt.txt",
+        });
+        expect(prompt.length).toBeGreaterThan(0);
+        expect(outputPath).toBe(path.join(tempDir, "out", "prompt.txt"));
+        const written = await fs.readFile(path.join(tempDir, "out", "prompt.txt"), "utf-8");
+        expect(written).toBe(prompt);
+    });
+});
+//# sourceMappingURL=changed.test.js.map

package/dist/__tests__/changed.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed.test.js","sourceRoot":"","sources":["../../src/__tests__/changed.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/cli.test.js

@@ -38,7 +38,6 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const util_1 = require("util");
-const generator_1 = require("../generator");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 describe("CLI", () => {
     let tempDir;
@@ -48,14 +47,25 @@ describe("CLI", () => {
         originalCwd = process.cwd();
         process.chdir(tempDir);
     });
+    beforeAll(async () => {
+        const cliPath = path.resolve(process.cwd(), "dist", "cli.js");
+        try {
+            await fs.access(cliPath);
+        }
+        catch {
+            throw new Error("CLI tests require dist/cli.js. Run 'npm run build' before 'npm test'.");
+        }
+    });
     afterEach(async () => {
         process.chdir(originalCwd);
         await fs.rm(tempDir, { recursive: true, force: true });
     });
     const runCli = async (args) => {
-        const cliPath = path.join(__dirname, "../../dist/cli.js");
+        const cliPath = path.resolve(originalCwd, "dist", "cli.js");
         try {
-            const { stdout, stderr } = await execAsync(`node ${cliPath} ${args}`);
+            const { stdout, stderr } = await execAsync(`node "${cliPath}" ${args}`, {
+                cwd: tempDir,
+            });
             return { stdout: stdout || "", stderr: stderr || "", code: 0 };
         }
         catch (error) {
@@ -66,179 +76,72 @@ describe("CLI", () => {
             };
         }
     };
-    describe("validate command", () => {
-        it("should validate a valid docspec file", async () => {
-            const filePath = path.join(tempDir, "valid.docspec.md");
-            const validContent = `# DOCSPEC: Test
-
-## 1. Document Purpose
-
-This document serves as a test case for the CLI validation command. It contains custom content that is different from the boilerplate template and sufficient to pass validation.
-
-## 2. Update Triggers
-
-This document should be updated when testing CLI validation functionality. The content is meaningful and customized for testing purposes.
-
-## 3. Expected Structure
-
-This section describes the structure of the test document. It includes all required sections with adequate content to pass validation checks.
-
-## 4. Editing Guidelines
-
-The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
-
-## 5. Intentional Omissions
-
-There are no known gaps in this test document. All sections are complete and properly formatted with sufficient content.
-`;
-            await fs.writeFile(filePath, validContent, "utf-8");
-            const result = await runCli(`validate ${filePath}`);
-            expect(result.code).toBe(0);
-            expect(result.stdout).toContain("✅");
-        });
-        it("should reject an invalid docspec file", async () => {
-            const filePath = path.join(tempDir, "invalid.docspec.md");
-            await (0, generator_1.generateDocspec)(filePath); // This creates boilerplate-only content
-            const result = await runCli(`validate ${filePath}`);
-            expect(result.code).toBe(1);
-            const output = result.stdout + result.stderr;
-            expect(output).toContain("❌");
-            expect(output).toContain("boilerplate");
-        });
-        it("should validate multiple files", async () => {
-            const file1 = path.join(tempDir, "file1.docspec.md");
-            const file2 = path.join(tempDir, "file2.docspec.md");
-            const validContent = `# DOCSPEC: Test
-
-## 1. Document Purpose
-
-This document serves as a test case for validating multiple docspec files. It contains custom content that is different from the boilerplate template.
-
-## 2. Update Triggers
-
-This document should be updated when testing multiple file validation. The content is meaningful and customized for testing purposes.
-
-## 3. Expected Structure
-
-This section describes the structure of the test document. It includes all required sections with adequate content to pass validation checks.
-
-## 4. Editing Guidelines
-
-The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
-
-## 5. Intentional Omissions
-
-There are no known gaps in this test document. All sections are complete and properly formatted with sufficient content.
-`;
-            await fs.writeFile(file1, validContent, "utf-8");
-            await fs.writeFile(file2, validContent, "utf-8");
-            const result = await runCli(`validate ${file1} ${file2}`);
-            expect(result.code).toBe(0);
-            expect(result.stdout).toContain("file1.docspec.md");
-            expect(result.stdout).toContain("file2.docspec.md");
-        });
-        it("should find all docspec files when no paths provided", async () => {
-            const file1 = path.join(tempDir, "file1.docspec.md");
-            const file2 = path.join(tempDir, "nested", "file2.docspec.md");
-            await fs.mkdir(path.join(tempDir, "nested"), { recursive: true });
-            const validContent = `# DOCSPEC: Test
-
-## 1. Document Purpose
-
-This document serves as a test case for validating multiple docspec files. It contains custom content that is different from the boilerplate template.
-
-## 2. Update Triggers
-
-This document should be updated when testing multiple file validation. The content is meaningful and customized for testing purposes.
-
-## 3. Expected Structure
-
-This section describes the structure of the test document. It includes all required sections with adequate content to pass validation checks.
-
-## 4. Editing Guidelines
-
-The style for this test document is straightforward and technical. It focuses on clarity and precision in describing test scenarios. Do: Ensure all sections have adequate content. Don't: Use boilerplate text or leave sections empty. Always provide meaningful test data.
-
-## 5. Intentional Omissions
-
-There are no known gaps in this test document. All sections are complete and properly formatted with sufficient content.
-`;
-            await fs.writeFile(file1, validContent, "utf-8");
-            await fs.writeFile(file2, validContent, "utf-8");
-            const result = await runCli("validate");
+    describe("default command (docspec <markdown_path>)", () => {
+        it("should seed .docspec/docspec.md from default when missing", async () => {
+            const result = await runCli("seed-test.md");
             expect(result.code).toBe(0);
-            expect(result.stdout).toContain("file1.docspec.md");
-            expect(result.stdout).toContain("file2.docspec.md");
-        });
-        it("should handle non-existent files gracefully", async () => {
-            const result = await runCli("validate nonexistent.docspec.md");
-            expect(result.code).toBe(1);
-            const output = result.stdout + result.stderr;
-            expect(output).toContain("Failed to read file");
-        });
-        it("should skip node_modules and .git directories", async () => {
-            await fs.mkdir(path.join(tempDir, "node_modules"), { recursive: true });
-            await fs.mkdir(path.join(tempDir, ".git"), { recursive: true });
-            const fileInNodeModules = path.join(tempDir, "node_modules", "test.docspec.md");
-            const fileInGit = path.join(tempDir, ".git", "test.docspec.md");
-            await fs.writeFile(fileInNodeModules, "test", "utf-8");
-            await fs.writeFile(fileInGit, "test", "utf-8");
-            const result = await runCli("validate");
-            // Should not find files in node_modules or .git
-            expect(result.stdout).not.toContain("node_modules");
-            expect(result.stdout).not.toContain(".git");
+            const templatePath = path.join(tempDir, ".docspec", "docspec.md");
+            const templateExists = await fs.access(templatePath).then(() => true).catch(() => false);
+            expect(templateExists).toBe(true);
+            const content = await fs.readFile(templatePath, "utf-8");
+            expect(content).toContain("Document Purpose");
+            expect(content).toContain("{{TARGET_FILE}}");
         });
-    });
-    describe("generate command", () => {
-        it("should generate a new docspec file", async () => {
-            const filePath = path.join(tempDir, "new.docspec.md");
-            const result = await runCli(`generate ${filePath}`);
+        it("should generate a new docspec file under .docspec/ for markdown path", async () => {
+            const result = await runCli("new.md");
             expect(result.code).toBe(0);
             expect(result.stdout).toContain("✅");
-            expect(result.stdout).toContain("new.docspec.md");
+            expect(result.stdout).toContain(".docspec/new.docspec.md");
+            const filePath = path.join(tempDir, ".docspec", "new.docspec.md");
             const exists = await fs.access(filePath).then(() => true).catch(() => false);
             expect(exists).toBe(true);
         });
         it("should generate file with correct content", async () => {
-            const filePath = path.join(tempDir, "test.docspec.md");
-            await runCli(`generate ${filePath}`);
+            await runCli("test.md");
+            const filePath = path.join(tempDir, ".docspec", "test.docspec.md");
             const content = await fs.readFile(filePath, "utf-8");
             expect(content).toContain("# DOCSPEC: [test.md](/test.md)");
             expect(content).toContain("Document Purpose");
         });
-        it("should auto-append .docspec.md if not present", async () => {
-            const filePath = path.join(tempDir, "test");
-            await runCli(`generate ${filePath}`);
-            const fullPath = filePath + ".docspec.md";
-            const exists = await fs.access(fullPath).then(() => true).catch(() => false);
-            expect(exists).toBe(true);
-        });
-        it("should create nested directories", async () => {
-            const filePath = path.join(tempDir, "nested", "deep", "test.docspec.md");
-            const result = await runCli(`generate ${filePath}`);
+        it("should create nested directories under .docspec/", async () => {
+            const result = await runCli("nested/deep/test.md");
             expect(result.code).toBe(0);
+            const filePath = path.join(tempDir, ".docspec", "nested", "deep", "test.docspec.md");
             const exists = await fs.access(filePath).then(() => true).catch(() => false);
             expect(exists).toBe(true);
         });
         it("should generate link to target markdown file", async () => {
-            const filePath = path.join(tempDir, "my-awesome-doc.docspec.md");
-            await runCli(`generate ${filePath}`);
+            await runCli("my-awesome-doc.md");
+            const filePath = path.join(tempDir, ".docspec", "my-awesome-doc.docspec.md");
             const content = await fs.readFile(filePath, "utf-8");
             expect(content).toContain("# DOCSPEC: [my-awesome-doc.md](/my-awesome-doc.md)");
         });
     });
+    describe("generate subcommand (file + prompt)", () => {
+        it("should generate docspec and write prompt file", async () => {
+            await fs.writeFile(path.join(tempDir, "README.md"), "# Hello", "utf-8");
+            const result = await runCli("generate README.md --output-prompt prompt.txt");
+            expect(result.code).toBe(0);
+            expect(result.stdout).toContain(".docspec/README.docspec.md");
+            expect(result.stdout).toContain("prompt");
+            const promptPath = path.join(tempDir, "prompt.txt");
+            const exists = await fs.access(promptPath).then(() => true).catch(() => false);
+            expect(exists).toBe(true);
+        });
+    });
     describe("help and version", () => {
         it("should show help message", async () => {
             const result = await runCli("--help");
             expect(result.code).toBe(0);
             expect(result.stdout).toContain("Usage:");
-            expect(result.stdout).toContain("validate");
+            expect(result.stdout).toContain("changed");
             expect(result.stdout).toContain("generate");
+            expect(result.stdout).toContain("markdown_path");
         });
         it("should show version", async () => {
             const result = await runCli("--version");
             expect(result.code).toBe(0);
-            expect(result.stdout).toContain("0.1.0");
+            expect(result.stdout).toContain("0.3.0");
         });
     });
 });