lightspec 0.1.1 → 0.2.2

package/README.md

@@ -1,9 +1,7 @@
 <p align="center">
   <a href="https://github.com/augmenter-dev/lightspec">
     <picture>
-      <source srcset="assets/lightspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
-      <source srcset="assets/lightspec_pixel_light.svg" media="(prefers-color-scheme: light)">
-      <img src="assets/lightspec_pixel_light.svg" alt="LightSpec logo" height="64">
+      <img src="assets/augmenter-lightspec.svg" alt="LightSpec logo" height="156">
     </picture>
   </a>
   
@@ -19,16 +17,12 @@
 </p>
 
 <p align="center">
-  <img src="assets/lightspec_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.
+  <img src="assets/openspec_dashboard.png" alt="LightSpec dashboard preview" width="90%">
 </p>
 
 # LightSpec
 
-A fork of [LightSpec](https://github.com/Fission-AI/LightSpec) v0.23.0
+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.**
 
@@ -40,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).
@@ -87,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
 
@@ -196,29 +171,29 @@ 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
 
-After `lightspec init` completes, you'll receive a suggested prompt to help populate your project context:
+After `lightspec init` completes, you'll receive a suggested command to validate and populate your project context:
 
 ```text
-Populate your project context:
-"Please read lightspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
+Validate and populate your project context:
+"/lightspec:context-check"
 ```
 
-Use `lightspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
+Use the `/lightspec:context-check` skill to validate that your agent instruction file (CLAUDE.md or AGENTS.md) contains adequate project context. The skill will check for required properties like Purpose, Tech Stack, Architecture Patterns, and more. If anything is missing, it can help you explore the codebase and populate the missing information.
 
 ### 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:
@@ -281,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
@@ -379,6 +352,9 @@ Deltas are "patches" that show how specs change:
 
 ## How LightSpec Compares
 
+### vs. OpenSpec
+OpenSpec has evolved into a more mature yet complex tool with a rich feature set. LightSpec focuses on simplicity and ease of adoption, especially for teams new to spec-driven development. LightSpec's minimalist approach has the additional benefit of reducing the number of skills and commands needed, and reducing the risk of involuntary skill activation from AI assistants.
+
 ### vs. spec-kit
 LightSpec’s two-folder model (`lightspec/specs/` for the current truth, `lightspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
 
@@ -404,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
 
@@ -424,7 +400,7 @@ See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and adviso
 ## Agent Skills
 
 LightSpec includes 3 Claude Code skills for the core development workflow:
-- `lightspec-new` - Create a new change
+- `lightspec-proposal` - Create a new change
 - `lightspec-apply` - Get apply instructions for implementation
 - `lightspec-archive` - Archive a completed change
 

package/dist/cli/index.js

@@ -19,23 +19,6 @@ import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/i
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
-/**
- * Get the full command path for nested commands.
- * For example: 'change show' -> 'change:show'
- */
-function getCommandPath(command) {
-    const names = [];
-    let current = command;
-    while (current) {
-        const name = current.name();
-        // Skip the root 'lightspec' command
-        if (name && name !== 'lightspec') {
-            names.unshift(name);
-        }
-        current = current.parent;
-    }
-    return names.join(':') || 'lightspec';
-}
 program
     .name('lightspec')
     .description('AI-native system for spec-driven development')
@@ -43,19 +26,15 @@ program
 // Global options
 program.option('--no-color', 'Disable color output');
 // Apply global flags and telemetry before any command runs
-// Note: preAction receives (thisCommand, actionCommand) where:
-// - thisCommand: the command where hook was added (root program)
-// - actionCommand: the command actually being executed (subcommand)
-program.hook('preAction', async (thisCommand, actionCommand) => {
+program.hook('preAction', async (thisCommand) => {
     const opts = thisCommand.opts();
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
     // Show first-run telemetry notice (if not seen)
     await maybeShowTelemetryNotice();
-    // Track command execution (use actionCommand to get the actual subcommand)
-    const commandPath = getCommandPath(actionCommand);
-    await trackCommand(commandPath, version);
+    // Track command execution
+    await trackCommand();
 });
 // Shutdown telemetry after command completes
 program.hook('postAction', async () => {
@@ -63,10 +42,12 @@ program.hook('postAction', async () => {
 });
 const availableToolIds = AI_TOOLS.filter((tool) => tool.available).map((tool) => tool.value);
 const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
+const skillLocationOptionDescription = 'Install generated skills in "project" or "home" location (defaults to interactive selection).';
 program
     .command('init [path]')
     .description('Initialize LightSpec in your project')
     .option('--tools <tools>', toolsOptionDescription)
+    .option('--skills-location <location>', skillLocationOptionDescription)
     .action(async (targetPath = '.', options) => {
     try {
         // Validate that the path is a valid directory
@@ -90,8 +71,15 @@ program
             }
         }
         const { InitCommand } = await import('../core/init.js');
+        const skillLocation = options?.skillsLocation === 'project' || options?.skillsLocation === 'home'
+            ? options.skillsLocation
+            : undefined;
+        if (options?.skillsLocation && !skillLocation) {
+            throw new Error('Invalid --skills-location value. Use "project" or "home".');
+        }
         const initCommand = new InitCommand({
             tools: options?.tools,
+            skillLocation,
         });
         await initCommand.execute(targetPath);
     }

package/dist/commands/feedback.js

@@ -87,7 +87,7 @@ function formatBody(bodyText) {
  * Generate a pre-filled GitHub issue URL for manual submission
  */
 function generateManualSubmissionUrl(title, body) {
-    const repo = 'Fission-AI/LightSpec';
+    const repo = 'augmenter-dev/LightSpec';
     const encodedTitle = encodeURIComponent(title);
     const encodedBody = encodeURIComponent(body);
     const encodedLabels = encodeURIComponent('feedback');
@@ -114,7 +114,7 @@ function submitViaGhCli(title, body) {
             'issue',
             'create',
             '--repo',
-            'Fission-AI/LightSpec',
+            'augmenter-dev/LightSpec',
             '--title',
             title,
             '--body',

package/dist/core/config.d.ts

@@ -5,6 +5,7 @@ export declare const LIGHTSPEC_MARKERS: {
 };
 export interface LightSpecConfig {
     aiTools: string[];
+    skillLocation: 'project' | 'home';
 }
 export interface AIToolOption {
     name: string;

package/dist/core/config.js

@@ -20,6 +20,7 @@ export const AI_TOOLS = [
     { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot' },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow' },
     { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code' },
+    { name: 'Mistral Vibe', value: 'mistral-vibe', available: true, successLabel: 'Mistral Vibe' },
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode' },
     { name: 'Qoder (CLI)', value: 'qoder', available: true, successLabel: 'Qoder' },
     { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code' },

package/dist/core/configurators/slash/amazon-q.js

@@ -2,7 +2,8 @@ import { SlashCommandConfigurator } from './base.js';
 const FILE_PATHS = {
     proposal: '.amazonq/prompts/lightspec-proposal.md',
     apply: '.amazonq/prompts/lightspec-apply.md',
-    archive: '.amazonq/prompts/lightspec-archive.md'
+    archive: '.amazonq/prompts/lightspec-archive.md',
+    'context-check': '.aws/amazonq/commands/lightspec-context-check.md'
 };
 const FRONTMATTER = {
     proposal: `---
@@ -31,7 +32,10 @@ The user wants to archive the following deployed change. Use the lightspec instr
 
 <ChangeId>
   $ARGUMENTS
-</ChangeId>`
+</ChangeId>`,
+    'context-check': `---
+description: Validate project context in agent instruction files and help populate missing information.
+---`
 };
 export class AmazonQSlashCommandConfigurator extends SlashCommandConfigurator {
     toolId = 'amazon-q';

package/dist/core/configurators/slash/antigravity.js

@@ -2,12 +2,14 @@ import { SlashCommandConfigurator } from './base.js';
 const FILE_PATHS = {
     proposal: '.agent/workflows/lightspec-proposal.md',
     apply: '.agent/workflows/lightspec-apply.md',
-    archive: '.agent/workflows/lightspec-archive.md'
+    archive: '.agent/workflows/lightspec-archive.md',
+    'context-check': '.antigravity/commands/lightspec-context-check.md'
 };
 const DESCRIPTIONS = {
     proposal: 'Scaffold a new LightSpec change and validate strictly.',
     apply: 'Implement an approved LightSpec change and keep tasks in sync.',
-    archive: 'Archive a deployed LightSpec change and update specs.'
+    archive: 'Archive a deployed LightSpec change and update specs.',
+    'context-check': 'Validate project context in agent instruction files and help populate missing information.'
 };
 export class AntigravitySlashCommandConfigurator extends SlashCommandConfigurator {
     toolId = 'antigravity';

package/dist/core/configurators/slash/auggie.js

@@ -2,7 +2,8 @@ import { SlashCommandConfigurator } from './base.js';
 const FILE_PATHS = {
     proposal: '.augment/commands/lightspec-proposal.md',
     apply: '.augment/commands/lightspec-apply.md',
-    archive: '.augment/commands/lightspec-archive.md'
+    archive: '.augment/commands/lightspec-archive.md',
+    'context-check': '.auggie/commands/lightspec-context-check.md'
 };
 const FRONTMATTER = {
     proposal: `---
@@ -16,6 +17,12 @@ argument-hint: change-id
     archive: `---
 description: Archive a deployed LightSpec change and update specs.
 argument-hint: change-id
+---`,
+    'context-check': `---
+name: LightSpec: Context Check
+description: Validate project context in agent instruction files and help populate missing information.
+category: LightSpec
+tags: [lightspec, context, validation]
 ---`
 };
 export class AuggieSlashCommandConfigurator extends SlashCommandConfigurator {

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

@@ -2,18 +2,29 @@ import { SlashCommandId } from '../../templates/index.js';
 export interface SlashCommandTarget {
     id: SlashCommandId;
     path: string;
-    kind: 'slash';
+    kind: 'skill';
 }
+export type SkillInstallLocation = 'project' | 'home';
 export declare abstract class SlashCommandConfigurator {
     abstract readonly toolId: string;
     abstract readonly isAvailable: boolean;
+    private installLocation;
+    setInstallLocation(location: SkillInstallLocation): void;
     getTargets(): SlashCommandTarget[];
     generateAll(projectPath: string, _lightspecDir: string): Promise<string[]>;
     updateExisting(projectPath: string, _lightspecDir: string): Promise<string[]>;
-    protected abstract getRelativePath(id: SlashCommandId): string;
-    protected abstract getFrontmatter(id: SlashCommandId): string | undefined;
     protected getBody(id: SlashCommandId): string;
     resolveAbsolutePath(projectPath: string, id: SlashCommandId): string;
+    private getRelativeSkillPath;
+    private getToolRoot;
+    private getHomeRootPath;
+    private getSkillName;
+    private buildSkillFile;
     protected updateBody(filePath: string, body: string): Promise<void>;
+    private cleanupLegacyArtifacts;
+    private relativeToToolRoot;
+    private removeLegacyLightSpecFiles;
+    private walkAndRemove;
+    private isLegacyLightSpecFile;
 }
 //# sourceMappingURL=base.d.ts.map

package/dist/core/configurators/slash/base.js

@@ -1,57 +1,151 @@
+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'];
+const ALL_COMMANDS = ['proposal', 'apply', 'archive', 'context-check'];
+const TOOL_SKILL_ROOTS = {
+    'amazon-q': '.amazonq',
+    antigravity: '.antigravity',
+    auggie: '.auggie',
+    claude: '.claude',
+    cline: '.cline',
+    codex: '.codex',
+    codebuddy: '.codebuddy',
+    continue: '.continue',
+    costrict: '.cospec/lightspec',
+    crush: '.crush',
+    cursor: '.cursor',
+    factory: '.factory',
+    gemini: '.gemini',
+    'github-copilot': '.github/copilot',
+    iflow: '.iflow',
+    kilocode: '.kilocode',
+    'mistral-vibe': '.vibe',
+    opencode: '.opencode',
+    qoder: '.qoder',
+    qwen: '.qwen',
+    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 class SlashCommandConfigurator {
+    installLocation = 'project';
+    setInstallLocation(location) {
+        this.installLocation = location;
+    }
     getTargets() {
         return ALL_COMMANDS.map((id) => ({
             id,
-            path: this.getRelativePath(id),
-            kind: 'slash'
+            path: this.getRelativeSkillPath(id),
+            kind: 'skill',
         }));
     }
     async generateAll(projectPath, _lightspecDir) {
         const createdOrUpdated = [];
         for (const target of this.getTargets()) {
             const body = this.getBody(target.id);
-            const filePath = FileSystemUtils.joinPath(projectPath, target.path);
+            const filePath = this.resolveAbsolutePath(projectPath, target.id);
             if (await FileSystemUtils.fileExists(filePath)) {
                 await this.updateBody(filePath, body);
             }
             else {
-                const frontmatter = this.getFrontmatter(target.id);
-                const sections = [];
-                if (frontmatter) {
-                    sections.push(frontmatter.trim());
-                }
-                sections.push(`${LIGHTSPEC_MARKERS.start}\n${body}\n${LIGHTSPEC_MARKERS.end}`);
-                const content = sections.join('\n') + '\n';
+                const frontmatter = TemplateManager.getSlashCommandFrontmatter(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) {
         const updated = [];
         for (const target of this.getTargets()) {
-            const filePath = FileSystemUtils.joinPath(projectPath, target.path);
+            const filePath = this.resolveAbsolutePath(projectPath, target.id);
             if (await FileSystemUtils.fileExists(filePath)) {
                 const body = this.getBody(target.id);
                 await this.updateBody(filePath, body);
                 updated.push(target.path);
             }
         }
+        await this.cleanupLegacyArtifacts(projectPath);
         return updated;
     }
     getBody(id) {
         return TemplateManager.getSlashCommandBody(id).trim();
     }
-    // Resolve absolute path for a given slash command target. Subclasses may override
-    // to redirect to tool-specific locations (e.g., global directories).
     resolveAbsolutePath(projectPath, id) {
-        const rel = this.getRelativePath(id);
-        return FileSystemUtils.joinPath(projectPath, rel);
+        const relativePath = this.getRelativeSkillPath(id);
+        if (this.installLocation === 'project') {
+            return FileSystemUtils.joinPath(projectPath, relativePath);
+        }
+        const homeRoot = this.getHomeRootPath();
+        const rootPrefix = this.getToolRoot();
+        const normalizedRelativePath = FileSystemUtils.toPosixPath(relativePath);
+        if (!normalizedRelativePath.startsWith(`${rootPrefix}/`)) {
+            throw new Error(`Skill path '${relativePath}' does not match expected root '${rootPrefix}' for ${this.toolId}`);
+        }
+        const relativeUnderRoot = normalizedRelativePath.slice(rootPrefix.length + 1);
+        return FileSystemUtils.joinPath(homeRoot, relativeUnderRoot);
+    }
+    getRelativeSkillPath(id) {
+        const root = this.getToolRoot();
+        const skillName = this.getSkillName(id);
+        return `${root}/skills/${skillName}/SKILL.md`;
+    }
+    getToolRoot() {
+        const root = TOOL_SKILL_ROOTS[this.toolId];
+        if (!root) {
+            throw new Error(`No skill root directory configured for tool '${this.toolId}'`);
+        }
+        return root;
+    }
+    getHomeRootPath() {
+        if (this.toolId === 'codex') {
+            const codexHome = process.env.CODEX_HOME?.trim();
+            return codexHome && codexHome.length > 0
+                ? codexHome
+                : FileSystemUtils.joinPath(os.homedir(), '.codex');
+        }
+        const toolRoot = this.getToolRoot();
+        const trimmed = toolRoot.startsWith('./') ? toolRoot.slice(2) : toolRoot;
+        return path.join(os.homedir(), trimmed);
+    }
+    getSkillName(id) {
+        return `lightspec-${id}`;
+    }
+    buildSkillFile(frontmatter, body) {
+        const sections = [];
+        if (frontmatter) {
+            sections.push(frontmatter);
+        }
+        sections.push(`${LIGHTSPEC_MARKERS.start}\n${body}\n${LIGHTSPEC_MARKERS.end}`);
+        return `${sections.join('\n\n')}\n`;
     }
     async updateBody(filePath, body) {
         const content = await FileSystemUtils.readFile(filePath);
@@ -65,5 +159,55 @@ 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/slash/claude.js

@@ -2,7 +2,8 @@ import { SlashCommandConfigurator } from './base.js';
 const FILE_PATHS = {
     proposal: '.claude/commands/lightspec/proposal.md',
     apply: '.claude/commands/lightspec/apply.md',
-    archive: '.claude/commands/lightspec/archive.md'
+    archive: '.claude/commands/lightspec/archive.md',
+    'context-check': '.claude/commands/lightspec/context-check.md'
 };
 const FRONTMATTER = {
     proposal: `---
@@ -22,6 +23,12 @@ name: LightSpec: Archive
 description: Archive a deployed LightSpec change and update specs.
 category: LightSpec
 tags: [lightspec, archive]
+---`,
+    'context-check': `---
+name: LightSpec: Context Check
+description: Validate project context in agent instruction files and help populate missing information.
+category: LightSpec
+tags: [lightspec, context, validation]
 ---`
 };
 export class ClaudeSlashCommandConfigurator extends SlashCommandConfigurator {