feat: prioritize TOON format for agent parsing with JSON fallback

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -76,6 +76,7 @@
   "dependencies": {
     "@inquirer/core": "^10.3.2",
     "@inquirer/prompts": "^7.10.1",
+    "@toon-format/toon": "^4.1.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
     "cross-spawn": "7.0.6",

src/commands/change.ts

@@ -1,3 +1,5 @@
+import { printJson } from './shared-output.js';
+import type { OutputFormat } from '../core/format-output.js';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { JsonConverter } from '../core/converters/json-converter.js';
@@ -52,7 +54,7 @@ export class ChangeCommand {
    * - JSON mode: minimal object with deltas; --deltas-only returns same object with filtered deltas
    *   Note: --requirements-only is deprecated alias for --deltas-only
    */
-  async show(changeName?: string, options?: { json?: boolean; requirementsOnly?: boolean; deltasOnly?: boolean; noInteractive?: boolean; rootOutput?: RootOutput }): Promise<void> {
+  async show(changeName?: string, options?: { json?: boolean; requirementsOnly?: boolean; deltasOnly?: boolean; noInteractive?: boolean; rootOutput?: RootOutput; format?: OutputFormat }): Promise<void> {
     const changesPath = this.getChangesPath();
 
     if (!changeName) {
@@ -127,7 +129,7 @@ export class ChangeCommand {
         deltas,
         ...(options.rootOutput ? { root: options.rootOutput } : {}),
       };
-      console.log(JSON.stringify(output, null, 2));
+      printJson(output, options?.format ?? (options?.json ? 'json' : 'json-pretty'));
     } else {
       const content = await fs.readFile(proposalPath, 'utf-8');
       console.log(content);
@@ -139,7 +141,7 @@ export class ChangeCommand {
    * - Text default: IDs only; --long prints minimal details (title, counts)
    * - JSON: array of { id, title, deltaCount, taskStatus }, sorted by id
    */
-  async list(options?: { json?: boolean; long?: boolean }): Promise<void> {
+  async list(options?: { json?: boolean; long?: boolean; format?: OutputFormat }): Promise<void> {
     const changesPath = path.join(process.cwd(), 'openspec', 'changes');
 
     // Same directory-based resolution as `openspec list`, the command this
@@ -185,7 +187,7 @@ export class ChangeCommand {
       );
 
       const sorted = changeDetails.sort((a, b) => a.id.localeCompare(b.id));
-      console.log(JSON.stringify(sorted, null, 2));
+      printJson(sorted, options?.format ?? (options?.json ? 'json' : 'json-pretty'));
     } else {
       if (changes.length === 0) {
         console.log('No items found');
@@ -222,7 +224,7 @@ export class ChangeCommand {
     }
   }
 
-  async validate(changeName?: string, options?: { strict?: boolean; json?: boolean; noInteractive?: boolean }): Promise<void> {
+  async validate(changeName?: string, options?: { strict?: boolean; json?: boolean; noInteractive?: boolean; format?: OutputFormat }): Promise<void> {
     const changesPath = path.join(process.cwd(), 'openspec', 'changes');
 
     if (!changeName) {
@@ -263,7 +265,7 @@ export class ChangeCommand {
     });
 
     if (options?.json) {
-      console.log(JSON.stringify(report, null, 2));
+      printJson(report, options?.format ?? (options?.json ? 'json' : 'json-pretty'));
     } else {
       if (report.valid) {
         console.log(`Change "${changeName}" is valid`);

src/commands/config.ts

@@ -1,3 +1,5 @@
+import type { OutputFormat } from '../core/format-output.js';
+import { printJson } from './shared-output.js';
 import { Command } from 'commander';
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
@@ -233,11 +235,13 @@ export function registerConfigCommand(program: Command): void {
     .command('list')
     .description('Show all current settings')
     .option('--json', 'Output as JSON')
-    .action((options: { json?: boolean }) => {
+    .option('--json-pretty', 'Output as formatted JSON')
+    .option('--toon', 'Output in TOON format')
+    .action((options: { json?: boolean; format?: OutputFormat }) => {
       const config = getGlobalConfig();
 
       if (options.json) {
-        console.log(JSON.stringify(config, null, 2));
+        printJson(config, options?.format ?? (options?.json ? 'json' : 'json-pretty'));
       } else {
         // Read raw config to determine which values are explicit vs defaults
         const configPath = getGlobalConfigPath();
@@ -282,7 +286,7 @@ export function registerConfigCommand(program: Command): void {
       }
 
       if (typeof value === 'object' && value !== null) {
-        console.log(JSON.stringify(value));
+        printJson(value, 'json-pretty');
       } else {
         console.log(String(value));
       }
@@ -294,7 +298,7 @@ export function registerConfigCommand(program: Command): void {
     .description('Set a value (auto-coerce types)')
     .option('--string', 'Force value to be stored as string')
     .option('--allow-unknown', 'Allow setting unknown keys')
-    .action((key: string, value: string, options: { string?: boolean; allowUnknown?: boolean }) => {
+    .action((key: string, value: string, options: { string?: boolean; allowUnknown?: boolean; format?: OutputFormat }) => {
       const allowUnknown = Boolean(options.allowUnknown);
       const keyValidation = validateConfigKeyPath(key);
       // --allow-unknown relaxes the known-key check, but never the prototype-safety check.

src/commands/context.ts

@@ -25,6 +25,7 @@ import { StoreError } from '../core/store/errors.js';
 import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
 import { emitFailure, printJson } from './shared-output.js';
+import { normalizeOptions, type OutputFormat } from '../core/format-output.js';
 import { gatherRelationshipData } from './shared-gather.js';
 
 const FAILURE_PAYLOAD = { root: null, members: [] };
@@ -170,6 +171,8 @@ export function registerContextCommand(program: Command): void {
       new Option('--store-path <path>', 'Removed; register the store and use --store').hideHelp()
     )
     .option('--json', 'Output the agent brief as JSON')
+    .option('--json-pretty', 'Output as formatted JSON')
+    .option('--toon', 'Output in TOON format')
     .option('--code-workspace <path>', 'Also write a VS Code workspace file for the set')
     .option('--force', 'Overwrite an existing --code-workspace file')
     .action(
@@ -179,7 +182,9 @@ export function registerContextCommand(program: Command): void {
         json?: boolean;
         codeWorkspace?: string;
         force?: boolean;
+        format?: OutputFormat;
       }) => {
+        options = normalizeOptions(options) as any;
         try {
           const root = await resolveRootForCommand(
             { store: options.store, storePath: options.storePath },
@@ -197,15 +202,15 @@ export function registerContextCommand(program: Command): void {
             if (options.codeWorkspace) {
               writeCodeWorkspace(workingSet, options.codeWorkspace, options.force === true);
             }
-            printJson(workingSet);
+            printJson(workingSet, options.format);
           } else {
             printHumanWorkingSet(workingSet, declaredReferenceCount);
             if (options.codeWorkspace) {
               writeCodeWorkspace(workingSet, options.codeWorkspace, options.force === true);
             }
           }
         } catch (error) {
-          emitFailure(options.json, FAILURE_PAYLOAD, error, 'context_failed');
+          emitFailure(options.format ?? options.json, FAILURE_PAYLOAD, error, 'context_failed');
         }
       }
     );

src/commands/doctor.ts

@@ -26,6 +26,7 @@ import {
 import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
 import { emitFailure, printJson } from './shared-output.js';
+import { normalizeOptions, type OutputFormat } from '../core/format-output.js';
 import * as path from 'node:path';
 
 const FAILURE_PAYLOAD = { root: null, store: null, references: [] };
@@ -195,7 +196,10 @@ export function registerDoctorCommand(program: Command): void {
       new Option('--store-path <path>', 'Removed; register the store and use --store').hideHelp()
     )
     .option('--json', 'Output as JSON')
-    .action(async (options: { store?: string; storePath?: string; json?: boolean }) => {
+    .option('--json-pretty', 'Output as formatted JSON')
+    .option('--toon', 'Output in TOON format')
+    .action(async (options: { store?: string; storePath?: string; json?: boolean; format?: OutputFormat; jsonPretty?: boolean; toon?: boolean; }) => {
+      options = normalizeOptions(options) as any;
       try {
         const root = await resolveRootForCommand(
           { store: options.store, storePath: options.storePath },
@@ -213,7 +217,7 @@ export function registerDoctorCommand(program: Command): void {
         }
         printHumanHealth(health, declaredReferenceCount);
       } catch (error) {
-        emitFailure(options.json, FAILURE_PAYLOAD, error, 'doctor_failed');
+        emitFailure(options.format ?? options.json, FAILURE_PAYLOAD, error, 'doctor_failed');
       }
     });
 }