Merge pull request #69 from Fission-AI/feat/add-agents-md-config

feat(cli): add agents md standard support

Author: TabishB

README.md

@@ -102,10 +102,12 @@ openspec init
 
 # Select your AI tool:
 # "Which AI tool do you use?"
-#   > Claude Code
+#   > Claude Code (✅ OpenSpec custom slash commands available)
 #       Use /openspec:proposal, /openspec:apply, and /openspec:archive in Claude Code to run proposals, apply tasks, and archive changes.
-#     Cursor
+#     Cursor (✅ OpenSpec custom slash commands available)
 #       Use /openspec-proposal, /openspec-apply, and /openspec-archive in Cursor for proposals, implementation, and archiving.
+#     AGENTS.md (works with Codex, Amp, Copilot, …)
+#       Creates/updates a root-level AGENTS.md block for tools that follow the AGENTS.md convention (Codex, Amp, Jules, OpenCode, Gemini CLI, GitHub Copilot, etc.)
 
 # This creates:
 # openspec/
@@ -287,7 +289,7 @@ Without specs, AI coding assistants generate code based on vague prompts, often
    - Local dependency: `pnpm add @fission-ai/openspec@latest`
    - Global CLI: `npm install -g @fission-ai/openspec@latest`
 2. **Refresh agent instructions**
-   - Run `openspec update` inside each project to regenerate AI instructions and refresh slash-command bindings.
+   - Run `openspec update` inside each project to regenerate AI instructions, refresh the root `AGENTS.md`, and update slash-command bindings.
 
 Run the update step after every version bump (or when switching tools) so your agents always pick up the latest guidance.
 

openspec/changes/add-agents-md-config/specs/cli-init/spec.md

@@ -6,12 +6,9 @@ The command SHALL configure AI coding assistants with OpenSpec instructions base
 
 - **WHEN** run
 - **THEN** prompt user to select AI tools to configure:
-  - Claude Code
-  - AGENTS.md standard
-- **AND** show disabled options as "coming soon" (not selectable):
-  - Cursor (coming soon)
-  - Aider (coming soon)
-  - Continue (coming soon)
+  - Claude Code (✅ OpenSpec custom slash commands available)
+  - Cursor (✅ OpenSpec custom slash commands available)
+  - AGENTS.md (works with Codex, Amp, Copilot, …)
 
 ### Requirement: AI Tool Configuration Details
 The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system.

openspec/changes/add-agents-md-config/tasks.md

@@ -1,17 +1,17 @@
 # Implementation Tasks
 
 ## 1. Extend Init Workflow
-- [ ] 1.1 Add an "AGENTS.md standard" option to the `openspec init` tool-selection prompt, respecting the existing UI conventions.
-- [ ] 1.2 Generate or refresh a root-level `AGENTS.md` file using the OpenSpec markers when that option is selected, sourcing content from the canonical template.
+- [x] 1.1 Add an "AGENTS.md standard" option to the `openspec init` tool-selection prompt, respecting the existing UI conventions.
+- [x] 1.2 Generate or refresh a root-level `AGENTS.md` file using the OpenSpec markers when that option is selected, sourcing content from the canonical template.
 
 ## 2. Enhance Update Command
-- [ ] 2.1 Ensure `openspec update` writes the root `AGENTS.md` from the latest template (creating it if missing) alongside `openspec/AGENTS.md`.
-- [ ] 2.2 Update success messaging and logging to reflect creation vs refresh of the AGENTS standard file.
+- [x] 2.1 Ensure `openspec update` writes the root `AGENTS.md` from the latest template (creating it if missing) alongside `openspec/AGENTS.md`.
+- [x] 2.2 Update success messaging and logging to reflect creation vs refresh of the AGENTS standard file.
 
 ## 3. Shared Template Handling
-- [ ] 3.1 Refactor template utilities if necessary so both commands reuse the same content without duplication.
-- [ ] 3.2 Add automated tests covering init/update flows for projects with and without an existing `AGENTS.md`, ensuring markers behave correctly.
+- [x] 3.1 Refactor template utilities if necessary so both commands reuse the same content without duplication.
+- [x] 3.2 Add automated tests covering init/update flows for projects with and without an existing `AGENTS.md`, ensuring markers behave correctly.
 
 ## 4. Documentation
-- [ ] 4.1 Update CLI specs and user-facing docs to describe AGENTS standard support.
-- [ ] 4.2 Run `openspec validate add-agents-md-config --strict` and document any notable behavior changes.
+- [x] 4.1 Update CLI specs and user-facing docs to describe AGENTS standard support.
+- [x] 4.2 Run `openspec validate add-agents-md-config --strict` and document any notable behavior changes.

src/core/config.ts

@@ -1,17 +1,23 @@
 export const OPENSPEC_DIR_NAME = 'openspec';
 
-export interface OpenSpecConfig {
-  aiTools: string[];
-}
-
 export const OPENSPEC_MARKERS = {
   start: '<!-- OPENSPEC:START -->',
   end: '<!-- OPENSPEC:END -->'
 };
 
-export const AI_TOOLS = [
-  { name: 'Claude Code', value: 'claude', available: true },
-  { name: 'Cursor', value: 'cursor', available: true },
-  { name: 'Aider', value: 'aider', available: false },
-  { name: 'Continue', value: 'continue', available: false }
+export interface OpenSpecConfig {
+  aiTools: string[];
+}
+
+export interface AIToolOption {
+  name: string;
+  value: string;
+  available: boolean;
+  successLabel?: string;
+}
+
+export const AI_TOOLS: AIToolOption[] = [
+  { 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: 'AGENTS.md (works with Codex, Amp, Copilot, …)', value: 'agents', available: true, successLabel: 'your AGENTS.md-compatible assistant' }
 ];

src/core/configurators/agents.ts

@@ -0,0 +1,23 @@
+import path from 'path';
+import { ToolConfigurator } from './base.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { TemplateManager } from '../templates/index.js';
+import { OPENSPEC_MARKERS } from '../config.js';
+
+export class AgentsStandardConfigurator implements ToolConfigurator {
+  name = 'AGENTS.md standard';
+  configFileName = 'AGENTS.md';
+  isAvailable = true;
+
+  async configure(projectPath: string, _openspecDir: string): Promise<void> {
+    const filePath = path.join(projectPath, this.configFileName);
+    const content = TemplateManager.getAgentsStandardTemplate();
+
+    await FileSystemUtils.updateFileWithMarkers(
+      filePath,
+      content,
+      OPENSPEC_MARKERS.start,
+      OPENSPEC_MARKERS.end
+    );
+  }
+}

src/core/configurators/registry.ts

@@ -1,13 +1,16 @@
 import { ToolConfigurator } from './base.js';
 import { ClaudeConfigurator } from './claude.js';
+import { AgentsStandardConfigurator } from './agents.js';
 
 export class ToolRegistry {
   private static tools: Map<string, ToolConfigurator> = new Map();
 
   static {
     const claudeConfigurator = new ClaudeConfigurator();
+    const agentsConfigurator = new AgentsStandardConfigurator();
     // Register with the ID that matches the checkbox value
     this.tools.set('claude', claudeConfigurator);
+    this.tools.set('agents', agentsConfigurator);
   }
 
   static register(tool: ToolConfigurator): void {
@@ -25,4 +28,4 @@ export class ToolRegistry {
   static getAvailable(): ToolConfigurator[] {
     return this.getAll().filter(tool => tool.isAvailable);
   }
-}
+}

src/core/init.ts

@@ -121,7 +121,7 @@ export class InitCommand {
     // Get the selected tool name for display
     const selectedToolId = config.aiTools[0];
     const selectedTool = AI_TOOLS.find(t => t.value === selectedToolId);
-    const toolName = selectedTool ? selectedTool.name : 'your AI assistant';
+    const toolName = selectedTool?.successLabel ?? selectedTool?.name ?? 'your AI assistant';
 
     console.log(`\nNext steps - Copy these prompts to ${toolName}:\n`);
     console.log('────────────────────────────────────────────────────────────');

src/core/templates/index.ts

@@ -26,6 +26,10 @@ export class TemplateManager {
     return claudeTemplate;
   }
 
+  static getAgentsStandardTemplate(): string {
+    return claudeTemplate;
+  }
+
   static getSlashCommandBody(id: SlashCommandId): string {
     return getSlashCommandBody(id);
   }

src/core/update.ts

@@ -1,7 +1,8 @@
 import path from 'path';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { OPENSPEC_DIR_NAME } from './config.js';
+import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
 import { agentsTemplate } from './templates/agents-template.js';
+import { TemplateManager } from './templates/index.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 
@@ -18,7 +19,17 @@ 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();
@@ -63,7 +74,10 @@ export class UpdateCommand {
     }
 
     // 4. Success message (ASCII-safe)
-    const messages: string[] = ['Updated OpenSpec instructions (AGENTS.md)'];
+    const instructionUpdates = ['openspec/AGENTS.md'];
+    instructionUpdates.push(`AGENTS.md${rootAgentsExisted ? '' : ' (created)'}`);
+
+    const messages: string[] = [`Updated OpenSpec instructions (${instructionUpdates.join(', ')})`];
 
     if (updatedFiles.length > 0) {
       messages.push(`Updated AI tool files: ${updatedFiles.join(', ')}`);

test/core/init.test.ts

@@ -86,6 +86,23 @@ describe('InitCommand', () => {
       expect(updatedContent).toContain('Custom instructions here');
     });
 
+    it('should create AGENTS.md in project root when AGENTS standard is selected', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('agents');
+
+      await initCommand.execute(testDir);
+
+      const rootAgentsPath = path.join(testDir, 'AGENTS.md');
+      expect(await fileExists(rootAgentsPath)).toBe(true);
+
+      const content = await fs.readFile(rootAgentsPath, 'utf-8');
+      expect(content).toContain('<!-- OPENSPEC:START -->');
+      expect(content).toContain('OpenSpec Project');
+      expect(content).toContain('<!-- OPENSPEC:END -->');
+
+      const claudeExists = await fileExists(path.join(testDir, 'CLAUDE.md'));
+      expect(claudeExists).toBe(false);
+    });
+
     it('should create Claude slash command files with templates', async () => {
       vi.mocked(prompts.select).mockResolvedValue('claude');
 
@@ -168,6 +185,16 @@ describe('InitCommand', () => {
       const calls = logSpy.mock.calls.flat().join('\n');
       expect(calls).toContain('Copy these prompts to Claude Code');
     });
+
+    it('should reference AGENTS compatible assistants in success message', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('agents');
+      const logSpy = vi.spyOn(console, 'log');
+
+      await initCommand.execute(testDir);
+
+      const calls = logSpy.mock.calls.flat().join('\n');
+      expect(calls).toContain('Copy these prompts to your AGENTS.md-compatible assistant');
+    });
   });
 
   describe('AI tool selection', () => {