lightspec 0.2.1 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <a href="https://github.com/augmenter-dev/lightspec">
     <picture>
-      <img src="assets/augmenter-lightspec.svg" alt="LightSpec logo" height="64">
+      <img src="assets/augmenter-lightspec.svg" alt="LightSpec logo" height="156">
     </picture>
   </a>
   
@@ -20,13 +20,9 @@
   <img src="assets/openspec_dashboard.png" alt="LightSpec dashboard preview" width="90%">
 </p>
 
-<p align="center">
-  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">LightSpec Discord</a> for help and questions.
-</p>
-
 # LightSpec
 
-A fork of [LightSpec](https://github.com/augmenter-dev/LightSpec), focused on simplicity and skill-based agents.
+A fork of [OpenSpec](https://github.com/Fission-AI/OpenSpec), focused on simplicity and skill-based agents.
 
 LightSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
 
@@ -38,13 +34,14 @@ Key outcomes:
 - Human and AI stakeholders agree on specs before work begins.
 - Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
 - Shared visibility into what's proposed, active, or archived.
-- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
+- Works with the AI tools you already use via [agent skills](https://agentskills.io/).
 
 ## How LightSpec compares (at a glance)
 
 - **Lightweight**: simple workflow, no API keys, minimal setup.
 - **Brownfield-first**: works great beyond 0→1. LightSpec separates the source of truth from proposals: `lightspec/specs/` (current truth) and `lightspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
 - **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
+- **Compared to OpenSpec**: LightSpec is a streamlined alternative to OpenSpec, focused on simplicity and ease of adoption. It has fewer commands and a more opinionated workflow, which can reduce cognitive overhead for teams new to spec-driven development.
 - **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). LightSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
 
 See the full comparison in [How LightSpec Compares](#how-lightspec-compares).
@@ -85,49 +82,29 @@ See the full comparison in [How LightSpec Compares](#how-lightspec-compares).
 
 ### Supported AI Tools
 
-<details>
-<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
-
-These tools have built-in LightSpec commands. Select the LightSpec integration when prompted.
-
-| Tool | Commands |
-|------|----------|
-| **Amazon Q Developer** | `@lightspec-proposal`, `@lightspec-apply`, `@lightspec-archive` (`.amazonq/prompts/`) |
-| **Antigravity** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.agent/workflows/`) |
-| **Auggie (Augment CLI)** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.augment/commands/`) |
-| **Claude Code** | `/lightspec:proposal`, `/lightspec:apply`, `/lightspec:archive` |
-| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/lightspec-*.md`) |
-| **CodeBuddy Code (CLI)** | `/lightspec:proposal`, `/lightspec:apply`, `/lightspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
-| **Codex** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (global: `~/.codex/prompts`, auto-installed) |
-| **Continue** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.continue/prompts/`) |
-| **CoStrict** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.cospec/lightspec/commands/`) — see [docs](https://costrict.ai)|
-| **Crush** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.crush/commands/lightspec/`) |
-| **Cursor** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` |
-| **Factory Droid** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.factory/commands/`) |
-| **Gemini CLI** | `/lightspec:proposal`, `/lightspec:apply`, `/lightspec:archive` (`.gemini/commands/lightspec/`) |
-| **GitHub Copilot** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.github/prompts/`) |
-| **iFlow (iflow-cli)** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.iflow/commands/`) |
-| **Kilo Code** | `/lightspec-proposal.md`, `/lightspec-apply.md`, `/lightspec-archive.md` (`.kilocode/workflows/`) |
-| **OpenCode** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` |
-| **Qoder (CLI)** | `/lightspec:proposal`, `/lightspec:apply`, `/lightspec:archive` (`.qoder/commands/lightspec/`) — see [docs](https://qoder.com/cli) |
-| **Qwen Code** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.qwen/commands/`) |
-| **RooCode** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.roo/commands/`) |
-| **Windsurf** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.windsurf/workflows/`) |
-
-Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/lightspec-proposal.md`, `/lightspec-apply.md`, or `/lightspec-archive.md`.
-
-</details>
-
-<details>
-<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
-
-These tools automatically read workflow instructions from `lightspec/AGENTS.md`. Ask them to follow the LightSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
-
-| Tools |
-|-------|
-| Amp • Jules • Others |
-
-</details>
+- Amazon Q Developer
+- Antigravity
+- Auggie (Augment CLI)
+- Claude Code
+- Cline
+- Codex
+- CodeBuddy Code (CLI)
+- Continue (VS Code / JetBrains / CLI)
+- CoStrict
+- Crush
+- Cursor
+- Factory Droid
+- Gemini CLI
+- GitHub Copilot
+- iFlow
+- Kilo Code
+- Mistral Vibe
+- OpenCode
+- Qoder (CLI)
+- Qwen Code
+- RooCode
+- Windsurf
+- Any AGENTS.md-compatible assistant (via Universal `AGENTS.md`)
 
 ### Install & Initialize
 
@@ -194,14 +171,14 @@ lightspec init
 
 **What happens during initialization:**
 - You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
-- LightSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
+- LightSpec automatically configures skills for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
 - A new `lightspec/` directory structure is created in your project
 
 **After setup:**
 - Primary AI tools can trigger `/lightspec` workflows without additional configuration
 - Run `lightspec list` to verify the setup and view any active changes
-- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
-  so a fresh launch ensures they appear
+- If your coding assistant doesn't surface the new skills right away, restart it. Skills are loaded at startup, so a fresh launch ensures they appear
+- Depending on your AI tool, you'll need to invoke the lightspec skills with either slash commands (e.g. `/lightspec:proposal`) or dollar commands (e.g. `$lightspec-proposal`) to create change proposals, apply changes, or archive completed work
 
 ### Optional: Populate Project Context
 
@@ -216,7 +193,7 @@ Use the `/lightspec:context-check` skill to validate that your agent instruction
 
 ### Create Your First Change
 
-Here's a real example showing the complete LightSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
+Here's a real example showing the complete LightSpec workflow. This works with any AI tool.
 
 #### 1. Draft the Proposal
 Start by asking your AI to create a change proposal:
@@ -279,8 +256,6 @@ Or run the command yourself in terminal:
 $ lightspec archive add-profile-filters --yes  # Archive the completed change without prompts
 ```
 
-**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an LightSpec proposal", "apply the LightSpec change", or "archive the change".
-
 ## Command Reference
 
 ```bash
@@ -405,7 +380,7 @@ Run `lightspec update` whenever someone switches tools so your agents pick up th
    npm install -g lightspec@latest
    ```
 2. **Refresh agent instructions**
-   - Run `lightspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
+   - Run `lightspec update` inside each project to regenerate AI guidance and ensure the latest skills are active.
 
 ## Contributing
 

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.