docspec 0.1.0 → 0.3.0

package/dist/docspec-changed.js

@@ -0,0 +1,210 @@
+"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 });
+exports.buildDocspecChangedPrompt = buildDocspecChangedPrompt;
+const fs = __importStar(require("fs/promises"));
+const fsSync = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const path_utils_1 = require("./path-utils");
+const DEFAULT_MAX_DOCSPECS = 10;
+const DEFAULT_MAX_DIFF_CHARS = 120000;
+/**
+ * List changed files via git diff --name-only base...merge
+ */
+function listChangedFiles(base, merge, repoRoot) {
+    const out = (0, child_process_1.execSync)(`git diff --name-only ${base}...${merge}`, {
+        encoding: "utf-8",
+        cwd: repoRoot,
+    }).trim();
+    return out ? out.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+}
+/**
+ * Get diff text via git diff base...merge, truncated if needed.
+ */
+function getDiffText(base, merge, repoRoot, maxChars) {
+    let diff;
+    try {
+        diff = (0, child_process_1.execSync)(`git diff ${base}...${merge}`, { encoding: "utf-8", cwd: repoRoot });
+    }
+    catch {
+        return "";
+    }
+    if (diff.length > maxChars) {
+        diff = diff.slice(0, maxChars) + "\n\n[DIFF TRUNCATED]\n";
+    }
+    return diff;
+}
+/**
+ * Find all docspec paths under .docspec/ in the repo.
+ */
+async function findAllDocspecPaths(docspecDir) {
+    const files = [];
+    try {
+        const entries = await fs.readdir(docspecDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(docspecDir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await findAllDocspecPaths(full)));
+            }
+            else if (entry.isFile() && entry.name.endsWith(".docspec.md")) {
+                files.push(full);
+            }
+        }
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    return files;
+}
+/**
+ * Find candidate docspec files to process given changed files.
+ * Strategy:
+ * 1) Changed files that are under .docspec/ and end with .docspec.md are included.
+ * 2) For each other changed file, walk up from its directory to repo root; at each level,
+ *    include docspecs whose target markdown lives in that directory.
+ */
+function findCandidateDocspecs(repoRoot, docspecPaths, changedFiles, maxDocspecs) {
+    const normalizedRoot = path.normalize(repoRoot).replace(/\\/g, "/");
+    const candidates = [];
+    const seen = new Set();
+    const add = (p) => {
+        const norm = path.normalize(p).replace(/\\/g, "/");
+        if (!seen.has(norm)) {
+            seen.add(norm);
+            candidates.push(p);
+        }
+    };
+    // 1) Directly changed docspecs (under .docspec/)
+    for (const f of changedFiles) {
+        const normalized = path.normalize(f).replace(/\\/g, "/");
+        if ((0, path_utils_1.isDocspecPath)(normalized) || (normalized.startsWith(".docspec/") && normalized.endsWith(".docspec.md"))) {
+            const full = path.join(repoRoot, f);
+            add(full);
+        }
+    }
+    // 2) For each changed file, walk up directory and include docspecs whose target markdown is in that directory
+    for (const f of changedFiles) {
+        const normalized = path.normalize(f).replace(/\\/g, "/");
+        if (normalized.startsWith(".docspec/"))
+            continue; // already handled
+        const fullPath = path.join(repoRoot, f);
+        let dir = path.dirname(fullPath);
+        while (true) {
+            const relDir = path.relative(repoRoot, dir).replace(/\\/g, "/") || ".";
+            for (const { docspecPath, targetMdPath } of docspecPaths) {
+                const targetDir = path.dirname(targetMdPath).replace(/\\/g, "/") || ".";
+                if (targetDir === relDir) {
+                    add(docspecPath);
+                }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir || path.relative(repoRoot, parent).startsWith(".."))
+                break;
+            dir = parent;
+        }
+        // Include if the changed file is the target markdown
+        for (const { docspecPath, targetMdPath } of docspecPaths) {
+            if (path.normalize(f).replace(/\\/g, "/") === path.normalize(targetMdPath).replace(/\\/g, "/")) {
+                add(docspecPath);
+            }
+        }
+    }
+    return candidates.slice(0, maxDocspecs);
+}
+/**
+ * Build the docspec-changed prompt and return it as a string.
+ * If options.outputPath is set, writes the prompt to that file.
+ */
+async function buildDocspecChangedPrompt(options) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const docspecDir = path.join(repoRoot, ".docspec");
+    let changedFiles = options.changedFiles ?? [];
+    let diffText = "";
+    if (changedFiles.length === 0 && options.base && options.merge) {
+        changedFiles = listChangedFiles(options.base, options.merge, repoRoot);
+        diffText = getDiffText(options.base, options.merge, repoRoot, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+    }
+    else if (options.changedFiles && options.changedFiles.length > 0 && options.base && options.merge) {
+        diffText = getDiffText(options.base, options.merge, repoRoot, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+    }
+    const allDocspecPaths = await findAllDocspecPaths(docspecDir);
+    const docspecWithTargets = allDocspecPaths
+        .map((p) => {
+        const rel = path.relative(repoRoot, p).replace(/\\/g, "/");
+        const targetMd = (0, path_utils_1.docspecToMarkdownPath)(rel);
+        return { docspecPath: p, targetMdPath: targetMd };
+    })
+        .filter(({ docspecPath }) => fsSync.existsSync(docspecPath));
+    const candidates = findCandidateDocspecs(repoRoot, docspecWithTargets, changedFiles, options.maxDocspecs ?? DEFAULT_MAX_DOCSPECS);
+    const parts = [
+        "Merged PR diff (context):",
+        "<diff>",
+        diffText || "(no diff available)",
+        "</diff>",
+        "",
+        "The following docspec files were discovered based on the PR changes. For each docspec, check if its target markdown file needs to be updated based on the code changes:",
+        "",
+    ];
+    let added = 0;
+    for (const docspecPath of candidates) {
+        const relDocspec = path.relative(repoRoot, docspecPath).replace(/\\/g, "/");
+        const targetMdPath = (0, path_utils_1.docspecToMarkdownPath)(relDocspec);
+        const targetFull = path.join(repoRoot, targetMdPath);
+        try {
+            await fs.access(targetFull);
+        }
+        catch {
+            continue;
+        }
+        const docspecContent = await fs.readFile(docspecPath, "utf-8");
+        const mdContent = await fs.readFile(targetFull, "utf-8");
+        parts.push(`## Docspec: ${relDocspec}`, `Target markdown: ${targetMdPath}`, "", "<docspec>", docspecContent, "</docspec>", "", "<markdown>", mdContent, "</markdown>", "");
+        added++;
+    }
+    if (added === 0) {
+        return { prompt: "", outputPath: null };
+    }
+    parts.push("Task:", "1. Explore the repository using your available tools to understand the codebase context", "2. Understand how the code changes in the diff relate to each docspec's requirements", "3. For each markdown file listed above, check if it already satisfies its docspec given the code changes", "4. Only update markdown files if changes are actually necessary to satisfy their docspecs - avoid making unnecessary changes", "5. Use the Edit tool to modify markdown files directly if changes are needed", "6. Do not provide any text output - files are modified directly using tools");
+    const prompt = parts.join("\n");
+    const outPath = options.outputPath ? path.resolve(repoRoot, options.outputPath) : null;
+    if (outPath && prompt) {
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await fs.writeFile(outPath, prompt, "utf-8");
+    }
+    return { prompt, outputPath: outPath };
+}
+//# sourceMappingURL=docspec-changed.js.map

package/dist/docspec-changed.js.map

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

package/dist/docspec-generate.d.ts

@@ -0,0 +1,22 @@
+export interface DocspecGenerateOptions {
+    /** Path to the markdown file (repo-relative, e.g. README.md or docs/deploy.md). */
+    markdownPath: string;
+    /** If true, overwrite existing docspec. If false and docspec exists, throws. */
+    overwrite?: boolean;
+    /** Repo root (default process.cwd()). */
+    repoRoot?: string;
+}
+/**
+ * Generate the docspec file (if missing or overwrite), then build plan and implementation prompts.
+ * Returns combined prompt (implementation prompt with {{PLAN}} placeholder) and optional paths to write.
+ */
+export declare function buildDocspecGeneratePrompts(options: DocspecGenerateOptions & {
+    outputPromptPath?: string;
+    outputPlanPath?: string;
+}): Promise<{
+    planPrompt: string;
+    implPrompt: string;
+    outputPromptPath?: string;
+    outputPlanPath?: string;
+}>;
+//# sourceMappingURL=docspec-generate.d.ts.map

package/dist/docspec-generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docspec-generate.d.ts","sourceRoot":"","sources":["../src/docspec-generate.ts"],"names":[],"mappings":"AAqFA,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,sBAAsB,GAAG;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0DzG"}

package/dist/docspec-generate.js

@@ -0,0 +1,171 @@
+"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 });
+exports.buildDocspecGeneratePrompts = buildDocspecGeneratePrompts;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const generator_1 = require("./generator");
+const path_utils_1 = require("./path-utils");
+const PLAN_TEMPLATE = `You are analyzing a markdown file and its docspec to discover missing or irrelevant information. Do not ask questions - create the plan directly.
+
+<markdown path="{{md_path}}">
+{{md_text}}
+</markdown>
+
+<docspec path="{{docspec_path}}">
+{{docspec_text}}
+</docspec>
+
+Task: Focus on INFORMATION DISCOVERY. Use all of your available tools to explore the repository and understand what actually exists, then analyze both files and create a plan that identifies:
+
+1. **Missing information in the docspec**: What important details about the markdown file are not captured in sections 1-5?
+   - What does the markdown actually contain that isn't mentioned in the docspec?
+   - What should trigger updates that isn't currently listed?
+   - What structure/guidelines are missing?
+
+2. **Irrelevant or incorrect information in the docspec**: What's in the docspec that doesn't match reality?
+   - Does the docspec describe things that aren't actually in the markdown?
+   - Are there update triggers that don't make sense?
+   - Are there structure requirements that don't match the actual document?
+
+3. **Missing information in the markdown**: What should be documented but isn't?
+   - Are there important details missing?
+   - Are there sections that should exist but don't?
+
+IMPORTANT: The docspec structure must be preserved:
+- Keep the header format: \`# DOCSPEC: [filename]\`
+- Keep the one-line description
+- Keep the \`## AGENT INSTRUCTIONS\` section exactly as-is
+- Keep section headers: \`## 1. Document Purpose\`, \`## 2. Update Triggers\`, etc.
+- ONLY update the CONTENT within sections 1-5, not the headers or structure
+
+Output your plan in a clear, structured format focusing on information gaps and corrections.
+`;
+const IMPL_TEMPLATE = `Based on this information discovery plan:
+<plan>
+{{PLAN}}
+</plan>
+
+You need to update two files:
+1. {{md_path}} - the markdown file
+2. {{docspec_path}} - the docspec file
+
+CRITICAL CONSTRAINTS FOR DOCSPEC FILE - YOU MUST PRESERVE THE EXACT STRUCTURE:
+
+1. Read the existing {{docspec_path}} file FIRST using the Read tool
+2. PRESERVE EXACTLY:
+   - The exact header format (e.g. \`# DOCSPEC: Readme\` or \`# DOCSPEC: [README.md](/README.md)\`) - keep it EXACTLY as written
+   - The exact one-line description format (e.g. \`> A specification that ...\`) - keep it EXACTLY as written
+   - The \`## AGENT INSTRUCTIONS\` section if it exists - keep it EXACTLY as-is, do not modify
+   - The EXACT section header names and numbers (e.g. \`## 1. Document Purpose\` or \`## 2. Update Triggers\`) - keep them EXACTLY as written
+   - The order of sections - do not reorder them
+
+3. ONLY update the CONTENT within sections 1-5 (the text below each section header)
+   - Do NOT change section header text, numbers, or names
+   - Do NOT change the format of headers
+   - Do NOT modify title, description, or AGENT INSTRUCTIONS
+
+Task:
+1. Read {{docspec_path}} and note its EXACT structure
+2. Read {{md_path}}
+3. Explore the repository and discover information about:
+   - What the codebase actually contains
+   - What files exist that relate to the markdown
+   - What the actual structure and content of the markdown is
+4. For {{docspec_path}}: Update ONLY the content text within sections 1-5. Preserve ALL structure, headers, format, and separators exactly as they were.
+5. For {{md_path}}: Add any missing information identified in the plan
+6. Make changes directly to the files
+`;
+function substitute(template, vars) {
+    let out = template;
+    for (const [key, value] of Object.entries(vars)) {
+        out = out.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+    }
+    return out;
+}
+/**
+ * Generate the docspec file (if missing or overwrite), then build plan and implementation prompts.
+ * Returns combined prompt (implementation prompt with {{PLAN}} placeholder) and optional paths to write.
+ */
+async function buildDocspecGeneratePrompts(options) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const mdPath = path.normalize(options.markdownPath).replace(/\\/g, "/");
+    const mdFull = path.join(repoRoot, mdPath);
+    const docspecPath = (0, path_utils_1.markdownToDocspecPath)(mdPath);
+    const docspecFull = path.join(repoRoot, docspecPath);
+    try {
+        await fs.access(mdFull);
+    }
+    catch {
+        throw new Error(`Markdown file not found: ${mdFull}`);
+    }
+    const docspecExists = await fs.access(docspecFull).then(() => true).catch(() => false);
+    if (docspecExists && !options.overwrite) {
+        throw new Error(`Docspec file already exists: ${docspecPath}. To overwrite, set overwrite to true.`);
+    }
+    await (0, generator_1.generateDocspec)(mdPath);
+    const mdText = await fs.readFile(mdFull, "utf-8");
+    const docspecText = await fs.readFile(docspecFull, "utf-8");
+    const vars = {
+        md_path: mdPath,
+        md_text: mdText,
+        docspec_path: docspecPath,
+        docspec_text: docspecText,
+        "{{PLAN}}": "{{PLAN}}",
+    };
+    const planPrompt = substitute(PLAN_TEMPLATE, vars);
+    const implPrompt = substitute(IMPL_TEMPLATE, vars);
+    const outPrompt = options.outputPromptPath
+        ? path.resolve(repoRoot, options.outputPromptPath)
+        : undefined;
+    const outPlan = options.outputPlanPath
+        ? path.resolve(repoRoot, options.outputPlanPath)
+        : undefined;
+    if (outPrompt) {
+        await fs.mkdir(path.dirname(outPrompt), { recursive: true });
+        await fs.writeFile(outPrompt, implPrompt, "utf-8");
+    }
+    if (outPlan) {
+        await fs.mkdir(path.dirname(outPlan), { recursive: true });
+        await fs.writeFile(outPlan, planPrompt, "utf-8");
+    }
+    return {
+        planPrompt,
+        implPrompt,
+        outputPromptPath: outPrompt,
+        outputPlanPath: outPlan,
+    };
+}
+//# sourceMappingURL=docspec-generate.js.map

package/dist/docspec-generate.js.map

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

package/dist/format-parser.d.ts

@@ -0,0 +1,24 @@
+export interface ParsedSection {
+    name: string;
+    boilerplate: string;
+    number: number;
+}
+export interface ParsedFormat {
+    sections: ParsedSection[];
+    template: string;
+    agentInstructions?: string;
+}
+/**
+ * Parse the docspec format file
+ */
+export declare function parseFormatFile(formatFilePath: string): ParsedFormat;
+/**
+ * Parse format content from a string
+ */
+export declare function parseFormatContent(content: string): ParsedFormat;
+/**
+ * Get the path to the format file. Uses .docspec/docspec.md in cwd.
+ * If it doesn't exist, seeds it from the bundled docspec-format.md and returns the new path.
+ */
+export declare function getFormatFilePath(): string;
+//# sourceMappingURL=format-parser.d.ts.map

package/dist/format-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-parser.d.ts","sourceRoot":"","sources":["../src/format-parser.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAKpE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAyIhE;AAyBD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAS1C"}

package/dist/format-parser.js

@@ -0,0 +1,205 @@
+"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 });
+exports.parseFormatFile = parseFormatFile;
+exports.parseFormatContent = parseFormatContent;
+exports.getFormatFilePath = getFormatFilePath;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("./logger");
+/**
+ * Parse the docspec format file
+ */
+function parseFormatFile(formatFilePath) {
+    logger_1.logger.debug(`Reading format file: ${formatFilePath}`);
+    const content = fs.readFileSync(formatFilePath, "utf-8");
+    logger_1.logger.debug(`Format file read: ${content.length} characters`);
+    return parseFormatContent(content);
+}
+/**
+ * Parse format content from a string
+ */
+function parseFormatContent(content) {
+    const lines = content.split("\n");
+    logger_1.logger.debug(`Parsing format content: ${lines.length} lines`);
+    // Look for AGENT INSTRUCTIONS section first
+    let agentInstructions;
+    let agentInstructionsStart = -1;
+    let agentInstructionsEnd = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "## AGENT INSTRUCTIONS") {
+            agentInstructionsStart = i;
+            logger_1.logger.debug(`Found AGENT INSTRUCTIONS section at line ${i + 1}`);
+            break;
+        }
+    }
+    // If AGENT INSTRUCTIONS section found, extract it
+    if (agentInstructionsStart >= 0) {
+        // Find the end of the AGENT INSTRUCTIONS section
+        // It ends at the next section header (##) or end of file
+        for (let i = agentInstructionsStart + 1; i < lines.length; i++) {
+            const trimmedLine = lines[i].trim();
+            // Check if this is a section header (starts with ##)
+            if (trimmedLine.match(/^##\s+/)) {
+                agentInstructionsEnd = i;
+                break;
+            }
+        }
+        if (agentInstructionsEnd < 0) {
+            agentInstructionsEnd = lines.length;
+        }
+        // Extract content between header and next section
+        const agentLines = lines.slice(agentInstructionsStart + 1, agentInstructionsEnd);
+        let agentContent = agentLines.join("\n");
+        // Remove separator lines (---) from the content
+        agentContent = agentContent
+            .split("\n")
+            .filter(line => line.trim() !== "---")
+            .join("\n")
+            .trim();
+        if (agentContent) {
+            agentInstructions = agentContent;
+            logger_1.logger.debug(`Extracted agent instructions: ${agentContent.length} characters`);
+        }
+    }
+    else {
+        logger_1.logger.debug("No AGENT INSTRUCTIONS section found");
+    }
+    // Find all section headers: ## N. Section Name
+    const sectionHeaderRegex = /^##\s+(\d+)\.\s+(.+)$/;
+    const sectionHeaders = [];
+    for (let i = 0; i < lines.length; i++) {
+        // Skip the AGENT INSTRUCTIONS header if it exists
+        if (lines[i].trim() === "## AGENT INSTRUCTIONS") {
+            continue;
+        }
+        const match = lines[i].match(sectionHeaderRegex);
+        if (match) {
+            sectionHeaders.push({
+                lineIndex: i,
+                number: parseInt(match[1], 10),
+                name: match[2].trim(),
+            });
+            logger_1.logger.debug(`Found section header: ${match[1]}. ${match[2].trim()} at line ${i + 1}`);
+        }
+    }
+    if (sectionHeaders.length === 0) {
+        logger_1.logger.debug("No section headers found in format file");
+        throw new Error("No section headers found in format file. Expected format: ## N. Section Name");
+    }
+    logger_1.logger.debug(`Found ${sectionHeaders.length} section header(s)`);
+    // Extract template: everything before the first numbered section header
+    // But exclude the AGENT INSTRUCTIONS section if it exists
+    const firstSectionLine = sectionHeaders[0].lineIndex;
+    let templateBeforeSections;
+    if (agentInstructionsStart >= 0 && agentInstructionsStart < firstSectionLine) {
+        // AGENT INSTRUCTIONS is between title and first section
+        // Template is everything before AGENT INSTRUCTIONS
+        templateBeforeSections = lines.slice(0, agentInstructionsStart).join("\n").trim();
+        logger_1.logger.debug("Template extracted before AGENT INSTRUCTIONS section");
+    }
+    else {
+        // No AGENT INSTRUCTIONS, use everything before first section
+        templateBeforeSections = lines.slice(0, firstSectionLine).join("\n").trim();
+        logger_1.logger.debug("Template extracted before first section");
+    }
+    const template = templateBeforeSections + "\n\n{{AGENT_INSTRUCTIONS}}\n\n{{SECTIONS}}\n";
+    logger_1.logger.debug(`Template length: ${template.length} characters`);
+    // Extract sections
+    const sections = [];
+    for (let i = 0; i < sectionHeaders.length; i++) {
+        const header = sectionHeaders[i];
+        const nextHeaderLine = i < sectionHeaders.length - 1
+            ? sectionHeaders[i + 1].lineIndex
+            : lines.length;
+        // Extract content between this header and the next header
+        const sectionLines = lines.slice(header.lineIndex + 1, nextHeaderLine);
+        let sectionContent = sectionLines.join("\n");
+        // Remove separator lines (---) from the content
+        sectionContent = sectionContent
+            .split("\n")
+            .filter(line => line.trim() !== "---")
+            .join("\n")
+            .trim();
+        logger_1.logger.debug(`Extracted section "${header.name}": ${sectionContent.length} characters`);
+        sections.push({
+            name: header.name,
+            boilerplate: sectionContent,
+            number: header.number,
+        });
+    }
+    // Sort sections by number to ensure correct order
+    sections.sort((a, b) => a.number - b.number);
+    logger_1.logger.debug(`Parsed ${sections.length} section(s) from format file`);
+    return {
+        sections,
+        template,
+        agentInstructions,
+    };
+}
+const USER_TEMPLATE = ".docspec/docspec.md";
+/**
+ * Seed .docspec/docspec.md from the bundled docspec-format.md if it doesn't exist.
+ * Returns the path to .docspec/docspec.md (in cwd).
+ */
+function seedDefaultFormatFile() {
+    const cwd = process.cwd();
+    const userPath = path.join(cwd, ".docspec", "docspec.md");
+    const defaultPath = path.join(__dirname, "..", "docspec-format.md");
+    logger_1.logger.debug(`Seeding ${userPath} from ${defaultPath}`);
+    if (!fs.existsSync(defaultPath)) {
+        throw new Error(`Default template not found at ${defaultPath}. ` +
+            `Create .docspec/docspec.md in your project or ensure the docspec package is installed correctly.`);
+    }
+    fs.mkdirSync(path.join(cwd, ".docspec"), { recursive: true });
+    fs.copyFileSync(defaultPath, userPath);
+    logger_1.logger.debug(`Seeded ${userPath}`);
+    return userPath;
+}
+/**
+ * Get the path to the format file. Uses .docspec/docspec.md in cwd.
+ * If it doesn't exist, seeds it from the bundled docspec-format.md and returns the new path.
+ */
+function getFormatFilePath() {
+    const cwd = process.cwd();
+    const userPath = path.join(cwd, ".docspec", "docspec.md");
+    if (fs.existsSync(userPath)) {
+        logger_1.logger.debug(`Format file found: ${userPath}`);
+        return userPath;
+    }
+    logger_1.logger.debug(`Format file not found at ${userPath}, seeding from default`);
+    return seedDefaultFormatFile();
+}
+//# sourceMappingURL=format-parser.js.map