fix: suppress UI spinners and telemetry notices when --json is used

- Modified status, instructions, templates, and new-change commands to conditionally start the ora spinner only when not in JSON mode.
- Updated the global preAction hook to detect the --json flag and pass a silent flag to telemetry notices.
- Added --json support to 'new change' command for machine-readable result reporting.
- Added a new spec for machine-readable-output capability.

This ensures stdout/stderr pollution does not break JSON parsing for automated tools and AI agents.

Author: CosticaPuntaru

openspec/specs/machine-readable-output/spec.md

@@ -0,0 +1,34 @@
+# Capability: Machine Readable Output
+
+## Purpose
+
+Allow automated tools and AI agents to consume OpenSpec CLI output without stream corruption from UI elements.
+
+## Requirements
+
+### 1. Spinner Suppression
+The `ora` spinner must not be started if the `--json` flag is provided.
+
+#### Scenario: Status with JSON
+- **Given** an OpenSpec project with active changes
+- **When** running `openspec status --change my-change --json`
+- **Then** the `stdout` contains only the JSON object
+- **And** no spinner characters are present in the output stream
+
+### 2. Telemetry Notice Suppression
+The "Note: OpenSpec collects anonymous usage stats" message must not be printed if the `--json` flag is provided.
+
+#### Scenario: First run with JSON
+- **Given** a new environment where the telemetry notice hasn't been shown
+- **When** running `openspec list --json`
+- **Then** the telemetry notice is NOT printed to stdout
+- **And** only the JSON change list is printed
+
+### 3. Error Handling
+Errors should be printed to `stderr` and not pollute the `stdout` JSON stream.
+
+#### Scenario: Command failure with JSON
+- **Given** an invalid change name
+- **When** running `openspec status --change invalid --json`
+- **Then** the exit code is non-zero
+- **And** the error message is printed to `stderr`

src/cli/index.ts

@@ -74,8 +74,12 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     process.env.NO_COLOR = '1';
   }
 
+  // Check if action command is requesting JSON output
+  const actionOpts = actionCommand.opts();
+  const isJson = actionOpts.json === true;
+
   // Show first-run telemetry notice (if not seen)
-  await maybeShowTelemetryNotice();
+  await maybeShowTelemetryNotice({ silent: isJson });
 
   // Track command execution (use actionCommand to get the actual subcommand)
   const commandPath = getCommandPath(actionCommand);
@@ -497,6 +501,7 @@ newCmd
   .description('Create a new change directory')
   .option('--description <text>', 'Description to add to README.md')
   .option('--schema <name>', `Workflow schema to use (default: ${DEFAULT_SCHEMA})`)
+  .option('--json', 'Output as JSON (success/failure details)')
   .action(async (name: string, options: NewChangeOptions) => {
     try {
       await newChangeCommand(name, options);

src/commands/workflow/instructions.ts

@@ -45,7 +45,10 @@ export async function instructionsCommand(
   artifactId: string | undefined,
   options: InstructionsOptions
 ): Promise<void> {
-  const spinner = ora('Generating instructions...').start();
+  const spinner = ora('Generating instructions...');
+  if (!options.json) {
+    spinner.start();
+  }
 
   try {
     const projectRoot = process.cwd();
@@ -400,7 +403,10 @@ export async function generateApplyInstructions(
 }
 
 export async function applyInstructionsCommand(options: ApplyInstructionsOptions): Promise<void> {
-  const spinner = ora('Generating apply instructions...').start();
+  const spinner = ora('Generating apply instructions...');
+  if (!options.json) {
+    spinner.start();
+  }
 
   try {
     const projectRoot = process.cwd();

src/commands/workflow/new-change.ts

@@ -16,6 +16,7 @@ import { validateSchemaExists } from './shared.js';
 export interface NewChangeOptions {
   description?: string;
   schema?: string;
+  json?: boolean;
 }
 
 // -----------------------------------------------------------------------------
@@ -40,7 +41,10 @@ export async function newChangeCommand(name: string | undefined, options: NewCha
   }
 
   const schemaDisplay = options.schema ? ` with schema '${options.schema}'` : '';
-  const spinner = ora(`Creating change '${name}'${schemaDisplay}...`).start();
+  const spinner = ora(`Creating change '${name}'${schemaDisplay}...`);
+  if (!options.json) {
+    spinner.start();
+  }
 
   try {
     const result = await createChange(projectRoot, name, { schema: options.schema });
@@ -53,9 +57,20 @@ export async function newChangeCommand(name: string | undefined, options: NewCha
       await fs.writeFile(readmePath, `# ${name}\n\n${options.description}\n`, 'utf-8');
     }
 
-    spinner.succeed(`Created change '${name}' at openspec/changes/${name}/ (schema: ${result.schema})`);
+    if (options.json) {
+      console.log(JSON.stringify({ 
+        success: true, 
+        name, 
+        schema: result.schema, 
+        path: `openspec/changes/${name}/` 
+      }, null, 2));
+    } else {
+      spinner.succeed(`Created change '${name}' at openspec/changes/${name}/ (schema: ${result.schema})`);
+    }
   } catch (error) {
-    spinner.fail(`Failed to create change '${name}'`);
+    if (!options.json) {
+      spinner.fail(`Failed to create change '${name}'`);
+    }
     throw error;
   }
 }

src/commands/workflow/status.ts

@@ -33,7 +33,10 @@ export interface StatusOptions {
 // -----------------------------------------------------------------------------
 
 export async function statusCommand(options: StatusOptions): Promise<void> {
-  const spinner = ora('Loading change status...').start();
+  const spinner = ora('Loading change status...');
+  if (!options.json) {
+    spinner.start();
+  }
 
   try {
     const projectRoot = process.cwd();

src/commands/workflow/templates.ts

@@ -33,7 +33,10 @@ export interface TemplateInfo {
 // -----------------------------------------------------------------------------
 
 export async function templatesCommand(options: TemplatesOptions): Promise<void> {
-  const spinner = ora('Loading templates...').start();
+  const spinner = ora('Loading templates...');
+  if (!options.json) {
+    spinner.start();
+  }
 
   try {
     const projectRoot = process.cwd();

src/telemetry/index.ts

@@ -119,7 +119,7 @@ export async function trackCommand(commandName: string, version: string): Promis
 /**
  * Show first-run telemetry notice if not already seen.
  */
-export async function maybeShowTelemetryNotice(): Promise<void> {
+export async function maybeShowTelemetryNotice(options: { silent?: boolean } = {}): Promise<void> {
   if (!isTelemetryEnabled()) {
     return;
   }
@@ -130,10 +130,12 @@ export async function maybeShowTelemetryNotice(): Promise<void> {
       return;
     }
 
-    // Display notice
-    console.log(
-      'Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0'
-    );
+    if (!options.silent) {
+      // Display notice
+      console.log(
+        'Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0'
+      );
+    }
 
     // Mark as seen
     await updateTelemetryConfig({ noticeSeen: true });