lightspec 0.1.1

package/dist/core/specs-apply.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Spec Application Logic
+ *
+ * Extracted from ArchiveCommand to enable standalone spec application.
+ * Applies delta specs from a change to main specs without archiving.
+ */
+export interface SpecUpdate {
+    source: string;
+    target: string;
+    exists: boolean;
+}
+export interface ApplyResult {
+    capability: string;
+    added: number;
+    modified: number;
+    removed: number;
+    renamed: number;
+}
+export interface SpecsApplyOutput {
+    changeName: string;
+    capabilities: ApplyResult[];
+    totals: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+    noChanges: boolean;
+}
+/**
+ * Find all delta spec files that need to be applied from a change.
+ */
+export declare function findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]>;
+/**
+ * Build an updated spec by applying delta operations.
+ * Returns the rebuilt content and counts of operations.
+ */
+export declare function buildUpdatedSpec(update: SpecUpdate, changeName: string): Promise<{
+    rebuilt: string;
+    counts: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+}>;
+/**
+ * Write an updated spec to disk.
+ */
+export declare function writeUpdatedSpec(update: SpecUpdate, rebuilt: string, counts: {
+    added: number;
+    modified: number;
+    removed: number;
+    renamed: number;
+}): Promise<void>;
+/**
+ * Build a skeleton spec for new capabilities.
+ */
+export declare function buildSpecSkeleton(specFolderName: string, changeName: string): string;
+/**
+ * Apply all delta specs from a change to main specs.
+ *
+ * @param projectRoot - The project root directory
+ * @param changeName - The name of the change to apply
+ * @param options - Options for the operation
+ * @returns Result of the operation with counts
+ */
+export declare function applySpecs(projectRoot: string, changeName: string, options?: {
+    dryRun?: boolean;
+    skipValidation?: boolean;
+    silent?: boolean;
+}): Promise<SpecsApplyOutput>;
+//# sourceMappingURL=specs-apply.d.ts.map

package/dist/core/specs-apply.js

@@ -0,0 +1,384 @@
+/**
+ * Spec Application Logic
+ *
+ * Extracted from ArchiveCommand to enable standalone spec application.
+ * Applies delta specs from a change to main specs without archiving.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { Validator } from './validation/validator.js';
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * Find all delta spec files that need to be applied from a change.
+ */
+export async function findSpecUpdates(changeDir, mainSpecsDir) {
+    const updates = [];
+    const changeSpecsDir = path.join(changeDir, 'specs');
+    try {
+        const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+                const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
+                try {
+                    await fs.access(specFile);
+                    // Check if target exists
+                    let exists = false;
+                    try {
+                        await fs.access(targetFile);
+                        exists = true;
+                    }
+                    catch {
+                        exists = false;
+                    }
+                    updates.push({
+                        source: specFile,
+                        target: targetFile,
+                        exists,
+                    });
+                }
+                catch {
+                    // Source spec doesn't exist, skip
+                }
+            }
+        }
+    }
+    catch {
+        // No specs directory in change
+    }
+    return updates;
+}
+/**
+ * Build an updated spec by applying delta operations.
+ * Returns the rebuilt content and counts of operations.
+ */
+export async function buildUpdatedSpec(update, changeName) {
+    // Read change spec content (delta-format expected)
+    const changeContent = await fs.readFile(update.source, 'utf-8');
+    // Parse deltas from the change spec file
+    const plan = parseDeltaSpec(changeContent);
+    const specName = path.basename(path.dirname(update.target));
+    // Pre-validate duplicates within sections
+    const addedNames = new Set();
+    for (const add of plan.added) {
+        const name = normalizeRequirementName(add.name);
+        if (addedNames.has(name)) {
+            throw new Error(`${specName} validation failed - duplicate requirement in ADDED for header "### Requirement: ${add.name}"`);
+        }
+        addedNames.add(name);
+    }
+    const modifiedNames = new Set();
+    for (const mod of plan.modified) {
+        const name = normalizeRequirementName(mod.name);
+        if (modifiedNames.has(name)) {
+            throw new Error(`${specName} validation failed - duplicate requirement in MODIFIED for header "### Requirement: ${mod.name}"`);
+        }
+        modifiedNames.add(name);
+    }
+    const removedNamesSet = new Set();
+    for (const rem of plan.removed) {
+        const name = normalizeRequirementName(rem);
+        if (removedNamesSet.has(name)) {
+            throw new Error(`${specName} validation failed - duplicate requirement in REMOVED for header "### Requirement: ${rem}"`);
+        }
+        removedNamesSet.add(name);
+    }
+    const renamedFromSet = new Set();
+    const renamedToSet = new Set();
+    for (const { from, to } of plan.renamed) {
+        const fromNorm = normalizeRequirementName(from);
+        const toNorm = normalizeRequirementName(to);
+        if (renamedFromSet.has(fromNorm)) {
+            throw new Error(`${specName} validation failed - duplicate FROM in RENAMED for header "### Requirement: ${from}"`);
+        }
+        if (renamedToSet.has(toNorm)) {
+            throw new Error(`${specName} validation failed - duplicate TO in RENAMED for header "### Requirement: ${to}"`);
+        }
+        renamedFromSet.add(fromNorm);
+        renamedToSet.add(toNorm);
+    }
+    // Pre-validate cross-section conflicts
+    const conflicts = [];
+    for (const n of modifiedNames) {
+        if (removedNamesSet.has(n))
+            conflicts.push({ name: n, a: 'MODIFIED', b: 'REMOVED' });
+        if (addedNames.has(n))
+            conflicts.push({ name: n, a: 'MODIFIED', b: 'ADDED' });
+    }
+    for (const n of addedNames) {
+        if (removedNamesSet.has(n))
+            conflicts.push({ name: n, a: 'ADDED', b: 'REMOVED' });
+    }
+    // Renamed interplay: MODIFIED must reference the NEW header, not FROM
+    for (const { from, to } of plan.renamed) {
+        const fromNorm = normalizeRequirementName(from);
+        const toNorm = normalizeRequirementName(to);
+        if (modifiedNames.has(fromNorm)) {
+            throw new Error(`${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`);
+        }
+        // Detect ADDED colliding with a RENAMED TO
+        if (addedNames.has(toNorm)) {
+            throw new Error(`${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"`);
+        }
+    }
+    if (conflicts.length > 0) {
+        const c = conflicts[0];
+        throw new Error(`${specName} validation failed - requirement present in multiple sections (${c.a} and ${c.b}) for header "### Requirement: ${c.name}"`);
+    }
+    const hasAnyDelta = plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length > 0;
+    if (!hasAnyDelta) {
+        throw new Error(`Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
+            `Provide ADDED/MODIFIED/REMOVED/RENAMED sections in change spec.`);
+    }
+    // Load or create base target content
+    let targetContent;
+    let isNewSpec = false;
+    try {
+        targetContent = await fs.readFile(update.target, 'utf-8');
+    }
+    catch {
+        // Target spec does not exist; MODIFIED and RENAMED are not allowed for new specs
+        // REMOVED will be ignored with a warning since there's nothing to remove
+        if (plan.modified.length > 0 || plan.renamed.length > 0) {
+            throw new Error(`${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.`);
+        }
+        // Warn about REMOVED requirements being ignored for new specs
+        if (plan.removed.length > 0) {
+            console.log(chalk.yellow(`⚠️  Warning: ${specName} - ${plan.removed.length} REMOVED requirement(s) ignored for new spec (nothing to remove).`));
+        }
+        isNewSpec = true;
+        targetContent = buildSpecSkeleton(specName, changeName);
+    }
+    // Extract requirements section and build name->block map
+    const parts = extractRequirementsSection(targetContent);
+    const nameToBlock = new Map();
+    for (const block of parts.bodyBlocks) {
+        nameToBlock.set(normalizeRequirementName(block.name), block);
+    }
+    // Apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED
+    // RENAMED
+    for (const r of plan.renamed) {
+        const from = normalizeRequirementName(r.from);
+        const to = normalizeRequirementName(r.to);
+        if (!nameToBlock.has(from)) {
+            throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found`);
+        }
+        if (nameToBlock.has(to)) {
+            throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`);
+        }
+        const block = nameToBlock.get(from);
+        const newHeader = `### Requirement: ${to}`;
+        const rawLines = block.raw.split('\n');
+        rawLines[0] = newHeader;
+        const renamedBlock = {
+            headerLine: newHeader,
+            name: to,
+            raw: rawLines.join('\n'),
+        };
+        nameToBlock.delete(from);
+        nameToBlock.set(to, renamedBlock);
+    }
+    // REMOVED
+    for (const name of plan.removed) {
+        const key = normalizeRequirementName(name);
+        if (!nameToBlock.has(key)) {
+            // For new specs, REMOVED requirements are already warned about and ignored
+            // For existing specs, missing requirements are an error
+            if (!isNewSpec) {
+                throw new Error(`${specName} REMOVED failed for header "### Requirement: ${name}" - not found`);
+            }
+            // Skip removal for new specs (already warned above)
+            continue;
+        }
+        nameToBlock.delete(key);
+    }
+    // MODIFIED
+    for (const mod of plan.modified) {
+        const key = normalizeRequirementName(mod.name);
+        if (!nameToBlock.has(key)) {
+            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
+        }
+        // Replace block with provided raw (ensure header line matches key)
+        const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/);
+        if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
+            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
+        }
+        nameToBlock.set(key, mod);
+    }
+    // ADDED
+    for (const add of plan.added) {
+        const key = normalizeRequirementName(add.name);
+        if (nameToBlock.has(key)) {
+            throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`);
+        }
+        nameToBlock.set(key, add);
+    }
+    // Duplicates within resulting map are implicitly prevented by key uniqueness.
+    // Recompose requirements section preserving original ordering where possible
+    const keptOrder = [];
+    const seen = new Set();
+    for (const block of parts.bodyBlocks) {
+        const key = normalizeRequirementName(block.name);
+        const replacement = nameToBlock.get(key);
+        if (replacement) {
+            keptOrder.push(replacement);
+            seen.add(key);
+        }
+    }
+    // Append any newly added that were not in original order
+    for (const [key, block] of nameToBlock.entries()) {
+        if (!seen.has(key)) {
+            keptOrder.push(block);
+        }
+    }
+    const reqBody = [parts.preamble && parts.preamble.trim() ? parts.preamble.trimEnd() : '']
+        .filter(Boolean)
+        .concat(keptOrder.map((b) => b.raw))
+        .join('\n\n')
+        .trimEnd();
+    const rebuilt = [parts.before.trimEnd(), parts.headerLine, reqBody, parts.after]
+        .filter((s, idx) => !(idx === 0 && s === ''))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n');
+    return {
+        rebuilt,
+        counts: {
+            added: plan.added.length,
+            modified: plan.modified.length,
+            removed: plan.removed.length,
+            renamed: plan.renamed.length,
+        },
+    };
+}
+/**
+ * Write an updated spec to disk.
+ */
+export async function writeUpdatedSpec(update, rebuilt, counts) {
+    // Create target directory if needed
+    const targetDir = path.dirname(update.target);
+    await fs.mkdir(targetDir, { recursive: true });
+    await fs.writeFile(update.target, rebuilt);
+    const specName = path.basename(path.dirname(update.target));
+    console.log(`Applying changes to lightspec/specs/${specName}/spec.md:`);
+    if (counts.added)
+        console.log(`  + ${counts.added} added`);
+    if (counts.modified)
+        console.log(`  ~ ${counts.modified} modified`);
+    if (counts.removed)
+        console.log(`  - ${counts.removed} removed`);
+    if (counts.renamed)
+        console.log(`  → ${counts.renamed} renamed`);
+}
+/**
+ * Build a skeleton spec for new capabilities.
+ */
+export function buildSpecSkeleton(specFolderName, changeName) {
+    const titleBase = specFolderName;
+    return `# ${titleBase} Specification\n\n## Purpose\nTBD - created by archiving change ${changeName}. Update Purpose after archive.\n\n## Requirements\n`;
+}
+/**
+ * Apply all delta specs from a change to main specs.
+ *
+ * @param projectRoot - The project root directory
+ * @param changeName - The name of the change to apply
+ * @param options - Options for the operation
+ * @returns Result of the operation with counts
+ */
+export async function applySpecs(projectRoot, changeName, options = {}) {
+    const changeDir = path.join(projectRoot, 'lightspec', 'changes', changeName);
+    const mainSpecsDir = path.join(projectRoot, 'lightspec', 'specs');
+    // Verify change exists
+    try {
+        const stat = await fs.stat(changeDir);
+        if (!stat.isDirectory()) {
+            throw new Error(`Change '${changeName}' not found.`);
+        }
+    }
+    catch {
+        throw new Error(`Change '${changeName}' not found.`);
+    }
+    // Find specs to update
+    const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
+    if (specUpdates.length === 0) {
+        return {
+            changeName,
+            capabilities: [],
+            totals: { added: 0, modified: 0, removed: 0, renamed: 0 },
+            noChanges: true,
+        };
+    }
+    // Prepare all updates first (validation pass, no writes)
+    const prepared = [];
+    for (const update of specUpdates) {
+        const built = await buildUpdatedSpec(update, changeName);
+        prepared.push({ update, rebuilt: built.rebuilt, counts: built.counts });
+    }
+    // Validate rebuilt specs unless validation is skipped
+    if (!options.skipValidation) {
+        const validator = new Validator();
+        for (const p of prepared) {
+            const specName = path.basename(path.dirname(p.update.target));
+            const report = await validator.validateSpecContent(specName, p.rebuilt);
+            if (!report.valid) {
+                const errors = report.issues
+                    .filter((i) => i.level === 'ERROR')
+                    .map((i) => `  ✗ ${i.message}`)
+                    .join('\n');
+                throw new Error(`Validation errors in rebuilt spec for ${specName}:\n${errors}`);
+            }
+        }
+    }
+    // Build results
+    const capabilities = [];
+    const totals = { added: 0, modified: 0, removed: 0, renamed: 0 };
+    for (const p of prepared) {
+        const capability = path.basename(path.dirname(p.update.target));
+        if (!options.dryRun) {
+            // Write the updated spec
+            const targetDir = path.dirname(p.update.target);
+            await fs.mkdir(targetDir, { recursive: true });
+            await fs.writeFile(p.update.target, p.rebuilt);
+            if (!options.silent) {
+                console.log(`Applying changes to lightspec/specs/${capability}/spec.md:`);
+                if (p.counts.added)
+                    console.log(`  + ${p.counts.added} added`);
+                if (p.counts.modified)
+                    console.log(`  ~ ${p.counts.modified} modified`);
+                if (p.counts.removed)
+                    console.log(`  - ${p.counts.removed} removed`);
+                if (p.counts.renamed)
+                    console.log(`  → ${p.counts.renamed} renamed`);
+            }
+        }
+        else if (!options.silent) {
+            console.log(`Would apply changes to lightspec/specs/${capability}/spec.md:`);
+            if (p.counts.added)
+                console.log(`  + ${p.counts.added} added`);
+            if (p.counts.modified)
+                console.log(`  ~ ${p.counts.modified} modified`);
+            if (p.counts.removed)
+                console.log(`  - ${p.counts.removed} removed`);
+            if (p.counts.renamed)
+                console.log(`  → ${p.counts.renamed} renamed`);
+        }
+        capabilities.push({
+            capability,
+            ...p.counts,
+        });
+        totals.added += p.counts.added;
+        totals.modified += p.counts.modified;
+        totals.removed += p.counts.removed;
+        totals.renamed += p.counts.renamed;
+    }
+    return {
+        changeName,
+        capabilities,
+        totals,
+        noChanges: false,
+    };
+}
+//# sourceMappingURL=specs-apply.js.map

package/dist/core/styles/palette.d.ts

@@ -0,0 +1,7 @@
+export declare const PALETTE: {
+    white: import("chalk").ChalkInstance;
+    lightGray: import("chalk").ChalkInstance;
+    midGray: import("chalk").ChalkInstance;
+    darkGray: import("chalk").ChalkInstance;
+};
+//# sourceMappingURL=palette.d.ts.map

package/dist/core/styles/palette.js

@@ -0,0 +1,8 @@
+import chalk from 'chalk';
+export const PALETTE = {
+    white: chalk.hex('#f4f4f4'),
+    lightGray: chalk.hex('#c8c8c8'),
+    midGray: chalk.hex('#8a8a8a'),
+    darkGray: chalk.hex('#4a4a4a')
+};
+//# sourceMappingURL=palette.js.map

package/dist/core/templates/agents-root-stub.d.ts

@@ -0,0 +1,2 @@
+export declare const agentsRootStubTemplate = "# LightSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\nAlways open `@/lightspec/AGENTS.md` when the request:\n- Mentions planning or proposals (words like proposal, spec, change, plan)\n- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work\n- Sounds ambiguous and you need the authoritative spec before coding\n\nUse `@/lightspec/AGENTS.md` to learn:\n- How to create and apply change proposals\n- Spec format and conventions\n- Project structure and guidelines\n\nKeep this managed block so 'lightspec update' can refresh the instructions.\n";
+//# sourceMappingURL=agents-root-stub.d.ts.map

package/dist/core/templates/agents-root-stub.js

@@ -0,0 +1,17 @@
+export const agentsRootStubTemplate = `# LightSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open \`@/lightspec/AGENTS.md\` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use \`@/lightspec/AGENTS.md\` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'lightspec update' can refresh the instructions.
+`;
+//# sourceMappingURL=agents-root-stub.js.map

package/dist/core/templates/agents-template.d.ts

@@ -0,0 +1,2 @@
+export declare const agentsTemplate = "# LightSpec Instructions\n\nInstructions for AI coding assistants using LightSpec for spec-driven development.\n\n## TL;DR Quick Checklist\n\n- Search existing work: `lightspec spec list --long`, `lightspec list` (use `rg` only for full-text search)\n- Decide scope: new capability vs modify existing capability\n- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)\n- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability\n- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement\n- Validate: `lightspec validate [change-id] --strict --no-interactive` and fix issues\n- Request approval: Do not start implementation until proposal is approved\n\n## Three-Stage Workflow\n\n### Stage 1: Creating Changes\nCreate proposal when you need to:\n- Add features or functionality\n- Make breaking changes (API, schema)\n- Change architecture or patterns  \n- Optimize performance (changes behavior)\n- Update security patterns\n\nTriggers (examples):\n- \"Help me create a change proposal\"\n- \"Help me plan a change\"\n- \"Help me create a proposal\"\n- \"I want to create a spec proposal\"\n- \"I want to create a spec\"\n\nLoose matching guidance:\n- Contains one of: `proposal`, `change`, `spec`\n- With one of: `create`, `plan`, `make`, `start`, `help`\n\nSkip proposal for:\n- Bug fixes (restore intended behavior)\n- Typos, formatting, comments\n- Dependency updates (non-breaking)\n- Configuration changes\n- Tests for existing behavior\n\n**Workflow**\n1. Review `lightspec/project.md`, `lightspec list`, and `lightspec list --specs` to understand current context.\n2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `lightspec/changes/<id>/`.\n3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.\n4. Run `lightspec validate <id> --strict --no-interactive` and resolve any issues before sharing the proposal.\n\n### Stage 2: Implementing Changes\nTrack these steps as TODOs and complete them one by one.\n1. **Read proposal.md** - Understand what's being built\n2. **Read design.md** (if exists) - Review technical decisions\n3. **Read tasks.md** - Get implementation checklist\n4. **Implement tasks sequentially** - Complete in order\n5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses\n6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality\n7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved\n\n### Stage 3: Archiving Changes\nAfter deployment, create separate PR to:\n- Move `changes/[name]/` \u2192 `changes/archive/YYYY-MM-DD-[name]/`\n- Update `specs/` if capabilities changed\n- Use `lightspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)\n- Run `lightspec validate --strict --no-interactive` to confirm the archived change passes checks\n\n## Before Any Task\n\n**Context Checklist:**\n- [ ] Read relevant specs in `specs/[capability]/spec.md`\n- [ ] Check pending changes in `changes/` for conflicts\n- [ ] Read `lightspec/project.md` for conventions\n- [ ] Run `lightspec list` to see active changes\n- [ ] Run `lightspec list --specs` to see existing capabilities\n\n**Before Creating Specs:**\n- Always check if capability already exists\n- Prefer modifying existing specs over creating duplicates\n- Use `lightspec show [spec]` to review current state\n- If request is ambiguous, ask 1\u20132 clarifying questions before scaffolding\n\n### Search Guidance\n- Enumerate specs: `lightspec spec list --long` (or `--json` for scripts)\n- Enumerate changes: `lightspec list` (or `lightspec change list --json` - deprecated but available)\n- Show details:\n  - Spec: `lightspec show <spec-id> --type spec` (use `--json` for filters)\n  - Change: `lightspec show <change-id> --json --deltas-only`\n- Full-text search (use ripgrep): `rg -n \"Requirement:|Scenario:\" lightspec/specs`\n\n## Quick Start\n\n### CLI Commands\n\n```bash\n# Essential commands\nlightspec list                  # List active changes\nlightspec list --specs          # List specifications\nlightspec show [item]           # Display change or spec\nlightspec validate [item]       # Validate changes or specs\nlightspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)\n\n# Project management\nlightspec init [path]           # Initialize LightSpec\nlightspec update [path]         # Update instruction files\n\n# Interactive mode\nlightspec show                  # Prompts for selection\nlightspec validate              # Bulk validation mode\n\n# Debugging\nlightspec show [change] --json --deltas-only\nlightspec validate [change] --strict --no-interactive\n```\n\n### Command Flags\n\n- `--json` - Machine-readable output\n- `--type change|spec` - Disambiguate items\n- `--strict` - Comprehensive validation\n- `--no-interactive` - Disable prompts\n- `--skip-specs` - Archive without spec updates\n- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)\n\n## Directory Structure\n\n```\nlightspec/\n\u251C\u2500\u2500 project.md              # Project conventions\n\u251C\u2500\u2500 specs/                  # Current truth - what IS built\n\u2502   \u2514\u2500\u2500 [capability]/       # Single focused capability\n\u2502       \u251C\u2500\u2500 spec.md         # Requirements and scenarios\n\u2502       \u2514\u2500\u2500 design.md       # Technical patterns\n\u251C\u2500\u2500 changes/                # Proposals - what SHOULD change\n\u2502   \u251C\u2500\u2500 [change-name]/\n\u2502   \u2502   \u251C\u2500\u2500 proposal.md     # Why, what, impact\n\u2502   \u2502   \u251C\u2500\u2500 tasks.md        # Implementation checklist\n\u2502   \u2502   \u251C\u2500\u2500 design.md       # Technical decisions (optional; see criteria)\n\u2502   \u2502   \u2514\u2500\u2500 specs/          # Delta changes\n\u2502   \u2502       \u2514\u2500\u2500 [capability]/\n\u2502   \u2502           \u2514\u2500\u2500 spec.md # ADDED/MODIFIED/REMOVED\n\u2502   \u2514\u2500\u2500 archive/            # Completed changes\n```\n\n## Creating Change Proposals\n\n### Decision Tree\n\n```\nNew request?\n\u251C\u2500 Bug fix restoring spec behavior? \u2192 Fix directly\n\u251C\u2500 Typo/format/comment? \u2192 Fix directly  \n\u251C\u2500 New feature/capability? \u2192 Create proposal\n\u251C\u2500 Breaking change? \u2192 Create proposal\n\u251C\u2500 Architecture change? \u2192 Create proposal\n\u2514\u2500 Unclear? \u2192 Create proposal (safer)\n```\n\n### Proposal Structure\n\n1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)\n\n2. **Write proposal.md:**\n```markdown\n# Change: [Brief description of change]\n\n## Why\n[1-2 sentences on problem/opportunity]\n\n## What Changes\n- [Bullet list of changes]\n- [Mark breaking changes with **BREAKING**]\n\n## Impact\n- Affected specs: [list capabilities]\n- Affected code: [key files/systems]\n```\n\n3. **Create spec deltas:** `specs/[capability]/spec.md`\n```markdown\n## ADDED Requirements\n### Requirement: New Feature\nThe system SHALL provide...\n\n#### Scenario: Success case\n- **WHEN** user performs action\n- **THEN** expected result\n\n## MODIFIED Requirements\n### Requirement: Existing Feature\n[Complete modified requirement]\n\n## REMOVED Requirements\n### Requirement: Old Feature\n**Reason**: [Why removing]\n**Migration**: [How to handle]\n```\nIf multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`\u2014one per capability.\n\n4. **Create tasks.md:**\n```markdown\n## 1. Implementation\n- [ ] 1.1 Create database schema\n- [ ] 1.2 Implement API endpoint\n- [ ] 1.3 Add frontend component\n- [ ] 1.4 Write tests\n```\n\n5. **Create design.md when needed:**\nCreate `design.md` if any of the following apply; otherwise omit it:\n- Cross-cutting change (multiple services/modules) or a new architectural pattern\n- New external dependency or significant data model changes\n- Security, performance, or migration complexity\n- Ambiguity that benefits from technical decisions before coding\n\nMinimal `design.md` skeleton:\n```markdown\n## Context\n[Background, constraints, stakeholders]\n\n## Goals / Non-Goals\n- Goals: [...]\n- Non-Goals: [...]\n\n## Decisions\n- Decision: [What and why]\n- Alternatives considered: [Options + rationale]\n\n## Risks / Trade-offs\n- [Risk] \u2192 Mitigation\n\n## Migration Plan\n[Steps, rollback]\n\n## Open Questions\n- [...]\n```\n\n## Spec File Format\n\n### Critical: Scenario Formatting\n\n**CORRECT** (use #### headers):\n```markdown\n#### Scenario: User login success\n- **WHEN** valid credentials provided\n- **THEN** return JWT token\n```\n\n**WRONG** (don't use bullets or bold):\n```markdown\n- **Scenario: User login**  \u274C\n**Scenario**: User login     \u274C\n### Scenario: User login      \u274C\n```\n\nEvery requirement MUST have at least one scenario.\n\n### Requirement Wording\n- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)\n\n### Delta Operations\n\n- `## ADDED Requirements` - New capabilities\n- `## MODIFIED Requirements` - Changed behavior\n- `## REMOVED Requirements` - Deprecated features\n- `## RENAMED Requirements` - Name changes\n\nHeaders matched with `trim(header)` - whitespace ignored.\n\n#### When to use ADDED vs MODIFIED\n- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding \"Slash Command Configuration\") rather than altering the semantics of an existing requirement.\n- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.\n- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.\n\nCommon pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren\u2019t explicitly changing the existing requirement, add a new requirement under ADDED instead.\n\nAuthoring a MODIFIED requirement correctly:\n1) Locate the existing requirement in `lightspec/specs/<capability>/spec.md`.\n2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).\n3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.\n4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.\n\nExample for RENAMED:\n```markdown\n## RENAMED Requirements\n- FROM: `### Requirement: Login`\n- TO: `### Requirement: User Authentication`\n```\n\n## Troubleshooting\n\n### Common Errors\n\n**\"Change must have at least one delta\"**\n- Check `changes/[name]/specs/` exists with .md files\n- Verify files have operation prefixes (## ADDED Requirements)\n\n**\"Requirement must have at least one scenario\"**\n- Check scenarios use `#### Scenario:` format (4 hashtags)\n- Don't use bullet points or bold for scenario headers\n\n**Silent scenario parsing failures**\n- Exact format required: `#### Scenario: Name`\n- Debug with: `lightspec show [change] --json --deltas-only`\n\n### Validation Tips\n\n```bash\n# Always use strict mode for comprehensive checks\nlightspec validate [change] --strict --no-interactive\n\n# Debug delta parsing\nlightspec show [change] --json | jq '.deltas'\n\n# Check specific requirement\nlightspec show [spec] --json -r 1\n```\n\n## Happy Path Script\n\n```bash\n# 1) Explore current state\nlightspec spec list --long\nlightspec list\n# Optional full-text search:\n# rg -n \"Requirement:|Scenario:\" lightspec/specs\n# rg -n \"^#|Requirement:\" lightspec/changes\n\n# 2) Choose change id and scaffold\nCHANGE=add-two-factor-auth\nmkdir -p lightspec/changes/$CHANGE/{specs/auth}\nprintf \"## Why\\n...\\n\\n## What Changes\\n- ...\\n\\n## Impact\\n- ...\\n\" > lightspec/changes/$CHANGE/proposal.md\nprintf \"## 1. Implementation\\n- [ ] 1.1 ...\\n\" > lightspec/changes/$CHANGE/tasks.md\n\n# 3) Add deltas (example)\ncat > lightspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'\n## ADDED Requirements\n### Requirement: Two-Factor Authentication\nUsers MUST provide a second factor during login.\n\n#### Scenario: OTP required\n- **WHEN** valid credentials are provided\n- **THEN** an OTP challenge is required\nEOF\n\n# 4) Validate\nlightspec validate $CHANGE --strict --no-interactive\n```\n\n## Multi-Capability Example\n\n```\nlightspec/changes/add-2fa-notify/\n\u251C\u2500\u2500 proposal.md\n\u251C\u2500\u2500 tasks.md\n\u2514\u2500\u2500 specs/\n    \u251C\u2500\u2500 auth/\n    \u2502   \u2514\u2500\u2500 spec.md   # ADDED: Two-Factor Authentication\n    \u2514\u2500\u2500 notifications/\n        \u2514\u2500\u2500 spec.md   # ADDED: OTP email notification\n```\n\nauth/spec.md\n```markdown\n## ADDED Requirements\n### Requirement: Two-Factor Authentication\n...\n```\n\nnotifications/spec.md\n```markdown\n## ADDED Requirements\n### Requirement: OTP Email Notification\n...\n```\n\n## Best Practices\n\n### Simplicity First\n- Default to <100 lines of new code\n- Single-file implementations until proven insufficient\n- Avoid frameworks without clear justification\n- Choose boring, proven patterns\n\n### Complexity Triggers\nOnly add complexity with:\n- Performance data showing current solution too slow\n- Concrete scale requirements (>1000 users, >100MB data)\n- Multiple proven use cases requiring abstraction\n\n### Clear References\n- Use `file.ts:42` format for code locations\n- Reference specs as `specs/auth/spec.md`\n- Link related changes and PRs\n\n### Capability Naming\n- Use verb-noun: `user-auth`, `payment-capture`\n- Single purpose per capability\n- 10-minute understandability rule\n- Split if description needs \"AND\"\n\n### Change ID Naming\n- Use kebab-case, short and descriptive: `add-two-factor-auth`\n- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`\n- Ensure uniqueness; if taken, append `-2`, `-3`, etc.\n\n## Tool Selection Guide\n\n| Task | Tool | Why |\n|------|------|-----|\n| Find files by pattern | Glob | Fast pattern matching |\n| Search code content | Grep | Optimized regex search |\n| Read specific files | Read | Direct file access |\n| Explore unknown scope | Task | Multi-step investigation |\n\n## Error Recovery\n\n### Change Conflicts\n1. Run `lightspec list` to see active changes\n2. Check for overlapping specs\n3. Coordinate with change owners\n4. Consider combining proposals\n\n### Validation Failures\n1. Run with `--strict` flag\n2. Check JSON output for details\n3. Verify spec file format\n4. Ensure scenarios properly formatted\n\n### Missing Context\n1. Read project.md first\n2. Check related specs\n3. Review recent archives\n4. Ask for clarification\n\n## Quick Reference\n\n### Stage Indicators\n- `changes/` - Proposed, not yet built\n- `specs/` - Built and deployed\n- `archive/` - Completed changes\n\n### File Purposes\n- `proposal.md` - Why and what\n- `tasks.md` - Implementation steps\n- `design.md` - Technical decisions\n- `spec.md` - Requirements and behavior\n\n### CLI Essentials\n```bash\nlightspec list              # What's in progress?\nlightspec show [item]       # View details\nlightspec validate --strict --no-interactive  # Is it correct?\nlightspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)\n```\n\nRemember: Specs are truth. Changes are proposals. Keep them in sync.\n";
+//# sourceMappingURL=agents-template.d.ts.map