lightspec 0.4.1 → 0.6.0

package/README.md

@@ -82,28 +82,39 @@ See the full comparison in [How LightSpec Compares](#how-lightspec-compares).
 
 ### Supported AI Tools
 
+- AdaL
 - Amazon Q Developer
-- Antigravity
-- Auggie (Augment CLI)
+- Augment
 - Claude Code
 - Cline
-- Codex
-- CodeBuddy Code (CLI)
-- Continue (VS Code / JetBrains / CLI)
+- CodeBuddy
+- Command Code
+- Continue
 - CoStrict
+- Cortex Code
 - Crush
-- Cursor
-- Factory Droid
-- Gemini CLI
-- GitHub Copilot
-- iFlow
+- Droid
+- iFlow CLI
+- Junie
 - Kilo Code
+- Kiro CLI
+- Kode
+- MCPJam
 - Mistral Vibe
-- OpenCode
-- Qoder (CLI)
+- Mux
+- Neovate
+- OpenClaw
+- OpenHands
+- Pochi
+- Pi
+- Qoder
 - Qwen Code
-- RooCode
+- Roo Code
+- Trae
+- Trae CN
+- Universal agent skills (`.agents`, for Codex, Amp, VS Code, Zed, Warp, Goose, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Replit, and similar assistants)
 - Windsurf
+- Zencoder
 - Any AGENTS.md-compatible assistant (via Universal `AGENTS.md`)
 
 ### Install & Initialize
@@ -170,7 +181,7 @@ 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
+- You'll be prompted to pick any natively supported AI tools using the current LightSpec provider IDs and install paths (for example `claude-code`, `cline`, `costrict`, `qoder`, `qwen-code`, `roo`, `universal`)
 - 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
 

package/dist/core/config.d.ts

@@ -13,5 +13,7 @@ export interface AIToolOption {
     available: boolean;
     successLabel?: string;
 }
+export declare const LEGACY_TOOL_ALIASES: Record<string, string>;
+export declare function normalizeToolId(toolId: string): string;
 export declare const AI_TOOLS: AIToolOption[];
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -3,29 +3,80 @@ export const LIGHTSPEC_MARKERS = {
     start: '<!-- LIGHTSPEC:START -->',
     end: '<!-- LIGHTSPEC:END -->'
 };
+const UNIVERSAL_AGENTS_SUPPORTED_PROVIDERS = [
+    'Codex',
+    'Amp',
+    'VS Code',
+    'Zed',
+    'Warp',
+    'Goose',
+];
+const UNIVERSAL_AGENTS_PROVIDER_PREVIEW_COUNT = 5;
+const universalAgentsProviderPreview = UNIVERSAL_AGENTS_SUPPORTED_PROVIDERS.slice(0, UNIVERSAL_AGENTS_PROVIDER_PREVIEW_COUNT).join(', ');
+const universalAgentsProviderSuffix = UNIVERSAL_AGENTS_SUPPORTED_PROVIDERS.length > UNIVERSAL_AGENTS_PROVIDER_PREVIEW_COUNT
+    ? ', ...'
+    : '';
+const UNIVERSAL_AGENTS_OPTION_LABEL = `Universal agent skills (${universalAgentsProviderPreview}${universalAgentsProviderSuffix})`;
+export const LEGACY_TOOL_ALIASES = {
+    agents: 'universal',
+    amp: 'universal',
+    antigravity: 'universal',
+    auggie: 'augment',
+    claude: 'claude-code',
+    codex: 'universal',
+    cursor: 'universal',
+    deepagents: 'universal',
+    factory: 'droid',
+    gemini: 'universal',
+    'gemini-cli': 'universal',
+    goose: 'universal',
+    'github-copilot': 'universal',
+    iflow: 'iflow-cli',
+    'kimi-cli': 'universal',
+    kilocode: 'kilo',
+    opencode: 'universal',
+    qwen: 'qwen-code',
+    replit: 'universal',
+    roocode: 'roo',
+    warp: 'universal',
+};
+export function normalizeToolId(toolId) {
+    const normalized = toolId.trim().toLowerCase();
+    return LEGACY_TOOL_ALIASES[normalized] ?? normalized;
+}
 export const AI_TOOLS = [
+    { name: UNIVERSAL_AGENTS_OPTION_LABEL, value: 'universal', available: true, successLabel: 'Universal agent skills' },
     { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer' },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity' },
-    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie' },
-    { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code' },
+    { name: 'Augment', value: 'augment', available: true, successLabel: 'Augment' },
+    { name: 'Claude Code', value: 'claude-code', available: true, successLabel: 'Claude Code' },
     { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline' },
-    { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex' },
-    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code' },
-    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)' },
+    { name: 'CodeBuddy', value: 'codebuddy', available: true, successLabel: 'CodeBuddy' },
+    { name: 'Command Code', value: 'command-code', available: true, successLabel: 'Command Code' },
+    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue' },
     { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict' },
+    { name: 'Cortex Code', value: 'cortex', available: true, successLabel: 'Cortex Code' },
     { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush' },
-    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor' },
-    { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid' },
-    { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI' },
-    { 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: 'Droid', value: 'droid', available: true, successLabel: 'Droid' },
+    { name: 'iFlow CLI', value: 'iflow-cli', available: true, successLabel: 'iFlow CLI' },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie' },
+    { name: 'Kilo Code', value: 'kilo', available: true, successLabel: 'Kilo Code' },
+    { name: 'Kiro CLI', value: 'kiro-cli', available: true, successLabel: 'Kiro CLI' },
+    { name: 'Kode', value: 'kode', available: true, successLabel: 'Kode' },
+    { name: 'MCPJam', value: 'mcpjam', available: true, successLabel: 'MCPJam' },
     { 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' },
-    { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode' },
+    { name: 'Mux', value: 'mux', available: true, successLabel: 'Mux' },
+    { name: 'Neovate', value: 'neovate', available: true, successLabel: 'Neovate' },
+    { name: 'OpenClaw', value: 'openclaw', available: true, successLabel: 'OpenClaw' },
+    { name: 'OpenHands', value: 'openhands', available: true, successLabel: 'OpenHands' },
+    { name: 'Pochi', value: 'pochi', available: true, successLabel: 'Pochi' },
+    { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi' },
+    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder' },
+    { name: 'Qwen Code', value: 'qwen-code', available: true, successLabel: 'Qwen Code' },
+    { name: 'Roo Code', value: 'roo', available: true, successLabel: 'Roo Code' },
+    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae' },
+    { name: 'Trae CN', value: 'trae-cn', available: true, successLabel: 'Trae CN' },
     { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf' },
-    { name: 'AGENTS.md + .agents (works with Amp, VS Code, …)', value: 'agents', available: true, successLabel: 'your AGENTS.md-compatible assistant' }
+    { name: 'Zencoder', value: 'zencoder', available: true, successLabel: 'Zencoder' },
+    { name: 'AdaL', value: 'adal', available: true, successLabel: 'AdaL' },
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/configurators/registry.js

@@ -6,6 +6,7 @@ import { QoderConfigurator } from './qoder.js';
 import { IflowConfigurator } from './iflow.js';
 import { AgentsStandardConfigurator } from './agents.js';
 import { QwenConfigurator } from './qwen.js';
+import { normalizeToolId } from '../config.js';
 export class ToolRegistry {
     static tools = new Map();
     static {
@@ -18,20 +19,20 @@ export class ToolRegistry {
         const agentsConfigurator = new AgentsStandardConfigurator();
         const qwenConfigurator = new QwenConfigurator();
         // Register with the ID that matches the checkbox value
-        this.tools.set('claude', claudeConfigurator);
+        this.tools.set('claude-code', claudeConfigurator);
         this.tools.set('cline', clineConfigurator);
         this.tools.set('codebuddy', codeBuddyConfigurator);
         this.tools.set('costrict', costrictConfigurator);
         this.tools.set('qoder', qoderConfigurator);
-        this.tools.set('iflow', iflowConfigurator);
-        this.tools.set('agents', agentsConfigurator);
-        this.tools.set('qwen', qwenConfigurator);
+        this.tools.set('iflow-cli', iflowConfigurator);
+        this.tools.set('universal', agentsConfigurator);
+        this.tools.set('qwen-code', qwenConfigurator);
     }
     static register(tool) {
         this.tools.set(tool.name.toLowerCase().replace(/\s+/g, '-'), tool);
     }
     static get(toolId) {
-        return this.tools.get(toolId);
+        return this.tools.get(normalizeToolId(toolId));
     }
     static getAll() {
         return Array.from(this.tools.values());

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

@@ -5,6 +5,7 @@ export interface AgentSkillTarget {
     kind: 'skill';
 }
 export type SkillInstallLocation = 'project' | 'home';
+export declare function normalizeAgentSkillToolId(toolId: string): string;
 export declare const AGENT_SKILL_TOOL_IDS: readonly string[];
 export declare class AgentSkillConfigurator {
     readonly toolId: string;
@@ -17,8 +18,14 @@ export declare class AgentSkillConfigurator {
     updateExisting(projectPath: string, _lightspecDir: string): Promise<string[]>;
     protected getBody(id: AgentSkillId): string;
     resolveAbsolutePath(projectPath: string, id: AgentSkillId): string;
+    resolveExistingAbsolutePaths(projectPath: string, id: AgentSkillId): Array<{
+        absolutePath: string;
+        relativePath: string;
+    }>;
     private getRelativeSkillPath;
-    private getToolRoot;
+    private getAllRelativeSkillPaths;
+    private resolvePathFromRelative;
+    private getDescriptor;
     private getHomeRootPath;
     private getSkillName;
     private buildSkillFile;

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

@@ -1,47 +1,210 @@
 import os from 'os';
-import path from 'path';
 import { FileSystemUtils } from '../../../utils/file-system.js';
 import { TemplateManager } from '../../templates/index.js';
-import { LIGHTSPEC_MARKERS } from '../../config.js';
-const ALL_SKILL_IDS = ['proposal', 'apply', 'archive', 'agentsmd-check'];
-const TOOL_SKILL_ROOTS = {
-    'amazon-q': '.amazonq',
-    antigravity: '.antigravity',
-    agents: '.agents',
-    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',
+import { LIGHTSPEC_MARKERS, normalizeToolId } from '../../config.js';
+const ALL_SKILL_IDS = ['proposal', 'apply', 'archive', 'agentsmd-check', 'loop'];
+const TOOL_SKILL_DESCRIPTORS = {
+    'amazon-q': {
+        projectSkillDir: '.amazonq/skills',
+        homeSkillDir: '.amazonq/skills',
+    },
+    adal: {
+        projectSkillDir: '.adal/skills',
+        homeSkillDir: '.adal/skills',
+    },
+    augment: {
+        projectSkillDir: '.augment/skills',
+        homeSkillDir: '.augment/skills',
+        aliases: ['auggie'],
+        legacyProjectSkillDirs: ['.auggie/skills'],
+        legacyHomeSkillDirs: ['.auggie/skills'],
+    },
+    'claude-code': {
+        projectSkillDir: '.claude/skills',
+        homeSkillDir: '.claude/skills',
+        aliases: ['claude'],
+    },
+    cline: {
+        projectSkillDir: '.agents/skills',
+        homeSkillDir: '.agents/skills',
+        legacyProjectSkillDirs: ['.cline/skills'],
+        legacyHomeSkillDirs: ['.cline/skills'],
+    },
+    codebuddy: {
+        projectSkillDir: '.codebuddy/skills',
+        homeSkillDir: '.codebuddy/skills',
+    },
+    'command-code': {
+        projectSkillDir: '.commandcode/skills',
+        homeSkillDir: '.commandcode/skills',
+    },
+    continue: {
+        projectSkillDir: '.continue/skills',
+        homeSkillDir: '.continue/skills',
+    },
+    costrict: {
+        projectSkillDir: '.cospec/lightspec/skills',
+        homeSkillDir: '.cospec/lightspec/skills',
+    },
+    cortex: {
+        projectSkillDir: '.cortex/skills',
+        homeSkillDir: '.snowflake/cortex/skills',
+    },
+    crush: {
+        projectSkillDir: '.crush/skills',
+        homeSkillDir: '.config/crush/skills',
+        legacyHomeSkillDirs: ['.crush/skills'],
+    },
+    droid: {
+        projectSkillDir: '.factory/skills',
+        homeSkillDir: '.factory/skills',
+        aliases: ['factory'],
+    },
+    'iflow-cli': {
+        projectSkillDir: '.iflow/skills',
+        homeSkillDir: '.iflow/skills',
+        aliases: ['iflow'],
+    },
+    junie: {
+        projectSkillDir: '.junie/skills',
+        homeSkillDir: '.junie/skills',
+    },
+    kilo: {
+        projectSkillDir: '.kilocode/skills',
+        homeSkillDir: '.kilocode/skills',
+        aliases: ['kilocode'],
+    },
+    'kiro-cli': {
+        projectSkillDir: '.kiro/skills',
+        homeSkillDir: '.kiro/skills',
+    },
+    kode: {
+        projectSkillDir: '.kode/skills',
+        homeSkillDir: '.kode/skills',
+    },
+    mcpjam: {
+        projectSkillDir: '.mcpjam/skills',
+        homeSkillDir: '.mcpjam/skills',
+    },
+    'mistral-vibe': {
+        projectSkillDir: '.vibe/skills',
+        homeSkillDir: '.vibe/skills',
+    },
+    mux: {
+        projectSkillDir: '.mux/skills',
+        homeSkillDir: '.mux/skills',
+    },
+    neovate: {
+        projectSkillDir: '.neovate/skills',
+        homeSkillDir: '.neovate/skills',
+    },
+    openclaw: {
+        projectSkillDir: 'skills',
+        homeSkillDir: '.openclaw/skills',
+    },
+    openhands: {
+        projectSkillDir: '.openhands/skills',
+        homeSkillDir: '.openhands/skills',
+    },
+    pochi: {
+        projectSkillDir: '.pochi/skills',
+        homeSkillDir: '.pochi/skills',
+    },
+    pi: {
+        projectSkillDir: '.pi/skills',
+        homeSkillDir: '.pi/agent/skills',
+    },
+    qoder: {
+        projectSkillDir: '.qoder/skills',
+        homeSkillDir: '.qoder/skills',
+    },
+    'qwen-code': {
+        projectSkillDir: '.qwen/skills',
+        homeSkillDir: '.qwen/skills',
+        aliases: ['qwen'],
+    },
+    roo: {
+        projectSkillDir: '.roo/skills',
+        homeSkillDir: '.roo/skills',
+        aliases: ['roocode'],
+        legacyProjectSkillDirs: ['.roocode/skills'],
+        legacyHomeSkillDirs: ['.roocode/skills'],
+    },
+    'trae-cn': {
+        projectSkillDir: '.trae/skills',
+        homeSkillDir: '.trae-cn/skills',
+    },
+    trae: {
+        projectSkillDir: '.trae/skills',
+        homeSkillDir: '.trae/skills',
+    },
+    universal: {
+        projectSkillDir: '.agents/skills',
+        homeSkillDir: '.config/agents/skills',
+        aliases: [
+            'agents',
+            'amp',
+            'antigravity',
+            'codex',
+            'cursor',
+            'deepagents',
+            'gemini',
+            'gemini-cli',
+            'github-copilot',
+            'goose',
+            'kimi-cli',
+            'opencode',
+            'replit',
+            'warp',
+        ],
+        legacyProjectSkillDirs: [
+            '.antigravity/skills',
+            '.cursor/skills',
+            '.codex/skills',
+            '.gemini/skills',
+            '.github/copilot/skills',
+            '.opencode/skills',
+        ],
+        legacyHomeSkillDirs: [
+            '.agents/skills',
+            '.antigravity/skills',
+            '.cursor/skills',
+            '.codex/skills',
+            '.deepagents/agent/skills',
+            '.gemini/skills',
+            '.github/copilot/skills',
+            '.copilot/skills',
+            '.opencode/skills',
+        ],
+    },
+    windsurf: {
+        projectSkillDir: '.windsurf/skills',
+        homeSkillDir: '.codeium/windsurf/skills',
+        legacyHomeSkillDirs: ['.windsurf/skills'],
+    },
+    zencoder: {
+        projectSkillDir: '.zencoder/skills',
+        homeSkillDir: '.zencoder/skills',
+    },
 };
-export const AGENT_SKILL_TOOL_IDS = Object.freeze(Object.keys(TOOL_SKILL_ROOTS));
+const TOOL_ID_ALIASES = Object.freeze(Object.fromEntries(Object.entries(TOOL_SKILL_DESCRIPTORS).flatMap(([toolId, descriptor]) => (descriptor.aliases ?? []).map((alias) => [alias, toolId]))));
+export function normalizeAgentSkillToolId(toolId) {
+    const normalized = normalizeToolId(toolId);
+    return TOOL_ID_ALIASES[normalized] ?? normalized;
+}
+export const AGENT_SKILL_TOOL_IDS = Object.freeze(Object.keys(TOOL_SKILL_DESCRIPTORS));
 const TOOL_BODY_SUFFIX = {
-    factory: '\n\n$ARGUMENTS',
+    droid: '\n\n$ARGUMENTS',
 };
 export class AgentSkillConfigurator {
     toolId;
     isAvailable;
     installLocation = 'project';
     constructor(toolId, isAvailable = true) {
-        this.toolId = toolId;
+        this.toolId = normalizeAgentSkillToolId(toolId);
         this.isAvailable = isAvailable;
-        if (!TOOL_SKILL_ROOTS[this.toolId]) {
-            throw new Error(`No skill root directory configured for tool '${this.toolId}'`);
+        if (!TOOL_SKILL_DESCRIPTORS[this.toolId]) {
+            throw new Error(`No skill root directory configured for tool '${toolId}'`);
         }
     }
     setInstallLocation(location) {
@@ -74,11 +237,14 @@ export class AgentSkillConfigurator {
     async updateExisting(projectPath, _lightspecDir) {
         const updated = [];
         for (const target of this.getTargets()) {
-            const filePath = this.resolveAbsolutePath(projectPath, target.id);
-            if (await FileSystemUtils.fileExists(filePath)) {
+            const candidatePaths = this.resolveExistingAbsolutePaths(projectPath, target.id);
+            for (const candidate of candidatePaths) {
+                if (!await FileSystemUtils.fileExists(candidate.absolutePath)) {
+                    continue;
+                }
                 const body = this.getBody(target.id);
-                await this.updateBody(filePath, body);
-                updated.push(target.path);
+                await this.updateBody(candidate.absolutePath, body);
+                updated.push(candidate.relativePath);
             }
         }
         return updated;
@@ -90,40 +256,54 @@ export class AgentSkillConfigurator {
     }
     resolveAbsolutePath(projectPath, id) {
         const relativePath = this.getRelativeSkillPath(id);
+        return this.resolvePathFromRelative(projectPath, relativePath);
+    }
+    resolveExistingAbsolutePaths(projectPath, id) {
+        const relativePaths = this.getAllRelativeSkillPaths(id);
+        return relativePaths.map((relativePath) => ({
+            absolutePath: this.resolvePathFromRelative(projectPath, relativePath),
+            relativePath,
+        }));
+    }
+    getRelativeSkillPath(id) {
+        const descriptor = this.getDescriptor();
+        const skillName = this.getSkillName(id);
+        const skillDir = this.installLocation === 'project'
+            ? descriptor.projectSkillDir
+            : descriptor.homeSkillDir;
+        return `${skillDir}/${skillName}/SKILL.md`;
+    }
+    getAllRelativeSkillPaths(id) {
+        const descriptor = this.getDescriptor();
+        const skillName = this.getSkillName(id);
+        const skillDirs = this.installLocation === 'project'
+            ? [descriptor.projectSkillDir, ...(descriptor.legacyProjectSkillDirs ?? [])]
+            : [descriptor.homeSkillDir, ...(descriptor.legacyHomeSkillDirs ?? [])];
+        return Array.from(new Set(skillDirs.map((dir) => `${dir}/${skillName}/SKILL.md`)));
+    }
+    resolvePathFromRelative(projectPath, relativePath) {
         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`;
+        return FileSystemUtils.joinPath(homeRoot, relativePath);
     }
-    getToolRoot() {
-        const root = TOOL_SKILL_ROOTS[this.toolId];
-        if (!root) {
+    getDescriptor() {
+        const descriptor = TOOL_SKILL_DESCRIPTORS[this.toolId];
+        if (!descriptor) {
             throw new Error(`No skill root directory configured for tool '${this.toolId}'`);
         }
-        return root;
+        return descriptor;
     }
     getHomeRootPath() {
-        if (this.toolId === 'codex') {
+        const descriptor = this.getDescriptor();
+        if (descriptor.homeBase === 'codex-home') {
             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);
+        return os.homedir();
     }
     getSkillName(id) {
         return `lightspec-${id}`;

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

@@ -1,4 +1,4 @@
-import { AGENT_SKILL_TOOL_IDS, AgentSkillConfigurator, } from './base.js';
+import { AGENT_SKILL_TOOL_IDS, AgentSkillConfigurator, normalizeAgentSkillToolId, } from './base.js';
 export class AgentSkillRegistry {
     static configurators = new Map();
     static {
@@ -10,7 +10,7 @@ export class AgentSkillRegistry {
         this.configurators.set(configurator.toolId, configurator);
     }
     static get(toolId) {
-        return this.configurators.get(toolId);
+        return this.configurators.get(normalizeAgentSkillToolId(toolId));
     }
     static getAll() {
         return Array.from(this.configurators.values());

package/dist/core/init.d.ts

@@ -40,6 +40,7 @@ export declare class InitCommand {
     private getSkillInstallLocation;
     private getSelectedTools;
     private resolveToolsArg;
+    private normalizeSelectedTools;
     private promptForAITools;
     private getExistingToolStates;
     private isToolConfigured;

package/dist/core/init.js

@@ -7,7 +7,7 @@ import { FileSystemUtils } from '../utils/file-system.js';
 import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { AgentSkillRegistry } from './configurators/skills/registry.js';
-import { AI_TOOLS, LIGHTSPEC_DIR_NAME, LIGHTSPEC_MARKERS, } from './config.js';
+import { AI_TOOLS, LIGHTSPEC_DIR_NAME, LIGHTSPEC_MARKERS, normalizeToolId, } from './config.js';
 import { PALETTE } from './styles/palette.js';
 const PROGRESS_SPINNER = {
     interval: 80,
@@ -41,8 +41,6 @@ const parseToolLabel = (raw) => {
 };
 const isSelectableChoice = (choice) => choice.selectable;
 const ROOT_STUB_CHOICE_VALUE = '__root_stub__';
-const OTHER_TOOLS_HEADING_VALUE = '__heading-other__';
-const LIST_SPACER_VALUE = '__list-spacer__';
 const toolSelectionWizard = createPrompt((config, done) => {
     const totalSteps = 3;
     const [step, setStep] = useState('intro');
@@ -340,10 +338,10 @@ export class InitCommand {
     async getSelectedTools(existingTools, extendMode) {
         const nonInteractiveSelection = this.resolveToolsArg();
         if (nonInteractiveSelection !== null) {
-            return nonInteractiveSelection;
+            return this.normalizeSelectedTools(nonInteractiveSelection);
         }
         // Fall back to interactive mode
-        return this.promptForAITools(existingTools, extendMode);
+        return this.normalizeSelectedTools(await this.promptForAITools(existingTools, extendMode));
     }
     resolveToolsArg() {
         if (typeof this.toolsArg === 'undefined') {
@@ -371,7 +369,7 @@ export class InitCommand {
         if (tokens.length === 0) {
             throw new Error('The --tools option requires at least one tool ID when not using "all" or "none".');
         }
-        const normalizedTokens = tokens.map((token) => token.toLowerCase());
+        const normalizedTokens = tokens.map((token) => normalizeToolId(token));
         if (normalizedTokens.some((token) => token === 'all' || token === 'none')) {
             throw new Error('Cannot combine reserved values "all" or "none" with specific tool IDs.');
         }
@@ -387,6 +385,18 @@ export class InitCommand {
         }
         return deduped;
     }
+    normalizeSelectedTools(selected) {
+        const availableSet = new Set(AI_TOOLS.filter((tool) => tool.available).map((tool) => tool.value));
+        const normalized = [];
+        for (const toolId of selected) {
+            const canonical = normalizeToolId(toolId);
+            if (!availableSet.has(canonical) || normalized.includes(canonical)) {
+                continue;
+            }
+            normalized.push(canonical);
+        }
+        return normalized;
+    }
     async promptForAITools(existingTools, extendMode) {
         const availableTools = AI_TOOLS.filter((tool) => tool.available);
         const baseMessage = extendMode
@@ -396,7 +406,7 @@ export class InitCommand {
             ? availableTools
                 .filter((tool) => existingTools[tool.value])
                 .map((tool) => tool.value)
-            : [];
+            : ['universal'];
         const initialSelected = Array.from(new Set(initialNativeSelection));
         const choices = [
             {
@@ -414,34 +424,6 @@ export class InitCommand {
                 configured: Boolean(existingTools[tool.value]),
                 selectable: true,
             })),
-            ...(availableTools.length
-                ? [
-                    {
-                        kind: 'info',
-                        value: LIST_SPACER_VALUE,
-                        label: { primary: '' },
-                        selectable: false,
-                    },
-                ]
-                : []),
-            {
-                kind: 'heading',
-                value: OTHER_TOOLS_HEADING_VALUE,
-                label: {
-                    primary: 'Other tools (use Universal AGENTS.md for Amp, VS Code, GitHub Copilot, …)',
-                },
-                selectable: false,
-            },
-            {
-                kind: 'option',
-                value: ROOT_STUB_CHOICE_VALUE,
-                label: {
-                    primary: 'Universal AGENTS.md',
-                    annotation: 'always available',
-                },
-                configured: extendMode,
-                selectable: true,
-            },
         ];
         return this.prompt({
             extendMode,
@@ -485,10 +467,15 @@ export class InitCommand {
         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))) {
-                    hasSkills = true;
-                    break; // At least one file with markers is sufficient
+                const candidates = skillConfigurator.resolveExistingAbsolutePaths(projectPath, target.id);
+                for (const candidate of candidates) {
+                    if ((await FileSystemUtils.fileExists(candidate.absolutePath)) && (await fileHasMarkers(candidate.absolutePath))) {
+                        hasSkills = true;
+                        break; // At least one file with markers is sufficient
+                    }
+                }
+                if (hasSkills) {
+                    break;
                 }
             }
         }
@@ -560,7 +547,7 @@ export class InitCommand {
         return rootStubStatus;
     }
     async configureRootAgentsStub(projectPath, lightspecDir) {
-        const configurator = ToolRegistry.get('agents');
+        const configurator = ToolRegistry.get('universal');
         if (!configurator || !configurator.isAvailable) {
             return 'skipped';
         }

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

@@ -1,4 +1,4 @@
-export type AgentSkillId = 'proposal' | 'apply' | 'archive' | 'agentsmd-check';
+export type AgentSkillId = 'proposal' | 'apply' | 'archive' | 'agentsmd-check' | 'loop';
 export declare const agentSkillBodies: Record<AgentSkillId, string>;
 export declare const agentSkillFrontmatter: Record<AgentSkillId, string>;
 export declare function getAgentSkillBody(id: AgentSkillId): string;

package/dist/core/templates/agent-skill-templates.js

@@ -2,17 +2,20 @@ import { applyTemplate, applyFrontmatter } from './apply-template.js';
 import { archiveTemplate, archiveFrontmatter } from './archive-template.js';
 import { proposalTemplate, proposalFrontmatter } from './proposal-template.js';
 import { agentsmdCheckTemplate, agentsmdCheckFrontmatter, } from './agentsmd-check-template.js';
+import { loopTemplate, loopFrontmatter } from './loop-template.js';
 export const agentSkillBodies = {
     proposal: proposalTemplate,
     apply: applyTemplate,
     archive: archiveTemplate,
     'agentsmd-check': agentsmdCheckTemplate,
+    loop: loopTemplate,
 };
 export const agentSkillFrontmatter = {
     proposal: proposalFrontmatter,
     apply: applyFrontmatter,
     archive: archiveFrontmatter,
     'agentsmd-check': agentsmdCheckFrontmatter,
+    loop: loopFrontmatter,
 };
 export function getAgentSkillBody(id) {
     return agentSkillBodies[id];

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\n**If (and only if) the feature is complex** (new capability, breaking change, architecture/performance/security work), follow these steps:\n\n- [ ] Suggest switching to `/plan` mode before writing the proposal if it's not already the case\n- [ ] Run `lightspec-proposal`.\n- [ ] Do not implement the feature until the proposal is approved by the user. Implementation MUST be operated using `lightspec-apply` to ensure the implementation is properly tracked and documented.\n- [ ] If unsure which skill to run, list installed skills.\n\nKeep this managed block so 'lightspec update' can refresh the instructions.\n";
+export declare const agentsRootStubTemplate = "# LightSpec Instructions\n\nIF (and only if) the user message:\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\nTHEN: \nDo the following:\n- [ ] Suggest switching to `/plan` mode before writing the proposal if it's not already the case\n- [ ] When the user approves the plan and terminates planning mode, run `lightspec-apply` to implement the approved proposal.\n- [ ] Run `lightspec-proposal`.\n- [ ] Do not implement the feature until the proposal is approved by the user. Implementation MUST be operated using `lightspec-apply` to ensure the implementation is properly tracked and documented.\n- [ ] If unsure which skill to run, list installed skills.\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

@@ -1,10 +1,14 @@
 export const agentsRootStubTemplate = `# LightSpec Instructions
 
-These instructions are for AI assistants working in this project.
-
-**If (and only if) the feature is complex** (new capability, breaking change, architecture/performance/security work), follow these steps:
+IF (and only if) the user message:
+  - 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
 
+THEN: 
+Do the following:
 - [ ] Suggest switching to \`/plan\` mode before writing the proposal if it's not already the case
+- [ ] When the user approves the plan and terminates planning mode, run \`lightspec-apply\` to implement the approved proposal.
 - [ ] Run \`lightspec-proposal\`.
 - [ ] Do not implement the feature until the proposal is approved by the user. Implementation MUST be operated using \`lightspec-apply\` to ensure the implementation is properly tracked and documented.
 - [ ] If unsure which skill to run, list installed skills.

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

@@ -0,0 +1,3 @@
+export declare const loopFrontmatter = "---\nname: lightspec-loop\ndescription: Use when systematically implementing LightSpec change proposals through clean, sequential delegation. For instance, when the user applies the plan using /lightspec:apply.\ndisable-model-invocation: false\nuser-invocable: true\nmetadata:\n  source: lightspec\n  workflow: loop\n---";
+export declare const loopTemplate = "# LightSpec Loop: Subagent-Driven Implementation\n\nImplement LightSpec changes by dispatching a fresh subagent per change, with clean context isolation and sequential execution.\n\n**Core principle:** fresh subagent per change + sequential execution + clean context = isolated, predictable implementation.\n\n## When To Use\n- You have multiple active LightSpec changes to implement.\n- The changes are mostly independent.\n- You want strict context isolation between change implementations.\n\n## Process\n1. Run `lightspec list` to discover active changes.\n2. Present active change IDs to the user and confirm the execution order.\n3. For each change ID, execute the cycle below sequentially:\n   - Dispatch a fresh general-purpose subagent.\n   - First subagent action: clear context (for example, `/clear` if your assistant supports it).\n   - Run `lightspec apply <change-id>`.\n   - Implement all required code/docs/tests.\n   - Run `lightspec archive <change-id> --yes` once implementation is complete.\n   - Verify the archive succeeded before moving to the next change.\n4. After all requested changes are processed, provide a concise completion summary.\n\n## Subagent Instruction Template\n```\nYou are implementing one specific LightSpec change. Follow this workflow:\n1. First action: clear your context to avoid contamination from prior work.\n2. Run: lightspec apply <change-id>\n3. Implement all tasks in the change proposal.\n4. Archive the completed change: lightspec archive <change-id> --yes\n5. Report completion status and stop.\n```\n\n## Operational Constraints\n**Never**\n- Implement LightSpec changes in parallel.\n- Skip context reset between change implementations.\n- Move to the next change before confirming archive success for the current one.\n\n**Always**\n- Confirm the change ID exists before starting.\n- Ask the user how to proceed on failure (retry, skip, abort).\n- Keep a running status list: total, current, completed, remaining.\n\n## Error Handling\n- If a subagent fails implementation, report the failure and ask whether to retry with a fresh subagent, skip, or abort.\n- If `lightspec apply` or `lightspec archive` fails, stop and request user confirmation before continuing.\n\n## Integration\n- Uses `lightspec-apply` workflow semantics through `lightspec apply <change-id>`.\n- Uses `lightspec-archive` workflow semantics through `lightspec archive <change-id> --yes`.\n";
+//# sourceMappingURL=loop-template.d.ts.map

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

@@ -0,0 +1,62 @@
+export const loopFrontmatter = `---
+name: lightspec-loop
+description: Use when systematically implementing LightSpec change proposals through clean, sequential delegation. For instance, when the user applies the plan using /lightspec:apply.
+disable-model-invocation: false
+user-invocable: true
+metadata:
+  source: lightspec
+  workflow: loop
+---`;
+export const loopTemplate = `# LightSpec Loop: Subagent-Driven Implementation
+
+Implement LightSpec changes by dispatching a fresh subagent per change, with clean context isolation and sequential execution.
+
+**Core principle:** fresh subagent per change + sequential execution + clean context = isolated, predictable implementation.
+
+## When To Use
+- You have multiple active LightSpec changes to implement.
+- The changes are mostly independent.
+- You want strict context isolation between change implementations.
+
+## Process
+1. Run \`lightspec list\` to discover active changes.
+2. Present active change IDs to the user and confirm the execution order.
+3. For each change ID, execute the cycle below sequentially:
+   - Dispatch a fresh general-purpose subagent.
+   - First subagent action: clear context (for example, \`/clear\` if your assistant supports it).
+   - Run \`lightspec apply <change-id>\`.
+   - Implement all required code/docs/tests.
+   - Run \`lightspec archive <change-id> --yes\` once implementation is complete.
+   - Verify the archive succeeded before moving to the next change.
+4. After all requested changes are processed, provide a concise completion summary.
+
+## Subagent Instruction Template
+\`\`\`
+You are implementing one specific LightSpec change. Follow this workflow:
+1. First action: clear your context to avoid contamination from prior work.
+2. Run: lightspec apply <change-id>
+3. Implement all tasks in the change proposal.
+4. Archive the completed change: lightspec archive <change-id> --yes
+5. Report completion status and stop.
+\`\`\`
+
+## Operational Constraints
+**Never**
+- Implement LightSpec changes in parallel.
+- Skip context reset between change implementations.
+- Move to the next change before confirming archive success for the current one.
+
+**Always**
+- Confirm the change ID exists before starting.
+- Ask the user how to proceed on failure (retry, skip, abort).
+- Keep a running status list: total, current, completed, remaining.
+
+## Error Handling
+- If a subagent fails implementation, report the failure and ask whether to retry with a fresh subagent, skip, or abort.
+- If \`lightspec apply\` or \`lightspec archive\` fails, stop and request user confirmation before continuing.
+
+## Integration
+- Uses \`lightspec-apply\` workflow semantics through \`lightspec apply <change-id>\`.
+- Uses \`lightspec-archive\` workflow semantics through \`lightspec archive <change-id> --yes\`.
+`;
+//# sourceMappingURL=loop-template.js.map

package/dist/core/update.js

@@ -71,7 +71,7 @@ export class UpdateCommand {
         }
         if (updatedSkillFiles.length > 0) {
             // Normalize to forward slashes for cross-platform log consistency
-            const normalized = updatedSkillFiles.map((p) => FileSystemUtils.toPosixPath(p));
+            const normalized = Array.from(new Set(updatedSkillFiles.map((p) => FileSystemUtils.toPosixPath(p))));
             summaryParts.push(`Updated skills: ${normalized.join(', ')}`);
         }
         const failedItems = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightspec",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "lightspec",