@fission-ai/openspec 0.5.0 → 0.7.0

package/README.md

@@ -84,6 +84,9 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
 | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
+
+Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
 
 #### AGENTS.md Compatible
 These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
@@ -121,8 +124,8 @@ openspec init
 ```
 
 **What happens during initialization:**
-- You'll be prompted to select your AI tool (Claude Code, Cursor, etc.)
-- OpenSpec automatically configures slash commands or `AGENTS.md` based on your selection
+- You'll be prompted to pick any natively supported AI tools (Claude Code, Cursor, OpenCode, etc.); other assistants always rely on the shared `AGENTS.md` stub
+- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
 - A new `openspec/` directory structure is created in your project
 
 **After setup:**

package/dist/core/config.js

@@ -4,9 +4,10 @@ export const OPENSPEC_MARKERS = {
     end: '<!-- OPENSPEC:END -->'
 };
 export const AI_TOOLS = [
-    { name: 'Claude Code (✅ OpenSpec custom slash commands available)', value: 'claude', available: true, successLabel: 'Claude Code' },
-    { name: 'Cursor (✅ OpenSpec custom slash commands available)', value: 'cursor', available: true, successLabel: 'Cursor' },
-    { name: 'OpenCode (✅ OpenSpec custom slash commands available)', value: 'opencode', available: true, successLabel: 'OpenCode' },
-    { name: 'AGENTS.md (works with Codex, Amp, Copilot, …)', value: 'agents', available: true, successLabel: 'your AGENTS.md-compatible assistant' }
+    { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code' },
+    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor' },
+    { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode' },
+    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code' },
+    { name: 'AGENTS.md (works with Codex, Amp, VS Code, GitHub Copilot, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
 ];
 //# sourceMappingURL=config.js.map

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

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

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

@@ -0,0 +1,17 @@
+import { SlashCommandConfigurator } from "./base.js";
+const FILE_PATHS = {
+    proposal: ".kilocode/workflows/openspec-proposal.md",
+    apply: ".kilocode/workflows/openspec-apply.md",
+    archive: ".kilocode/workflows/openspec-archive.md"
+};
+export class KiloCodeSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = "kilocode";
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(_id) {
+        return undefined;
+    }
+}
+//# sourceMappingURL=kilocode.js.map

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

@@ -1,14 +1,17 @@
 import { ClaudeSlashCommandConfigurator } from './claude.js';
 import { CursorSlashCommandConfigurator } from './cursor.js';
+import { KiloCodeSlashCommandConfigurator } from './kilocode.js';
 import { OpenCodeSlashCommandConfigurator } from './opencode.js';
 export class SlashCommandRegistry {
     static configurators = new Map();
     static {
         const claude = new ClaudeSlashCommandConfigurator();
         const cursor = new CursorSlashCommandConfigurator();
+        const kilocode = new KiloCodeSlashCommandConfigurator();
         const opencode = new OpenCodeSlashCommandConfigurator();
         this.configurators.set(claude.toolId, claude);
         this.configurators.set(cursor.toolId, cursor);
+        this.configurators.set(kilocode.toolId, kilocode);
         this.configurators.set(opencode.toolId, opencode);
     }
     static register(configurator) {

package/dist/core/init.d.ts

@@ -3,9 +3,16 @@ type ToolLabel = {
     annotation?: string;
 };
 type ToolWizardChoice = {
+    kind: 'heading' | 'info';
+    value: string;
+    label: ToolLabel;
+    selectable: false;
+} | {
+    kind: 'option';
     value: string;
     label: ToolLabel;
     configured: boolean;
+    selectable: true;
 };
 type ToolWizardConfig = {
     extendMode: boolean;
@@ -29,6 +36,7 @@ export declare class InitCommand {
     private createDirectoryStructure;
     private generateFiles;
     private configureAITools;
+    private configureRootAgentsStub;
     private displaySuccessMessage;
     private formatToolNames;
     private renderBanner;

package/dist/core/init.js

@@ -7,16 +7,11 @@ import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME, } from './config.js';
+import { PALETTE } from './styles/palette.js';
 const PROGRESS_SPINNER = {
     interval: 80,
     frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓'],
 };
-const PALETTE = {
-    white: chalk.hex('#f4f4f4'),
-    lightGray: chalk.hex('#c8c8c8'),
-    midGray: chalk.hex('#8a8a8a'),
-    darkGray: chalk.hex('#4a4a4a'),
-};
 const LETTER_MAP = {
     O: [' ████ ', '██  ██', '██  ██', '██  ██', ' ████ '],
     P: ['█████ ', '██  ██', '█████ ', '██    ', '██    '],
@@ -38,16 +33,27 @@ const parseToolLabel = (raw) => {
         annotation: match[2].trim(),
     };
 };
+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');
-    const [cursor, setCursor] = useState(0);
-    const [selected, setSelected] = useState(() => config.initialSelected ?? []);
+    const selectableChoices = config.choices.filter(isSelectableChoice);
+    const initialCursorIndex = config.choices.findIndex((choice) => choice.selectable);
+    const [cursor, setCursor] = useState(initialCursorIndex === -1 ? 0 : initialCursorIndex);
+    const [selected, setSelected] = useState(() => {
+        const initial = new Set((config.initialSelected ?? []).filter((value) => selectableChoices.some((choice) => choice.value === value)));
+        return selectableChoices
+            .map((choice) => choice.value)
+            .filter((value) => initial.has(value));
+    });
     const [error, setError] = useState(null);
     const selectedSet = new Set(selected);
-    const pageSize = Math.max(Math.min(config.choices.length, 7), 1);
+    const pageSize = Math.max(config.choices.length, 1);
     const updateSelected = (next) => {
-        const ordered = config.choices
+        const ordered = selectableChoices
             .map((choice) => choice.value)
             .filter((value) => next.has(value));
         setSelected(ordered);
@@ -56,8 +62,13 @@ const toolSelectionWizard = createPrompt((config, done) => {
         items: config.choices,
         active: cursor,
         pageSize,
-        loop: config.choices.length > 1,
+        loop: false,
         renderItem: ({ item, isActive }) => {
+            if (!item.selectable) {
+                const prefix = item.kind === 'info' ? '  ' : '';
+                const textColor = item.kind === 'heading' ? PALETTE.lightGray : PALETTE.midGray;
+                return `${PALETTE.midGray(' ')} ${PALETTE.midGray(' ')} ${textColor(`${prefix}${item.label.primary}`)}`;
+            }
             const isSelected = selectedSet.has(item.value);
             const cursorSymbol = isActive
                 ? PALETTE.white('›')
@@ -66,10 +77,32 @@ const toolSelectionWizard = createPrompt((config, done) => {
                 ? PALETTE.white('◉')
                 : PALETTE.midGray('○');
             const nameColor = isActive ? PALETTE.white : PALETTE.midGray;
-            const label = `${nameColor(item.label.primary)}${item.configured ? PALETTE.midGray(' (already configured)') : ''}`;
+            const annotation = item.label.annotation
+                ? PALETTE.midGray(` (${item.label.annotation})`)
+                : '';
+            const configuredNote = item.configured
+                ? PALETTE.midGray(' (already configured)')
+                : '';
+            const label = `${nameColor(item.label.primary)}${annotation}${configuredNote}`;
             return `${cursorSymbol} ${indicator} ${label}`;
         },
     });
+    const moveCursor = (direction) => {
+        if (selectableChoices.length === 0) {
+            return;
+        }
+        let nextIndex = cursor;
+        while (true) {
+            nextIndex = nextIndex + direction;
+            if (nextIndex < 0 || nextIndex >= config.choices.length) {
+                return;
+            }
+            if (config.choices[nextIndex]?.selectable) {
+                setCursor(nextIndex);
+                return;
+            }
+        }
+    };
     useKeypress((key) => {
         if (step === 'intro') {
             if (isEnterKey(key)) {
@@ -79,20 +112,18 @@ const toolSelectionWizard = createPrompt((config, done) => {
         }
         if (step === 'select') {
             if (isUpKey(key)) {
-                const previousIndex = cursor <= 0 ? config.choices.length - 1 : cursor - 1;
-                setCursor(previousIndex);
+                moveCursor(-1);
                 setError(null);
                 return;
             }
             if (isDownKey(key)) {
-                const nextIndex = cursor >= config.choices.length - 1 ? 0 : cursor + 1;
-                setCursor(nextIndex);
+                moveCursor(1);
                 setError(null);
                 return;
             }
             if (isSpaceKey(key)) {
                 const current = config.choices[cursor];
-                if (!current)
+                if (!current || !current.selectable)
                     return;
                 const next = new Set(selected);
                 if (next.has(current.value)) {
@@ -106,16 +137,13 @@ const toolSelectionWizard = createPrompt((config, done) => {
                 return;
             }
             if (isEnterKey(key)) {
-                if (selected.length === 0) {
-                    setError('Select at least one AI tool to continue.');
-                    return;
-                }
                 setStep('review');
                 setError(null);
                 return;
             }
             if (key.name === 'escape') {
-                setSelected([]);
+                const next = new Set();
+                updateSelected(next);
                 setError(null);
             }
             return;
@@ -124,7 +152,7 @@ const toolSelectionWizard = createPrompt((config, done) => {
             if (isEnterKey(key)) {
                 const finalSelection = config.choices
                     .map((choice) => choice.value)
-                    .filter((value) => selectedSet.has(value));
+                    .filter((value) => selectedSet.has(value) && value !== ROOT_STUB_CHOICE_VALUE);
                 done(finalSelection);
                 return;
             }
@@ -134,9 +162,21 @@ const toolSelectionWizard = createPrompt((config, done) => {
             }
         }
     });
-    const selectedNames = config.choices
-        .filter((choice) => selectedSet.has(choice.value))
-        .map((choice) => choice.label.primary);
+    const rootStubChoice = selectableChoices.find((choice) => choice.value === ROOT_STUB_CHOICE_VALUE);
+    const rootStubSelected = rootStubChoice
+        ? selectedSet.has(ROOT_STUB_CHOICE_VALUE)
+        : false;
+    const nativeChoices = selectableChoices.filter((choice) => choice.value !== ROOT_STUB_CHOICE_VALUE);
+    const selectedNativeChoices = nativeChoices.filter((choice) => selectedSet.has(choice.value));
+    const formatSummaryLabel = (choice) => {
+        const annotation = choice.label.annotation
+            ? PALETTE.midGray(` (${choice.label.annotation})`)
+            : '';
+        const configuredNote = choice.configured
+            ? PALETTE.midGray(' (already configured)')
+            : '';
+        return `${PALETTE.white(choice.label.primary)}${annotation}${configuredNote}`;
+    };
     const stepIndex = step === 'intro' ? 1 : step === 'select' ? 2 : 3;
     const lines = [];
     lines.push(PALETTE.midGray(`Step ${stepIndex}/${totalSteps}`));
@@ -159,13 +199,16 @@ const toolSelectionWizard = createPrompt((config, done) => {
         lines.push('');
         lines.push(page);
         lines.push('');
-        if (selectedNames.length === 0) {
-            lines.push(`${PALETTE.midGray('Selected')}: ${PALETTE.midGray('None selected yet')}`);
+        lines.push(PALETTE.midGray('Selected configuration:'));
+        if (rootStubSelected && rootStubChoice) {
+            lines.push(`  ${PALETTE.white('-')} ${formatSummaryLabel(rootStubChoice)}`);
+        }
+        if (selectedNativeChoices.length === 0) {
+            lines.push(`  ${PALETTE.midGray('- No natively supported providers selected')}`);
         }
         else {
-            lines.push(PALETTE.midGray('Selected:'));
-            selectedNames.forEach((name) => {
-                lines.push(`  ${PALETTE.white('-')} ${PALETTE.white(name)}`);
+            selectedNativeChoices.forEach((choice) => {
+                lines.push(`  ${PALETTE.white('-')} ${formatSummaryLabel(choice)}`);
             });
         }
     }
@@ -173,12 +216,15 @@ const toolSelectionWizard = createPrompt((config, done) => {
         lines.push(PALETTE.white('Review selections'));
         lines.push(PALETTE.midGray('Press Enter to confirm or Backspace to adjust.'));
         lines.push('');
-        if (selectedNames.length === 0) {
-            lines.push(PALETTE.midGray('No tools selected. Press Backspace to return.'));
+        if (rootStubSelected && rootStubChoice) {
+            lines.push(`${PALETTE.white('▌')} ${formatSummaryLabel(rootStubChoice)}`);
+        }
+        if (selectedNativeChoices.length === 0) {
+            lines.push(PALETTE.midGray('No natively supported providers selected. Universal instructions will still be applied.'));
         }
         else {
-            selectedNames.forEach((name) => {
-                lines.push(`${PALETTE.white('▌')} ${PALETTE.white(name)}`);
+            selectedNativeChoices.forEach((choice) => {
+                lines.push(`${PALETTE.white('▌')} ${formatSummaryLabel(choice)}`);
             });
         }
     }
@@ -202,13 +248,6 @@ export class InitCommand {
         this.renderBanner(extendMode);
         // Get configuration (after validation to avoid prompts if validation fails)
         const config = await this.getConfiguration(existingToolStates, extendMode);
-        if (config.aiTools.length === 0) {
-            if (extendMode) {
-                throw new Error(`OpenSpec seems to already be initialized at ${openspecPath}.\n` +
-                    `Use 'openspec update' to update the structure.`);
-            }
-            throw new Error('You must select at least one AI tool to configure.');
-        }
         const availableTools = AI_TOOLS.filter((tool) => tool.available);
         const selectedIds = new Set(config.aiTools);
         const selectedTools = availableTools.filter((tool) => selectedIds.has(tool.value));
@@ -231,13 +270,13 @@ export class InitCommand {
         }
         // Step 2: Configure AI tools
         const toolSpinner = this.startSpinner('Configuring AI tools...');
-        await this.configureAITools(projectPath, openspecDir, config.aiTools);
+        const rootStubStatus = await this.configureAITools(projectPath, openspecDir, config.aiTools);
         toolSpinner.stopAndPersist({
             symbol: PALETTE.white('▌'),
             text: PALETTE.white('AI tools configured'),
         });
         // Success message
-        this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode);
+        this.displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, rootStubStatus);
     }
     async validate(projectPath, _openspecPath) {
         const extendMode = await FileSystemUtils.directoryExists(_openspecPath);
@@ -253,25 +292,64 @@ export class InitCommand {
     }
     async promptForAITools(existingTools, extendMode) {
         const availableTools = AI_TOOLS.filter((tool) => tool.available);
-        if (availableTools.length === 0) {
-            return [];
-        }
         const baseMessage = extendMode
-            ? 'Which AI tools would you like to add or refresh?'
-            : 'Which AI tools do you use?';
-        const initialSelected = extendMode
+            ? 'Which natively supported AI tools would you like to add or refresh?'
+            : 'Which natively supported AI tools do you use?';
+        const initialNativeSelection = extendMode
             ? availableTools
                 .filter((tool) => existingTools[tool.value])
                 .map((tool) => tool.value)
             : [];
-        return this.prompt({
-            extendMode,
-            baseMessage,
-            choices: availableTools.map((tool) => ({
+        const initialSelected = Array.from(new Set(initialNativeSelection));
+        const choices = [
+            {
+                kind: 'heading',
+                value: '__heading-native__',
+                label: {
+                    primary: 'Natively supported providers (✔ OpenSpec custom slash commands available)',
+                },
+                selectable: false,
+            },
+            ...availableTools.map((tool) => ({
+                kind: 'option',
                 value: tool.value,
                 label: parseToolLabel(tool.name),
                 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 Codex, 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,
+            baseMessage,
+            choices,
             initialSelected,
         });
     }
@@ -321,6 +399,7 @@ export class InitCommand {
         }
     }
     async configureAITools(projectPath, openspecDir, toolIds) {
+        const rootStubStatus = await this.configureRootAgentsStub(projectPath, openspecDir);
         for (const toolId of toolIds) {
             const configurator = ToolRegistry.get(toolId);
             if (configurator && configurator.isAvailable) {
@@ -331,8 +410,19 @@ export class InitCommand {
                 await slashConfigurator.generateAll(projectPath, openspecDir);
             }
         }
+        return rootStubStatus;
     }
-    displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode) {
+    async configureRootAgentsStub(projectPath, openspecDir) {
+        const configurator = ToolRegistry.get('agents');
+        if (!configurator || !configurator.isAvailable) {
+            return 'skipped';
+        }
+        const stubPath = path.join(projectPath, configurator.configFileName);
+        const existed = await FileSystemUtils.fileExists(stubPath);
+        await configurator.configure(projectPath, openspecDir);
+        return existed ? 'updated' : 'created';
+    }
+    displaySuccessMessage(selectedTools, created, refreshed, skippedExisting, skipped, extendMode, rootStubStatus) {
         console.log(); // Empty line for spacing
         const successHeadline = extendMode
             ? 'OpenSpec tool configuration updated!'
@@ -341,6 +431,12 @@ export class InitCommand {
         console.log();
         console.log(PALETTE.lightGray('Tool summary:'));
         const summaryLines = [
+            rootStubStatus === 'created'
+                ? `${PALETTE.white('▌')} ${PALETTE.white('Root AGENTS.md stub created for other assistants')}`
+                : null,
+            rootStubStatus === 'updated'
+                ? `${PALETTE.lightGray('▌')} ${PALETTE.lightGray('Root AGENTS.md stub refreshed for other assistants')}`
+                : null,
             created.length
                 ? `${PALETTE.white('▌')} ${PALETTE.white('Created:')} ${this.formatToolNames(created)}`
                 : null,
@@ -380,7 +476,7 @@ export class InitCommand {
             .map((tool) => tool.successLabel ?? tool.name)
             .filter((name) => Boolean(name));
         if (names.length === 0)
-            return PALETTE.lightGray('your AI assistant');
+            return PALETTE.lightGray('your AGENTS.md-compatible assistant');
         if (names.length === 1)
             return PALETTE.white(names[0]);
         const base = names.slice(0, -1).map((name) => PALETTE.white(name));

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

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

package/dist/core/styles/palette.js

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

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

@@ -0,0 +1,2 @@
+export declare const agentsRootStubTemplate = "# OpenSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\nAlways open `@/openspec/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 `@/openspec/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 'openspec update' can refresh the instructions.\n";
+//# sourceMappingURL=agents-root-stub.d.ts.map

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

@@ -0,0 +1,17 @@
+export const agentsRootStubTemplate = `# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open \`@/openspec/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 \`@/openspec/AGENTS.md\` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+`;
+//# sourceMappingURL=agents-root-stub.js.map

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

@@ -1,2 +1,2 @@
-export { agentsTemplate as claudeTemplate } from './agents-template.js';
+export { agentsRootStubTemplate as claudeTemplate } from './agents-root-stub.js';
 //# sourceMappingURL=claude-template.d.ts.map

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

@@ -1,2 +1,2 @@
-export { agentsTemplate as claudeTemplate } from './agents-template.js';
+export { agentsRootStubTemplate as claudeTemplate } from './agents-root-stub.js';
 //# sourceMappingURL=claude-template.js.map

package/dist/core/templates/index.js

@@ -1,6 +1,7 @@
 import { agentsTemplate } from './agents-template.js';
 import { projectTemplate } from './project-template.js';
 import { claudeTemplate } from './claude-template.js';
+import { agentsRootStubTemplate } from './agents-root-stub.js';
 import { getSlashCommandBody } from './slash-command-templates.js';
 export class TemplateManager {
     static getTemplates(context = {}) {
@@ -19,7 +20,7 @@ export class TemplateManager {
         return claudeTemplate;
     }
     static getAgentsStandardTemplate() {
-        return agentsTemplate;
+        return agentsRootStubTemplate;
     }
     static getSlashCommandBody(id) {
         return getSlashCommandBody(id);

package/dist/core/templates/slash-command-templates.js

@@ -1,14 +1,14 @@
 const baseGuardrails = `**Guardrails**
 - Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
 - Keep changes tightly scoped to the requested outcome.
-- Refer to \`openspec/AGENTS.md\` if you need additional OpenSpec conventions or clarifications.`;
+- Refer to \`openspec/AGENTS.md\` (located inside the \`openspec/\` directory—run \`ls openspec\` or \`openspec update\` if you don't see it) if you need additional OpenSpec conventions or clarifications.`;
 const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.`;
 const proposalSteps = `**Steps**
 1. Review \`openspec/project.md\`, run \`openspec list\` and \`openspec list --specs\`, and inspect related code or docs (e.g., via \`rg\`/\`ls\`) to ground the proposal in current behaviour; note any gaps that require clarification.
 2. Choose a unique verb-led \`change-id\` and scaffold \`proposal.md\`, \`tasks.md\`, and \`design.md\` (when needed) under \`openspec/changes/<id>/\`.
 3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
 4. Capture architectural reasoning in \`design.md\` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
-5. Draft spec deltas in \`changes/<id>/specs/\` using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant.
+5. Draft spec deltas in \`changes/<id>/specs/<capability>/spec.md\` (one folder per capability) using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant.
 6. Draft \`tasks.md\` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
 7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.`;
 const proposalReferences = `**Reference**

package/dist/core/update.js

@@ -1,10 +1,9 @@
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
-import { agentsTemplate } from './templates/agents-template.js';
-import { TemplateManager } from './templates/index.js';
+import { OPENSPEC_DIR_NAME } from './config.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
+import { agentsTemplate } from './templates/agents-template.js';
 export class UpdateCommand {
     async execute(projectPath) {
         const resolvedProjectPath = path.resolve(projectPath);
@@ -16,34 +15,36 @@ export class UpdateCommand {
         }
         // 2. Update AGENTS.md (full replacement)
         const agentsPath = path.join(openspecPath, 'AGENTS.md');
-        const rootAgentsPath = path.join(resolvedProjectPath, 'AGENTS.md');
-        const rootAgentsExisted = await FileSystemUtils.fileExists(rootAgentsPath);
         await FileSystemUtils.writeFile(agentsPath, agentsTemplate);
-        const agentsStandardContent = TemplateManager.getAgentsStandardTemplate();
-        await FileSystemUtils.updateFileWithMarkers(rootAgentsPath, agentsStandardContent, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
         // 3. Update existing AI tool configuration files only
         const configurators = ToolRegistry.getAll();
         const slashConfigurators = SlashCommandRegistry.getAll();
-        let updatedFiles = [];
-        let failedFiles = [];
-        let updatedSlashFiles = [];
-        let failedSlashTools = [];
+        const updatedFiles = [];
+        const createdFiles = [];
+        const failedFiles = [];
+        const updatedSlashFiles = [];
+        const failedSlashTools = [];
         for (const configurator of configurators) {
             const configFilePath = path.join(resolvedProjectPath, configurator.configFileName);
-            // Only update if the file already exists
-            if (await FileSystemUtils.fileExists(configFilePath)) {
-                try {
-                    if (!await FileSystemUtils.canWriteFile(configFilePath)) {
-                        throw new Error(`Insufficient permissions to modify ${configurator.configFileName}`);
-                    }
-                    await configurator.configure(resolvedProjectPath, openspecPath);
-                    updatedFiles.push(configurator.configFileName);
+            const fileExists = await FileSystemUtils.fileExists(configFilePath);
+            const shouldConfigure = fileExists || configurator.configFileName === 'AGENTS.md';
+            if (!shouldConfigure) {
+                continue;
+            }
+            try {
+                if (fileExists && !await FileSystemUtils.canWriteFile(configFilePath)) {
+                    throw new Error(`Insufficient permissions to modify ${configurator.configFileName}`);
                 }
-                catch (error) {
-                    failedFiles.push(configurator.configFileName);
-                    console.error(`Failed to update ${configurator.configFileName}: ${error instanceof Error ? error.message : String(error)}`);
+                await configurator.configure(resolvedProjectPath, openspecPath);
+                updatedFiles.push(configurator.configFileName);
+                if (!fileExists) {
+                    createdFiles.push(configurator.configFileName);
                 }
             }
+            catch (error) {
+                failedFiles.push(configurator.configFileName);
+                console.error(`Failed to update ${configurator.configFileName}: ${error instanceof Error ? error.message : String(error)}`);
+            }
         }
         for (const slashConfigurator of slashConfigurators) {
             if (!slashConfigurator.isAvailable) {
@@ -51,30 +52,34 @@ export class UpdateCommand {
             }
             try {
                 const updated = await slashConfigurator.updateExisting(resolvedProjectPath, openspecPath);
-                updatedSlashFiles = updatedSlashFiles.concat(updated);
+                updatedSlashFiles.push(...updated);
             }
             catch (error) {
                 failedSlashTools.push(slashConfigurator.toolId);
                 console.error(`Failed to update slash commands for ${slashConfigurator.toolId}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        // 4. Success message (ASCII-safe)
-        const instructionUpdates = ['openspec/AGENTS.md'];
-        instructionUpdates.push(`AGENTS.md${rootAgentsExisted ? '' : ' (created)'}`);
-        const messages = [`Updated OpenSpec instructions (${instructionUpdates.join(', ')})`];
-        if (updatedFiles.length > 0) {
-            messages.push(`Updated AI tool files: ${updatedFiles.join(', ')}`);
+        const summaryParts = [];
+        const instructionFiles = ['openspec/AGENTS.md'];
+        if (updatedFiles.includes('AGENTS.md')) {
+            instructionFiles.push(createdFiles.includes('AGENTS.md') ? 'AGENTS.md (created)' : 'AGENTS.md');
         }
-        if (updatedSlashFiles.length > 0) {
-            messages.push(`Updated slash commands: ${updatedSlashFiles.join(', ')}`);
+        summaryParts.push(`Updated OpenSpec instructions (${instructionFiles.join(', ')})`);
+        const aiToolFiles = updatedFiles.filter((file) => file !== 'AGENTS.md');
+        if (aiToolFiles.length > 0) {
+            summaryParts.push(`Updated AI tool files: ${aiToolFiles.join(', ')}`);
         }
-        if (failedFiles.length > 0) {
-            messages.push(`Failed to update: ${failedFiles.join(', ')}`);
+        if (updatedSlashFiles.length > 0) {
+            summaryParts.push(`Updated slash commands: ${updatedSlashFiles.join(', ')}`);
         }
-        if (failedSlashTools.length > 0) {
-            messages.push(`Failed slash command updates: ${failedSlashTools.join(', ')}`);
+        const failedItems = [
+            ...failedFiles,
+            ...failedSlashTools.map((toolId) => `slash command refresh (${toolId})`),
+        ];
+        if (failedItems.length > 0) {
+            summaryParts.push(`Failed to update: ${failedItems.join(', ')}`);
         }
-        console.log(messages.join('\n'));
+        console.log(summaryParts.join(' | '));
     }
 }
 //# sourceMappingURL=update.js.map

package/dist/core/validation/constants.d.ts

@@ -26,7 +26,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";
-    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with .md files using delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
+    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
     readonly GUIDE_MISSING_SPEC_SECTIONS: "Missing required sections. Expected headers: \"## Purpose\" and \"## Requirements\". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...";
     readonly GUIDE_MISSING_CHANGE_SECTIONS: "Missing required sections. Expected headers: \"## Why\" and \"## What Changes\". Ensure deltas are documented in specs/ using delta headers.";
     readonly GUIDE_SCENARIO_FORMAT: "Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...";

package/dist/core/validation/constants.js

@@ -32,7 +32,7 @@ export const VALIDATION_MESSAGES = {
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
     // Guidance snippets (appended to primary messages for remediation)
-    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with .md files using delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
     GUIDE_MISSING_SPEC_SECTIONS: 'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
     GUIDE_MISSING_CHANGE_SECTIONS: 'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
     GUIDE_SCENARIO_FORMAT: 'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',

package/dist/utils/file-system.js

@@ -1,5 +1,34 @@
 import { promises as fs } from 'fs';
 import path from 'path';
+function isMarkerOnOwnLine(content, markerIndex, markerLength) {
+    let leftIndex = markerIndex - 1;
+    while (leftIndex >= 0 && content[leftIndex] !== '\n') {
+        const char = content[leftIndex];
+        if (char !== ' ' && char !== '\t' && char !== '\r') {
+            return false;
+        }
+        leftIndex--;
+    }
+    let rightIndex = markerIndex + markerLength;
+    while (rightIndex < content.length && content[rightIndex] !== '\n') {
+        const char = content[rightIndex];
+        if (char !== ' ' && char !== '\t' && char !== '\r') {
+            return false;
+        }
+        rightIndex++;
+    }
+    return true;
+}
+function findMarkerIndex(content, marker, fromIndex = 0) {
+    let currentIndex = content.indexOf(marker, fromIndex);
+    while (currentIndex !== -1) {
+        if (isMarkerOnOwnLine(content, currentIndex, marker.length)) {
+            return currentIndex;
+        }
+        currentIndex = content.indexOf(marker, currentIndex + marker.length);
+    }
+    return -1;
+}
 export class FileSystemUtils {
     static async createDirectory(dirPath) {
         await fs.mkdir(dirPath, { recursive: true });
@@ -56,9 +85,14 @@ export class FileSystemUtils {
         let existingContent = '';
         if (await this.fileExists(filePath)) {
             existingContent = await this.readFile(filePath);
-            const startIndex = existingContent.indexOf(startMarker);
-            const endIndex = existingContent.indexOf(endMarker);
+            const startIndex = findMarkerIndex(existingContent, startMarker);
+            const endIndex = startIndex !== -1
+                ? findMarkerIndex(existingContent, endMarker, startIndex + startMarker.length)
+                : findMarkerIndex(existingContent, endMarker);
             if (startIndex !== -1 && endIndex !== -1) {
+                if (endIndex < startIndex) {
+                    throw new Error(`Invalid marker state in ${filePath}. End marker appears before start marker.`);
+                }
                 const before = existingContent.substring(0, startIndex);
                 const after = existingContent.substring(endIndex + endMarker.length);
                 existingContent = before + startMarker + '\n' + content + '\n' + endMarker + after;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",