mdkg 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to mdkg are documented here.
+
+This project follows a pragmatic changelog style inspired by Keep a Changelog. Versions use npm package versions.
+
+## 0.0.9 - 2026-05-12
+
+### Added
+
+- Added generic agent workflow file support for `SPEC.md`, `WORK.md`, `WORK_ORDER.md`, `RECEIPT.md`, `FEEDBACK.md`, `DISPUTE.md`, and `PROPOSAL.md`.
+- Added `mdkg new <agent-file-type> ... --id <portable-id>` for semantic ids such as `agent.image-worker` and `work.generate-image`.
+- Added validation support for `pricing_model: included`.
+- Added validation support for `proposal_kind: skill_update` targeting `skill.<slug>` refs.
+- Added generic skill extension output under `extensions`, with `ochatr_*` metadata mapped to `extensions.ochatr`.
+- Added a non-mutating npm `postinstall` hint that points users to `mdkg --help` and prints shell PATH guidance only when needed.
+- Added `docs/agent-runtime-0.0.9-handoff.md` to document the runtime migration path from implementation-specific naming to generic agent workflow naming.
+- Added `npm run smoke:matrix` to pack mdkg, install it into an isolated temporary npm prefix, and exercise the command matrix plus onboarding workflows from the packaged CLI.
+
+### Changed
+
+- Renamed the remaining public Omni file-type surface to generic agent workflow language.
+- Kept `mdkg init --omni` only as hidden migration guidance to `mdkg init --agent`.
+- Updated README and command matrix version references to `0.0.9`.
+- Removed stale prepublish wording and absolute local README links.
+- Removed `AGENT_PROMPT_SNIPPET.md` and distilled its startup rules into `AGENT_START.md`, making `AGENT_START.md` the single first-hop agent onboarding doc.
+- Treated ochatr.ai metadata as a vendor extension pattern rather than the base mdkg schema name.
+- Added npm `prepack` and `prepublishOnly` guards so release commands fail if the built CLI or init assets are missing.
+- Included `CHANGELOG.md` and `CONTRIBUTING.md` in the npm package because README links to them.
+
+### Fixed
+
+- Fixed strict validation gaps for room-runtime-style skill proposals and included pricing.
+- Fixed docs drift between published `0.0.8`, local source version, and the 0.0.9 release target.
+
+### Verification Status
+
+- Passed: `npm ci` with `NPM_CONFIG_CACHE=/private/tmp/mdkg-npm-cache`.
+- Passed: `npm run build`.
+- Passed: `npm run test` with 306 tests.
+- Passed: `npm run cli:check`.
+- Passed: `node dist/cli.js validate`.
+- Passed: `npm run smoke:consumer`.
+- Passed: `npm run smoke:matrix`.
+- Passed: `npm pack --dry-run --json`; tarball includes `dist/cli.js`, compiled command/core/graph/pack/template/util files, `dist/init/`, `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md`, `LICENSE`, package metadata, and `scripts/postinstall.js`.
+- Passed: `npm publish --dry-run`; `prepublishOnly` and `prepack` both completed successfully.
+- Confirmed before publish: npm registry latest remains `mdkg@0.0.8`.
+
+## 0.0.8
+
+- Published npm baseline before the 0.0.9 agent workflow release work.
+- Does not include agent workflow file types, mutation JSON receipt expansion, workspace enable/disable, or postinstall guidance.
+
+## 0.0.7 and earlier
+
+- Historical local and published release line for mdkg's initial CLI, graph, pack, skill, and agent-bootstrap work.

package/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to mdkg
+
+mdkg is a local-first CLI for deterministic project memory. Contributions should preserve that shape: file-based, inspectable in git, deterministic when possible, and useful to both humans and agents.
+
+## Prompt Requests Before Pull Requests
+
+The preferred contribution path is a Prompt Request: describe intent clearly enough that a maintainer, human contributor, or coding agent can turn it into a correct patch.
+
+This is inspired by the OpenClaw creator's framing of Prompt Requests over Pull Requests. The point is not to reject code; it is to make user intent first-class. Many useful contributors know the workflow problem better than the codebase. mdkg should capture that intent before debating implementation details.
+
+Use a Prompt Request when you want to propose:
+- a new command or flag
+- a docs or onboarding improvement
+- a validation rule
+- a workflow standard
+- a bug report with expected behavior
+- an agent-facing convention or template
+
+A good Prompt Request includes:
+- the goal in plain language
+- the current behavior or gap
+- the desired behavior
+- one or two example commands or markdown snippets
+- acceptance criteria
+- any constraints, such as backwards compatibility or public naming
+
+Code Pull Requests are still welcome when the implementation is clear, scoped, tested, and linked to the intent it serves.
+
+## Public Naming
+
+mdkg's public standard language is generic agent workflow language.
+
+Use:
+- `agent workflow files`
+- `agent workflow docs`
+- `mdkg init --agent`
+- `skill.<slug>` for skill proposal targets
+- `extensions.<vendor>` for vendor extension metadata
+
+Avoid new public API or docs language that makes mdkg look tied to one product or runtime. ochatr.ai is a pioneering adopter and may use `ochatr_*` extension metadata, but the base mdkg schema should stay vendor-neutral.
+
+## Development Loop
+
+Install dependencies when npm is available:
+
+```bash
+npm install
+```
+
+Core checks:
+
+```bash
+npm run build
+npm run test
+npm run cli:check
+node dist/cli.js validate
+```
+
+Release smoke checks:
+
+```bash
+npm run smoke:consumer
+npm pack --dry-run
+```
+
+If the local toolchain is incomplete, document exactly what was blocked and run the checks that are still possible, such as:
+
+```bash
+git diff --check
+node --check scripts/postinstall.js
+```
+
+## Working in the mdkg Repo
+
+This repo dogfoods mdkg. Before a substantial change:
+
+1. Read `AGENT_START.md`.
+2. Inspect relevant source and tests.
+3. Use `CLI_COMMAND_MATRIX.md` for the command surface.
+4. Keep source behavior and docs aligned.
+5. Add focused tests for new user-visible behavior.
+6. Run `mdkg validate` after building when possible.
+
+Do not commit generated index or pack outputs. Keep `.mdkg/index/` and `.mdkg/pack/` ignored.
+
+## Change Requirements
+
+Good patches are:
+- small enough to review
+- explicit about public interface changes
+- covered by focused tests
+- documented in `README.md`, `CLI_COMMAND_MATRIX.md`, or `CHANGELOG.md` when behavior changes
+- careful with existing dirty worktree changes
+
+For agent workflow files, update tests and fixtures when changing:
+- accepted frontmatter fields
+- validation rules
+- `mdkg new` scaffolding
+- pack/search/show output
+
+For release work, update:
+- `package.json`
+- `package-lock.json`
+- `README.md`
+- `CLI_COMMAND_MATRIX.md`
+- `CHANGELOG.md`
+- init assets under `assets/init/` when generated starter docs change
+
+## Pull Request Guidance
+
+When submitting code, include:
+- linked Prompt Request or short intent statement
+- summary of behavior changes
+- tests run and any blocked checks
+- docs updated or reason docs were not needed
+- compatibility notes for existing mdkg repos
+
+Do not include unrelated formatting churn or generated artifacts unless the change requires them.
+
+## Security and Secrets
+
+Do not put secrets in mdkg nodes, packs, events, fixtures, or test outputs. mdkg is project memory, not a secret store.
+
+Report security-sensitive issues privately until a safe disclosure path is established.

package/README.md

@@ -13,7 +13,7 @@ mdkg stays deliberately boring:
 - zero runtime dependencies
 - no sqlite, daemon, hosted index, or vector DB
 
-Current package version in source: `0.0.6`
+Current package version in source: `0.0.9`
 
 ## The product shape
 
@@ -31,8 +31,6 @@ If a repo needs repeatable procedures, author them as first-class skills under `
 
 ## Install
 
-Once published:
-
 ```bash
 npm i -g mdkg
 # or
@@ -65,6 +63,13 @@ Create a task:
 mdkg new task "bootstrap cli" --status todo --priority 1 --tags cli,build
 ```
 
+Create an agent workflow document with a semantic portable id:
+
+```bash
+mdkg new spec "image worker" --id agent.image-worker
+mdkg new work "generate image" --id work.generate-image
+```
+
 Inspect the current truth:
 
 ```bash
@@ -113,13 +118,13 @@ mdkg skill validate release-readiness
 ## LLM-readable onboarding artifacts
 
 The root docs below are the canonical fast-start set for humans and agents:
-- [`AGENT_START.md`](/Users/nicholasreames/Git/mdkg/AGENT_START.md)
-- [`llms.txt`](/Users/nicholasreames/Git/mdkg/llms.txt)
-- [`AGENT_PROMPT_SNIPPET.md`](/Users/nicholasreames/Git/mdkg/AGENT_PROMPT_SNIPPET.md)
-- [`PACK_EXAMPLES.md`](/Users/nicholasreames/Git/mdkg/PACK_EXAMPLES.md)
-- [`MANUAL_BEHAVIOR_AUDIT.md`](/Users/nicholasreames/Git/mdkg/MANUAL_BEHAVIOR_AUDIT.md)
-- [`CLI_COMMAND_MATRIX.md`](/Users/nicholasreames/Git/mdkg/CLI_COMMAND_MATRIX.md)
-- [`COVERAGE_HARDENING_MATRIX.md`](/Users/nicholasreames/Git/mdkg/COVERAGE_HARDENING_MATRIX.md)
+- [`AGENT_START.md`](AGENT_START.md)
+- [`llms.txt`](llms.txt)
+- [`PACK_EXAMPLES.md`](PACK_EXAMPLES.md)
+- [`CLI_COMMAND_MATRIX.md`](CLI_COMMAND_MATRIX.md)
+- [`COVERAGE_HARDENING_MATRIX.md`](COVERAGE_HARDENING_MATRIX.md)
+- [`CHANGELOG.md`](CHANGELOG.md)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
 
 ## Repository shape
 
@@ -199,6 +204,21 @@ This repo now dogfoods three internal skills:
 - `build-pack-and-execute-task`
 - `verify-close-and-checkpoint`
 
+Optional skill metadata with prefixes such as `ochatr_*` is treated as vendor extension data. Structured skill output exposes it under `extensions.ochatr` while keeping the top-level `ochatr` field as a 0.0.9 compatibility alias. ochatr.ai is a pioneering adopter of this extension pattern, not the name of the base mdkg standard.
+
+## Agent workflow files
+
+mdkg recognizes a small set of canonical agent workflow documents:
+- `SPEC.md` for agent, package, or runtime specifications
+- `WORK.md` for reusable work contracts
+- `WORK_ORDER.md` for concrete requests against work contracts
+- `RECEIPT.md` for completed work output and artifacts
+- `FEEDBACK.md`, `DISPUTE.md`, and `PROPOSAL.md` for review loops
+
+Use `mdkg new spec|work|work_order|receipt|feedback|dispute|proposal "<title>"` to scaffold them. `--id <portable-id>` is available for these types when semantic ids such as `agent.image-worker` or `work.generate-image` are preferred.
+
+Relational templates contain editable placeholder refs. `spec` and `work` scaffold as validation-clean standalone docs; `work_order`, `receipt`, `feedback`, `dispute`, and `proposal` need real refs before strict `mdkg validate` passes.
+
 ## Current direction
 
 This release includes:
@@ -211,6 +231,7 @@ This release includes:
 - latest-checkpoint resolver + index hint
 - events JSONL validation
 - XML / TOON / Markdown output for node and skill list/search/show
+- agent workflow file types and semantic `mdkg new --id` support
 - product-specific skill mirrors for Codex/OpenAI and Claude
 - shared `AGENT_START.md` startup guidance
 
@@ -241,6 +262,8 @@ Use these defaults:
 
 ## Contributing
 
+Start with [`CONTRIBUTING.md`](CONTRIBUTING.md). mdkg prefers Prompt Requests before Pull Requests: contributors can submit intent, workflows, prompts, and acceptance criteria without needing to write code first.
+
 This repo dogfoods mdkg itself. The behavior source of truth is the combination of:
 - source under `src/`
 - tests under `tests/`

package/dist/cli.js

@@ -63,7 +63,7 @@ function printUsage(log) {
     log("  guide       Show the mdkg guide");
     log("  format      Normalize frontmatter");
     log("  doctor      Run install and workspace diagnostics");
-    log("  workspace   Manage workspaces (ls/add/rm)");
+    log("  workspace   Manage workspaces (ls/add/rm/enable/disable)");
     log("\nQuickstart:");
     log("  mdkg init --llm");
     log('  mdkg new task "..." --status todo --priority 1');
@@ -97,10 +97,14 @@ function printInitHelp(log) {
 }
 function printNewHelp(log) {
     log("Usage:");
-    log('  mdkg new <type> "<title>" [options]');
+    log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
     log("  rule prd edd dec prop epic feat task bug checkpoint test");
+    log("\nAgent workflow file types:");
+    log("  spec work work_order receipt feedback dispute proposal");
+    log("  Use --id <portable-id> with these types for semantic ids like agent.image-worker.");
     log("\nOptions:");
+    log("  --id <portable-id>         Explicit id for agent workflow file types");
     log("  --ws <alias>               Workspace alias (default root)");
     log("  --status <status>          Work item or decision status");
     log("  --priority <0..9>          Work item priority");
@@ -113,6 +117,8 @@ function printNewHelp(log) {
     log("  --parent --prev --next --relates --blocked-by --blocks");
     log("  --links --artifacts --refs --aliases --owners --cases --supersedes");
     log("  --owners <owner,owner,...> Owners");
+    log("\nNotes:");
+    log("  spec/work scaffold as validation-clean docs; relational workflow docs need real refs.");
     printGlobalOptions(log);
 }
 function printGuideHelp(log) {
@@ -122,9 +128,11 @@ function printGuideHelp(log) {
 }
 function printWorkspaceHelp(log) {
     log("Usage:");
-    log("  mdkg workspace ls");
-    log("  mdkg workspace add <alias> <path> [--mdkg-dir <dir>]");
-    log("  mdkg workspace rm <alias>");
+    log("  mdkg workspace ls [--json]");
+    log("  mdkg workspace add <alias> <path> [--mdkg-dir <dir>] [--json]");
+    log("  mdkg workspace rm <alias> [--json]");
+    log("  mdkg workspace enable <alias> [--json]");
+    log("  mdkg workspace disable <alias> [--json]");
     printGlobalOptions(log);
 }
 function printIndexHelp(log) {
@@ -199,7 +207,7 @@ function printSkillHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "new":
             log("Usage:");
-            log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
+            log('  mdkg skill new <slug> "<name>" --description "<description>" [options] [--json]');
             log("\nOptions:");
             log("  --tags <tag,tag,...>         Optional skill tags");
             log("  --authors <name,name,...>    Optional authors list");
@@ -232,24 +240,24 @@ function printSkillHelp(log, subcommand) {
             return;
         case "validate":
             log("Usage:");
-            log("  mdkg skill validate [<slug>]");
+            log("  mdkg skill validate [<slug>] [--json]");
             printGlobalOptions(log);
             return;
         case "sync":
             log("Usage:");
-            log("  mdkg skill sync [--force]");
+            log("  mdkg skill sync [--force] [--json]");
             log("\nWhen to use:");
             log("  Rebuild .agents/skills and .claude/skills from canonical .mdkg/skills.");
             printGlobalOptions(log);
             return;
         default:
             log("Usage:");
-            log('  mdkg skill new <slug> "<name>" --description "<description>" [options]');
+            log('  mdkg skill new <slug> "<name>" --description "<description>" [options] [--json]');
             log("  mdkg skill list [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
             log("  mdkg skill show <slug> [--meta] [--json|--xml|--toon|--md]");
             log('  mdkg skill search "<query>" [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]');
-            log("  mdkg skill validate [<slug>]");
-            log("  mdkg skill sync [--force]");
+            log("  mdkg skill validate [<slug>] [--json]");
+            log("  mdkg skill sync [--force] [--json]");
             log("\nNotes:");
             log("  Skills are first-class under `mdkg skill ...`.");
             log("  Use stage tags like `stage:plan`, `stage:execute`, and `stage:review` with --tags.");
@@ -260,7 +268,7 @@ function printTaskHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "start":
             log("Usage:");
-            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
+            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Move a task, bug, or test into progress as a structured state change.");
             log("  If `events.jsonl` is missing, mdkg prints a short reminder about `mdkg event enable`.");
@@ -271,7 +279,7 @@ function printTaskHelp(log, subcommand) {
             log("  mdkg task update <id-or-qid> [--ws <alias>] [--status <status>] [--priority <n>]");
             log("                   [--add-artifacts <a,...>] [--add-links <l,...>] [--add-refs <id,...>]");
             log("                   [--add-skills <slug,...>] [--add-tags <tag,...>] [--add-blocked-by <id,...>]");
-            log('                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"]');
+            log('                   [--clear-blocked-by] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Update structured task metadata and evidence while keeping body and narrative edits in markdown.");
             printGlobalOptions(log);
@@ -279,7 +287,7 @@ function printTaskHelp(log, subcommand) {
         case "done":
             log("Usage:");
             log('  mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]');
-            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"]');
+            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Mark a task-like node done, optionally create a checkpoint, and emit a completion event when enabled.");
             log("  Use `--checkpoint` for milestone compression, not every routine task completion.");
@@ -287,9 +295,9 @@ function printTaskHelp(log, subcommand) {
             return;
         default:
             log("Usage:");
-            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"]');
-            log("  mdkg task update <id-or-qid> [options]");
-            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options]');
+            log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
+            log("  mdkg task update <id-or-qid> [options] [--json]");
+            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
             log("\nNotes:");
             log("  `mdkg task ...` only supports task, bug, and test nodes in this wave.");
             log("  Feat and epic closeout remain checkpoint-first guidance plus manual parent updates.");
@@ -300,7 +308,7 @@ function printEventHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "enable":
             log("Usage:");
-            log("  mdkg event enable [--ws <alias>]");
+            log("  mdkg event enable [--ws <alias>] [--json]");
             log("\nWhen to use:");
             log("  Create or ensure the append-only JSONL event log for a workspace.");
             printGlobalOptions(log);
@@ -308,7 +316,7 @@ function printEventHelp(log, subcommand) {
         case "append":
             log("Usage:");
             log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...>");
-            log('                    [--ws <alias>] [--artifacts <a,...>] [--notes "<text>"] [--run-id <id>]');
+            log('                    [--ws <alias>] [--artifacts <a,...>] [--notes "<text>"] [--run-id <id>] [--json]');
             log("                    [--agent <name>] [--skill <slug>] [--tool <id>]");
             log("\nWhen to use:");
             log("  Append explicit provenance events from an orchestrator or manual workflow.");
@@ -316,8 +324,8 @@ function printEventHelp(log, subcommand) {
             return;
         default:
             log("Usage:");
-            log("  mdkg event enable [--ws <alias>]");
-            log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options]");
+            log("  mdkg event enable [--ws <alias>] [--json]");
+            log("  mdkg event append --kind <kind> --status <ok|error|retry|skipped> --refs <id,...> [options] [--json]");
             printGlobalOptions(log);
     }
 }
@@ -328,13 +336,13 @@ function printNextHelp(log) {
 }
 function printCheckpointHelp(log) {
     log("Usage:");
-    log("  mdkg checkpoint new <title> [--ws <alias>]");
+    log("  mdkg checkpoint new <title> [--ws <alias>] [--json]");
     log('        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]');
     printGlobalOptions(log);
 }
 function printValidateHelp(log) {
     log("Usage:");
-    log("  mdkg validate [--out <path>] [--quiet]");
+    log("  mdkg validate [--out <path>] [--quiet] [--json]");
     printGlobalOptions(log);
 }
 function printFormatHelp(log) {
@@ -573,7 +581,8 @@ function runWorkspaceSubcommand(parsed, root) {
             if (parsed.positionals.length > 2) {
                 throw new errors_1.UsageError("workspace ls takes no arguments");
             }
-            (0, workspace_1.runWorkspaceListCommand)({ root });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceListCommand)({ root, json });
             return 0;
         }
         case "add": {
@@ -583,7 +592,8 @@ function runWorkspaceSubcommand(parsed, root) {
                 throw new errors_1.UsageError("workspace add requires <alias> <path>");
             }
             const mdkgDir = requireFlagValue("--mdkg-dir", parsed.flags["--mdkg-dir"]);
-            (0, workspace_1.runWorkspaceAddCommand)({ root, alias, workspacePath, mdkgDir });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceAddCommand)({ root, alias, workspacePath, mdkgDir, json });
             return 0;
         }
         case "rm": {
@@ -591,11 +601,30 @@ function runWorkspaceSubcommand(parsed, root) {
             if (!alias || parsed.positionals.length > 3) {
                 throw new errors_1.UsageError("workspace rm requires <alias>");
             }
-            (0, workspace_1.runWorkspaceRemoveCommand)({ root, alias });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceRemoveCommand)({ root, alias, json });
+            return 0;
+        }
+        case "enable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("workspace enable requires <alias>");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceEnableCommand)({ root, alias, json });
+            return 0;
+        }
+        case "disable": {
+            const alias = parsed.positionals[2];
+            if (!alias || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("workspace disable requires <alias>");
+            }
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, workspace_1.runWorkspaceDisableCommand)({ root, alias, json });
             return 0;
         }
         default:
-            throw new errors_1.UsageError("workspace requires ls/add/rm");
+            throw new errors_1.UsageError("workspace requires ls/add/rm/enable/disable");
     }
 }
 function runSkillSubcommand(parsed, root) {
@@ -620,6 +649,7 @@ function runSkillSubcommand(parsed, root) {
             const withScripts = parseBooleanFlag("--with-scripts", parsed.flags["--with-scripts"]);
             const force = parseBooleanFlag("--force", parsed.flags["--force"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, skill_1.runSkillNewCommand)({
                 root,
                 slug,
@@ -631,6 +661,7 @@ function runSkillSubcommand(parsed, root) {
                 withScripts,
                 force,
                 runId,
+                json,
             });
             return 0;
         }
@@ -698,7 +729,8 @@ function runSkillSubcommand(parsed, root) {
                 throw new errors_1.UsageError("skill validate accepts at most one slug");
             }
             const slug = parsed.positionals[2];
-            (0, skill_1.runSkillValidateCommand)({ root, slug });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, skill_1.runSkillValidateCommand)({ root, slug, json });
             return 0;
         }
         case "sync": {
@@ -706,7 +738,8 @@ function runSkillSubcommand(parsed, root) {
                 throw new errors_1.UsageError("skill sync does not accept positional arguments");
             }
             const force = parseBooleanFlag("--force", parsed.flags["--force"]);
-            (0, skill_1.runSkillSyncCommand)({ root, force });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, skill_1.runSkillSyncCommand)({ root, force, json });
             return 0;
         }
         default:
@@ -724,7 +757,8 @@ function runTaskSubcommand(parsed, root) {
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
-            (0, task_1.runTaskStartCommand)({ root, id, ws, runId, note });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, task_1.runTaskStartCommand)({ root, id, ws, runId, note, json });
             return 0;
         }
         case "update": {
@@ -744,6 +778,7 @@ function runTaskSubcommand(parsed, root) {
             const clearBlockedBy = parseBooleanFlag("--clear-blocked-by", parsed.flags["--clear-blocked-by"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, task_1.runTaskUpdateCommand)({
                 root,
                 id,
@@ -759,6 +794,7 @@ function runTaskSubcommand(parsed, root) {
                 clearBlockedBy,
                 runId,
                 note,
+                json,
             });
             return 0;
         }
@@ -774,6 +810,7 @@ function runTaskSubcommand(parsed, root) {
             const checkpoint = requireFlagValue("--checkpoint", parsed.flags["--checkpoint"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, task_1.runTaskDoneCommand)({
                 root,
                 id,
@@ -784,6 +821,7 @@ function runTaskSubcommand(parsed, root) {
                 checkpoint,
                 runId,
                 note,
+                json,
             });
             return 0;
         }
@@ -799,7 +837,8 @@ function runEventSubcommand(parsed, root) {
                 throw new errors_1.UsageError("event enable does not accept positional arguments");
             }
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
-            (0, event_1.runEventEnableCommand)({ root, ws });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, event_1.runEventEnableCommand)({ root, ws, json });
             return 0;
         }
         case "append": {
@@ -819,6 +858,7 @@ function runEventSubcommand(parsed, root) {
             const agent = requireFlagValue("--agent", parsed.flags["--agent"]);
             const skill = requireFlagValue("--skill", parsed.flags["--skill"]);
             const tool = requireFlagValue("--tool", parsed.flags["--tool"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, event_1.runEventAppendCommand)({
                 root,
                 ws,
@@ -831,6 +871,7 @@ function runEventSubcommand(parsed, root) {
                 agent,
                 skill,
                 tool,
+                json,
             });
             return 0;
         }
@@ -882,6 +923,7 @@ function runCommand(parsed, root, runtime) {
             if (!type || !title) {
                 throw new errors_1.UsageError("new requires a type and title");
             }
+            const id = requireFlagValue("--id", parsed.flags["--id"]);
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
@@ -905,10 +947,12 @@ function runCommand(parsed, root, runtime) {
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, new_1.runNewCommand)({
                 root,
                 type,
                 title,
+                id,
                 ws,
                 status,
                 priority,
@@ -932,6 +976,7 @@ function runCommand(parsed, root, runtime) {
                 noCache,
                 noReindex,
                 runId,
+                json,
             });
             return 0;
         }
@@ -1117,6 +1162,7 @@ function runCommand(parsed, root, runtime) {
             const template = requireFlagValue("--template", parsed.flags["--template"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
             (0, checkpoint_1.runCheckpointNewCommand)({
                 root,
                 title,
@@ -1128,6 +1174,7 @@ function runCommand(parsed, root, runtime) {
                 template,
                 runId,
                 note,
+                json,
             });
             return 0;
         }
@@ -1137,7 +1184,8 @@ function runCommand(parsed, root, runtime) {
             }
             const out = requireFlagValue("--out", parsed.flags["--out"]);
             const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
-            (0, validate_1.runValidateCommand)({ root, out, quiet });
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, validate_1.runValidateCommand)({ root, out, quiet, json });
             return 0;
         }
         case "format":