lightspec 0.2.2 → 0.3.0

package/dist/core/configurators/skills/base.d.ts

@@ -0,0 +1,27 @@
+import { AgentSkillId } from '../../templates/index.js';
+export interface AgentSkillTarget {
+    id: AgentSkillId;
+    path: string;
+    kind: 'skill';
+}
+export type SkillInstallLocation = 'project' | 'home';
+export declare const AGENT_SKILL_TOOL_IDS: readonly string[];
+export declare class AgentSkillConfigurator {
+    readonly toolId: string;
+    readonly isAvailable: boolean;
+    private installLocation;
+    constructor(toolId: string, isAvailable?: boolean);
+    setInstallLocation(location: SkillInstallLocation): void;
+    getTargets(): AgentSkillTarget[];
+    generateAll(projectPath: string, _lightspecDir: string): Promise<string[]>;
+    updateExisting(projectPath: string, _lightspecDir: string): Promise<string[]>;
+    protected getBody(id: AgentSkillId): string;
+    resolveAbsolutePath(projectPath: string, id: AgentSkillId): string;
+    private getRelativeSkillPath;
+    private getToolRoot;
+    private getHomeRootPath;
+    private getSkillName;
+    private buildSkillFile;
+    protected updateBody(filePath: string, body: string): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/core/configurators/{slash → skills}/base.js

@@ -1,10 +1,9 @@
 import os from 'os';
 import path from 'path';
-import { promises as fs } from 'fs';
 import { FileSystemUtils } from '../../../utils/file-system.js';
 import { TemplateManager } from '../../templates/index.js';
 import { LIGHTSPEC_MARKERS } from '../../config.js';
-const ALL_COMMANDS = ['proposal', 'apply', 'archive', 'context-check'];
+const ALL_SKILL_IDS = ['proposal', 'apply', 'archive', 'context-check'];
 const TOOL_SKILL_ROOTS = {
     'amazon-q': '.amazonq',
     antigravity: '.antigravity',
@@ -29,37 +28,26 @@ const TOOL_SKILL_ROOTS = {
     roocode: '.roocode',
     windsurf: '.windsurf',
 };
-const TOOL_LEGACY_DIRS = {
-    'amazon-q': ['.amazonq/prompts', '.aws/amazonq/commands'],
-    antigravity: ['.antigravity/commands', '.agent/workflows'],
-    auggie: ['.augment/commands', '.auggie/commands'],
-    claude: ['.claude/commands'],
-    cline: ['.cline/commands', '.clinerules/workflows'],
-    codex: ['.codex/prompts'],
-    codebuddy: ['.codebuddy/commands'],
-    continue: ['.continue/prompts', '.continue/commands'],
-    costrict: ['.cospec/lightspec/commands'],
-    crush: ['.crush/commands'],
-    cursor: ['.cursor/commands'],
-    factory: ['.factory/commands'],
-    gemini: ['.gemini/commands'],
-    'github-copilot': ['.github/prompts', '.github/copilot/prompts'],
-    iflow: ['.iflow/commands'],
-    kilocode: ['.kilocode/commands', '.kilocode/workflows'],
-    'mistral-vibe': ['.vibe/commands', '.vibe/workflows', '.vibe/prompts'],
-    opencode: ['.opencode/command', '.opencode/commands'],
-    qoder: ['.qoder/commands', '.qoder/prompts'],
-    qwen: ['.qwen/commands', '.qwen/prompts'],
-    roocode: ['.roo/commands', '.roocode/commands'],
-    windsurf: ['.windsurf/workflows', '.windsurf/commands'],
+export const AGENT_SKILL_TOOL_IDS = Object.freeze(Object.keys(TOOL_SKILL_ROOTS));
+const TOOL_BODY_SUFFIX = {
+    factory: '\n\n$ARGUMENTS',
 };
-export class SlashCommandConfigurator {
+export class AgentSkillConfigurator {
+    toolId;
+    isAvailable;
     installLocation = 'project';
+    constructor(toolId, isAvailable = true) {
+        this.toolId = toolId;
+        this.isAvailable = isAvailable;
+        if (!TOOL_SKILL_ROOTS[this.toolId]) {
+            throw new Error(`No skill root directory configured for tool '${this.toolId}'`);
+        }
+    }
     setInstallLocation(location) {
         this.installLocation = location;
     }
     getTargets() {
-        return ALL_COMMANDS.map((id) => ({
+        return ALL_SKILL_IDS.map((id) => ({
             id,
             path: this.getRelativeSkillPath(id),
             kind: 'skill',
@@ -74,13 +62,12 @@ export class SlashCommandConfigurator {
                 await this.updateBody(filePath, body);
             }
             else {
-                const frontmatter = TemplateManager.getSlashCommandFrontmatter(target.id).trim();
+                const frontmatter = TemplateManager.getAgentSkillFrontmatter(target.id).trim();
                 const content = this.buildSkillFile(frontmatter, body);
                 await FileSystemUtils.writeFile(filePath, content);
             }
             createdOrUpdated.push(target.path);
         }
-        await this.cleanupLegacyArtifacts(projectPath);
         return createdOrUpdated;
     }
     async updateExisting(projectPath, _lightspecDir) {
@@ -93,11 +80,12 @@ export class SlashCommandConfigurator {
                 updated.push(target.path);
             }
         }
-        await this.cleanupLegacyArtifacts(projectPath);
         return updated;
     }
     getBody(id) {
-        return TemplateManager.getSlashCommandBody(id).trim();
+        const baseBody = TemplateManager.getAgentSkillBody(id).trim();
+        const suffix = TOOL_BODY_SUFFIX[this.toolId] ?? '';
+        return `${baseBody}${suffix}`;
     }
     resolveAbsolutePath(projectPath, id) {
         const relativePath = this.getRelativeSkillPath(id);
@@ -159,55 +147,5 @@ export class SlashCommandConfigurator {
         const updatedContent = `${before}\n${body}\n${after}`;
         await FileSystemUtils.writeFile(filePath, updatedContent);
     }
-    async cleanupLegacyArtifacts(projectPath) {
-        const legacyDirs = TOOL_LEGACY_DIRS[this.toolId] ?? [];
-        for (const legacyDir of legacyDirs) {
-            const absoluteDir = this.installLocation === 'project'
-                ? FileSystemUtils.joinPath(projectPath, legacyDir)
-                : FileSystemUtils.joinPath(this.getHomeRootPath(), this.relativeToToolRoot(legacyDir));
-            await this.removeLegacyLightSpecFiles(absoluteDir);
-        }
-    }
-    relativeToToolRoot(relativePath) {
-        const rootPrefix = this.getToolRoot();
-        const normalized = FileSystemUtils.toPosixPath(relativePath);
-        if (normalized.startsWith(`${rootPrefix}/`)) {
-            return normalized.slice(rootPrefix.length + 1);
-        }
-        if (normalized === rootPrefix) {
-            return '';
-        }
-        return normalized.startsWith('./') ? normalized.slice(2) : normalized;
-    }
-    async removeLegacyLightSpecFiles(dirPath) {
-        if (!(await FileSystemUtils.directoryExists(dirPath))) {
-            return;
-        }
-        await this.walkAndRemove(dirPath);
-    }
-    async walkAndRemove(currentPath) {
-        const entries = await fs.readdir(currentPath, { withFileTypes: true });
-        for (const entry of entries) {
-            const entryPath = path.join(currentPath, entry.name);
-            if (entry.isDirectory()) {
-                await this.walkAndRemove(entryPath);
-                continue;
-            }
-            if (this.isLegacyLightSpecFile(entryPath)) {
-                await fs.unlink(entryPath);
-            }
-        }
-    }
-    isLegacyLightSpecFile(filePath) {
-        const normalized = FileSystemUtils.toPosixPath(filePath).toLowerCase();
-        return (normalized.includes('/lightspec-proposal') ||
-            normalized.includes('/lightspec-apply') ||
-            normalized.includes('/lightspec-archive') ||
-            normalized.includes('/lightspec-context-check') ||
-            normalized.includes('/lightspec/proposal') ||
-            normalized.includes('/lightspec/apply') ||
-            normalized.includes('/lightspec/archive') ||
-            normalized.includes('/lightspec/context-check'));
-    }
 }
 //# sourceMappingURL=base.js.map

package/dist/core/configurators/skills/registry.d.ts

@@ -0,0 +1,9 @@
+import { AgentSkillConfigurator, SkillInstallLocation } from './base.js';
+export declare class AgentSkillRegistry {
+    private static configurators;
+    static register(configurator: AgentSkillConfigurator): void;
+    static get(toolId: string): AgentSkillConfigurator | undefined;
+    static getAll(): AgentSkillConfigurator[];
+    static setInstallLocation(location: SkillInstallLocation): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/configurators/skills/registry.js

@@ -0,0 +1,24 @@
+import { AGENT_SKILL_TOOL_IDS, AgentSkillConfigurator, } from './base.js';
+export class AgentSkillRegistry {
+    static configurators = new Map();
+    static {
+        for (const toolId of AGENT_SKILL_TOOL_IDS) {
+            this.configurators.set(toolId, new AgentSkillConfigurator(toolId));
+        }
+    }
+    static register(configurator) {
+        this.configurators.set(configurator.toolId, configurator);
+    }
+    static get(toolId) {
+        return this.configurators.get(toolId);
+    }
+    static getAll() {
+        return Array.from(this.configurators.values());
+    }
+    static setInstallLocation(location) {
+        for (const configurator of this.configurators.values()) {
+            configurator.setInstallLocation(location);
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/init.d.ts

@@ -1,4 +1,4 @@
-import { SkillInstallLocation } from './configurators/slash/base.js';
+import { SkillInstallLocation } from './configurators/skills/base.js';
 type ToolLabel = {
     primary: string;
     annotation?: string;

package/dist/core/init.js

@@ -6,7 +6,7 @@ import ora from 'ora';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
-import { SlashCommandRegistry } from './configurators/slash/registry.js';
+import { AgentSkillRegistry } from './configurators/skills/registry.js';
 import { AI_TOOLS, LIGHTSPEC_DIR_NAME, LIGHTSPEC_MARKERS, } from './config.js';
 import { PALETTE } from './styles/palette.js';
 const PROGRESS_SPINNER = {
@@ -282,7 +282,7 @@ export class InitCommand {
         this.renderBanner(extendMode);
         // Get configuration (after validation to avoid prompts if validation fails)
         const config = await this.getConfiguration(existingToolStates, extendMode);
-        SlashCommandRegistry.setInstallLocation(config.skillLocation);
+        AgentSkillRegistry.setInstallLocation(config.skillLocation);
         const availableTools = AI_TOOLS.filter((tool) => tool.available);
         const selectedIds = new Set(config.aiTools);
         const selectedTools = availableTools.filter((tool) => selectedIds.has(tool.value));
@@ -474,7 +474,7 @@ export class InitCommand {
             }
         };
         let hasConfigFile = false;
-        let hasSlashCommands = false;
+        let hasSkills = false;
         // Check if the tool has a config file with LightSpec markers
         const configFile = ToolRegistry.get(toolId)?.configFileName;
         if (configFile) {
@@ -482,24 +482,24 @@ export class InitCommand {
             hasConfigFile = (await FileSystemUtils.fileExists(configPath)) && (await fileHasMarkers(configPath));
         }
         // Check if any skill file exists with LightSpec markers
-        const slashConfigurator = SlashCommandRegistry.get(toolId);
-        if (slashConfigurator) {
-            for (const target of slashConfigurator.getTargets()) {
-                const absolute = slashConfigurator.resolveAbsolutePath(projectPath, target.id);
+        const skillConfigurator = AgentSkillRegistry.get(toolId);
+        if (skillConfigurator) {
+            for (const target of skillConfigurator.getTargets()) {
+                const absolute = skillConfigurator.resolveAbsolutePath(projectPath, target.id);
                 if ((await FileSystemUtils.fileExists(absolute)) && (await fileHasMarkers(absolute))) {
-                    hasSlashCommands = true;
+                    hasSkills = true;
                     break; // At least one file with markers is sufficient
                 }
             }
         }
         // Tool is only configured if BOTH exist with markers
-        // OR if the tool has no config file requirement (slash commands only)
-        // OR if the tool has no slash commands requirement (config file only)
+        // OR if the tool has no config file requirement (skills only)
+        // OR if the tool has no skill requirement (config file only)
         const hasConfigFileRequirement = configFile !== undefined;
-        const hasSkillRequirement = slashConfigurator !== undefined;
+        const hasSkillRequirement = skillConfigurator !== undefined;
         if (hasConfigFileRequirement && hasSkillRequirement) {
             // Both are required - both must be present with markers
-            return hasConfigFile && hasSlashCommands;
+            return hasConfigFile && hasSkills;
         }
         else if (hasConfigFileRequirement) {
             // Only config file required
@@ -507,7 +507,7 @@ export class InitCommand {
         }
         else if (hasSkillRequirement) {
             // Only skills required
-            return hasSlashCommands;
+            return hasSkills;
         }
         return false;
     }
@@ -552,9 +552,9 @@ export class InitCommand {
             if (configurator && configurator.isAvailable) {
                 await configurator.configure(projectPath, lightspecDir);
             }
-            const slashConfigurator = SlashCommandRegistry.get(toolId);
-            if (slashConfigurator && slashConfigurator.isAvailable) {
-                await slashConfigurator.generateAll(projectPath, lightspecDir);
+            const skillConfigurator = AgentSkillRegistry.get(toolId);
+            if (skillConfigurator && skillConfigurator.isAvailable) {
+                await skillConfigurator.generateAll(projectPath, lightspecDir);
             }
         }
         return rootStubStatus;

package/dist/core/templates/agent-skill-templates.d.ts

@@ -0,0 +1,6 @@
+export type AgentSkillId = 'proposal' | 'apply' | 'archive' | 'context-check';
+export declare const agentSkillBodies: Record<AgentSkillId, string>;
+export declare const agentSkillFrontmatter: Record<AgentSkillId, string>;
+export declare function getAgentSkillBody(id: AgentSkillId): string;
+export declare function getAgentSkillFrontmatter(id: AgentSkillId): string;
+//# sourceMappingURL=agent-skill-templates.d.ts.map

package/dist/core/templates/{slash-command-templates.js → agent-skill-templates.js}

@@ -2,22 +2,22 @@ import { applyTemplate, applyFrontmatter } from './apply-template.js';
 import { archiveTemplate, archiveFrontmatter } from './archive-template.js';
 import { proposalTemplate, proposalFrontmatter } from './proposal-template.js';
 import { contextCheckTemplate, contextCheckFrontmatter, } from './context-check-template.js';
-export const slashCommandBodies = {
+export const agentSkillBodies = {
     proposal: proposalTemplate,
     apply: applyTemplate,
     archive: archiveTemplate,
     'context-check': contextCheckTemplate,
 };
-export const slashCommandFrontmatter = {
+export const agentSkillFrontmatter = {
     proposal: proposalFrontmatter,
     apply: applyFrontmatter,
     archive: archiveFrontmatter,
     'context-check': contextCheckFrontmatter,
 };
-export function getSlashCommandBody(id) {
-    return slashCommandBodies[id];
+export function getAgentSkillBody(id) {
+    return agentSkillBodies[id];
 }
-export function getSlashCommandFrontmatter(id) {
-    return slashCommandFrontmatter[id];
+export function getAgentSkillFrontmatter(id) {
+    return agentSkillFrontmatter[id];
 }
-//# sourceMappingURL=slash-command-templates.js.map
+//# sourceMappingURL=agent-skill-templates.js.map

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

@@ -1,2 +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";
+export declare const agentsRootStubTemplate = "# LightSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\n- For complex features (new capability, breaking change, architecture/performance/security work), suggest switching to `/plan` mode if it's not already the case, then run `lightspec-proposal` before coding.\n- If unsure which skill to run, list installed skills in your assistant's `skills/` folder.\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

@@ -2,15 +2,8 @@ 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
+- For complex features (new capability, breaking change, architecture/performance/security work), suggest switching to \`/plan\` mode if it's not already the case, then run \`lightspec-proposal\` before coding.
+- If unsure which skill to run, list installed skills in your assistant's \`skills/\` folder.
 
 Keep this managed block so 'lightspec update' can refresh the instructions.
 `;

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

@@ -1,2 +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 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- [ ] 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 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. Check related specs\n2. Review recent archives\n3. 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";
+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 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- [ ] 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 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 \"Agent Skill 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. Check related specs\n2. Review recent archives\n3. 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

package/dist/core/templates/agents-template.js

@@ -265,7 +265,7 @@ Every requirement MUST have at least one scenario.
 Headers matched with \`trim(header)\` - whitespace ignored.
 
 #### When to use ADDED vs MODIFIED
-- 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.
+- 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 "Agent Skill Configuration") rather than altering the semantics of an existing requirement.
 - 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.
 - RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
 

package/dist/core/templates/archive-template.js

@@ -10,7 +10,7 @@ metadata:
 ---`;
 const archiveSteps = `**Steps**
 1. Determine the change ID to archive:
-   - If this prompt already includes a specific change ID (for example inside a \`<ChangeId>\` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If this prompt already includes a specific change ID (for example inside a \`<ChangeId>\` block populated by skill arguments), use that value after trimming whitespace.
    - If the conversation references a change loosely (for example by title or summary), run \`lightspec list\` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
    - Otherwise, review the conversation, run \`lightspec list\`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
    - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.

package/dist/core/templates/index.d.ts

@@ -1,5 +1,5 @@
 import { ProjectContext } from './project-template.js';
-import { SlashCommandId } from './slash-command-templates.js';
+import { AgentSkillId } from './agent-skill-templates.js';
 export interface Template {
     path: string;
     content: string | ((context: ProjectContext) => string);
@@ -10,9 +10,9 @@ export declare class TemplateManager {
     static getClineTemplate(): string;
     static getCostrictTemplate(): string;
     static getAgentsStandardTemplate(): string;
-    static getSlashCommandBody(id: SlashCommandId): string;
-    static getSlashCommandFrontmatter(id: SlashCommandId): string;
+    static getAgentSkillBody(id: AgentSkillId): string;
+    static getAgentSkillFrontmatter(id: AgentSkillId): string;
 }
 export { ProjectContext } from './project-template.js';
-export type { SlashCommandId } from './slash-command-templates.js';
+export type { AgentSkillId } from './agent-skill-templates.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/templates/index.js

@@ -3,7 +3,7 @@ import { claudeTemplate } from './claude-template.js';
 import { clineTemplate } from './cline-template.js';
 import { costrictTemplate } from './costrict-template.js';
 import { agentsRootStubTemplate } from './agents-root-stub.js';
-import { getSlashCommandBody, getSlashCommandFrontmatter, } from './slash-command-templates.js';
+import { getAgentSkillBody, getAgentSkillFrontmatter, } from './agent-skill-templates.js';
 export class TemplateManager {
     static getTemplates(context = {}) {
         return [
@@ -25,11 +25,11 @@ export class TemplateManager {
     static getAgentsStandardTemplate() {
         return agentsRootStubTemplate;
     }
-    static getSlashCommandBody(id) {
-        return getSlashCommandBody(id);
+    static getAgentSkillBody(id) {
+        return getAgentSkillBody(id);
     }
-    static getSlashCommandFrontmatter(id) {
-        return getSlashCommandFrontmatter(id);
+    static getAgentSkillFrontmatter(id) {
+        return getAgentSkillFrontmatter(id);
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/core/update.js

@@ -2,7 +2,7 @@ import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { LIGHTSPEC_DIR_NAME } from './config.js';
 import { ToolRegistry } from './configurators/registry.js';
-import { SlashCommandRegistry } from './configurators/slash/registry.js';
+import { AgentSkillRegistry } from './configurators/skills/registry.js';
 import { agentsTemplate } from './templates/agents-template.js';
 export class UpdateCommand {
     async execute(projectPath) {
@@ -18,11 +18,11 @@ export class UpdateCommand {
         await FileSystemUtils.writeFile(agentsPath, agentsTemplate);
         // 3. Update existing AI tool configuration files only
         const configurators = ToolRegistry.getAll();
-        const slashConfigurators = SlashCommandRegistry.getAll();
+        const skillConfigurators = AgentSkillRegistry.getAll();
         const updatedFiles = [];
         const createdFiles = [];
         const failedFiles = [];
-        const updatedSlashFiles = [];
+        const updatedSkillFiles = [];
         const failedSkillTools = [];
         for (const configurator of configurators) {
             const configFilePath = path.join(resolvedProjectPath, configurator.configFileName);
@@ -46,17 +46,17 @@ export class UpdateCommand {
                 console.error(`Failed to update ${configurator.configFileName}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        for (const slashConfigurator of slashConfigurators) {
-            if (!slashConfigurator.isAvailable) {
+        for (const skillConfigurator of skillConfigurators) {
+            if (!skillConfigurator.isAvailable) {
                 continue;
             }
             try {
-                const updated = await slashConfigurator.updateExisting(resolvedProjectPath, lightspecPath);
-                updatedSlashFiles.push(...updated);
+                const updated = await skillConfigurator.updateExisting(resolvedProjectPath, lightspecPath);
+                updatedSkillFiles.push(...updated);
             }
             catch (error) {
-                failedSkillTools.push(slashConfigurator.toolId);
-                console.error(`Failed to update skills for ${slashConfigurator.toolId}: ${error instanceof Error ? error.message : String(error)}`);
+                failedSkillTools.push(skillConfigurator.toolId);
+                console.error(`Failed to update skills for ${skillConfigurator.toolId}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         const summaryParts = [];
@@ -69,9 +69,9 @@ export class UpdateCommand {
         if (aiToolFiles.length > 0) {
             summaryParts.push(`Updated AI tool files: ${aiToolFiles.join(', ')}`);
         }
-        if (updatedSlashFiles.length > 0) {
+        if (updatedSkillFiles.length > 0) {
             // Normalize to forward slashes for cross-platform log consistency
-            const normalized = updatedSlashFiles.map((p) => FileSystemUtils.toPosixPath(p));
+            const normalized = updatedSkillFiles.map((p) => FileSystemUtils.toPosixPath(p));
             summaryParts.push(`Updated skills: ${normalized.join(', ')}`);
         }
         const failedItems = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightspec",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "lightspec",
@@ -74,6 +74,7 @@
     "check:pack-version": "node scripts/pack-version-check.mjs",
     "release": "pnpm run release:ci",
     "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:manual": "bash scripts/release-manual.sh",
     "changeset": "changeset"
   }
 }

package/dist/core/configurators/slash/amazon-q.d.ts

@@ -1,9 +0,0 @@
-import { SlashCommandConfigurator } from './base.js';
-import { SlashCommandId } from '../../templates/index.js';
-export declare class AmazonQSlashCommandConfigurator extends SlashCommandConfigurator {
-    readonly toolId = "amazon-q";
-    readonly isAvailable = true;
-    protected getRelativePath(id: SlashCommandId): string;
-    protected getFrontmatter(id: SlashCommandId): string;
-}
-//# sourceMappingURL=amazon-q.d.ts.map