@open-agent-toolkit/cli 0.0.55 → 0.0.56

package/assets/docs/contributing/skills.md

@@ -59,6 +59,47 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Use `create-agnostic-skill` when you want a reusable workflow skill that is not OAT-specific.
 - Use existing lifecycle skills as examples for progress banners, prerequisites, and artifact updates.
 
+## Reading project state
+
+Skills that need fields from the active project's `state.md` (e.g. `phase`, `phaseStatus`, `workflowMode`, `docsUpdated`, `lastCommit`) MUST query the CLI instead of hand-parsing YAML with `grep`/`awk`.
+
+For one field, use `--field`:
+
+```bash
+WORKFLOW_MODE=$(oat project status --field project.workflowMode 2>/dev/null || echo null)
+```
+
+If the skill is reading a resolved project path instead of the active project pointer, add `--project-path`:
+
+```bash
+WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field project.workflowMode 2>/dev/null || echo null)
+```
+
+For multiple fields, use `--shell` so the CLI reads project state once and emits shell-safe assignments:
+
+```bash
+eval "$(oat project status --shell \
+  PHASE=project.phase \
+  PHASE_STATUS=project.phaseStatus \
+  WORKFLOW_MODE=project.workflowMode 2>/dev/null)"
+```
+
+Skill snippets assume `oat` is available on `PATH`. Environments without a global install, including CI or cloud runners, can provide an `oat` shim backed by `npx`:
+
+```bash
+mkdir -p .oat/bin
+cat > .oat/bin/oat <<'EOF'
+#!/usr/bin/env bash
+exec npx @open-agent-toolkit/cli "$@"
+EOF
+chmod +x .oat/bin/oat
+export PATH="$PWD/.oat/bin:$PATH"
+```
+
+Create the shim once per checkout or CI job instead of putting `command -v oat` fallback branches in every skill. The same snippet also supports setups where `oat` is intentionally provided on `PATH` by `npx`.
+
+The JSON output is a stable contract: the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`, so removing or renaming any of those keys is a real test failure rather than a silent runtime break. See [CLI Reference](../reference/cli-reference.md) for the full locked field set.
+
 ## Reference artifacts
 
 - `.agents/skills/*/SKILL.md`

package/assets/docs/reference/cli-reference.md

@@ -37,7 +37,10 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 Notable inspection commands introduced in the current CLI surface:
 
 - `oat config dump --json` - merged config with source attribution
-- `oat project status --json` - full parsed state for the active tracked project
+- `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and will fail the contract test.
+- `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
+- `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
+- `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.55",
-  "docs-config": "0.0.55",
-  "docs-theme": "0.0.55",
-  "docs-transforms": "0.0.55"
+  "cli": "0.0.56",
+  "docs-config": "0.0.56",
+  "docs-theme": "0.0.56",
+  "docs-transforms": "0.0.56"
 }

package/assets/skills/oat-project-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.3
+version: 1.4.4
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -183,8 +183,7 @@ fi
 #### 3.3: Documentation Sync Status
 
 ```bash
-STATE_FILE="${PROJECT_PATH}/state.md"
-DOCS_UPDATED=$(grep "^oat_docs_updated:" "$STATE_FILE" 2>/dev/null | awk '{print $2}' || true)
+DOCS_UPDATED=$(oat project status --field project.docsUpdated 2>/dev/null || echo null)
 
 # Read policy from config (default: false = soft suggestion)
 REQUIRE_DOCS=$(oat config get documentation.requireForProjectCompletion 2>/dev/null || echo "false")

package/assets/skills/oat-project-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.1
+version: 1.3.2
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
 disable-model-invocation: true
 user-invocable: true
@@ -105,8 +105,7 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 ### Step 1: Determine Workflow Mode and Route
 
 ```bash
-WORKFLOW_MODE=$(grep "^oat_workflow_mode:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
-WORKFLOW_MODE="${WORKFLOW_MODE:-spec-driven}"
+WORKFLOW_MODE=$(oat project status --field project.workflowMode 2>/dev/null || echo null)
 ```
 
 **Mode: `quick`** — **STOP.** Print:

package/assets/skills/oat-project-pr-final/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-pr-final
-version: 1.3.3
+version: 1.3.4
 description: Use when an active OAT project has completed all phases and is ready for final merge to main. Generates the final OAT lifecycle PR description from artifacts and review status, then creates the PR automatically.
 disable-model-invocation: true
 user-invocable: true
@@ -134,8 +134,7 @@ Rules:
 Resolve workflow mode from `state.md` (default `spec-driven`):
 
 ```bash
-WORKFLOW_MODE=$(grep "^oat_workflow_mode:" "$PROJECT_PATH/state.md" 2>/dev/null | head -1 | awk '{print $2}')
-WORKFLOW_MODE=${WORKFLOW_MODE:-spec-driven}
+WORKFLOW_MODE=$(oat project status --field project.workflowMode 2>/dev/null || echo null)
 ```
 
 ```bash

package/assets/skills/oat-project-pr-progress/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-pr-progress
-version: 1.2.0
+version: 1.2.1
 description: Use when an active OAT project needs a mid-project PR for a completed phase (pNN). Generates a phase-scoped progress PR description from OAT artifacts and commit history, with optional PR creation.
 disable-model-invocation: true
 user-invocable: true
@@ -159,8 +159,7 @@ If scope is `range`/`base_sha`, set:
 Resolve workflow mode from `state.md` (default `spec-driven`):
 
 ```bash
-WORKFLOW_MODE=$(grep "^oat_workflow_mode:" "$PROJECT_PATH/state.md" 2>/dev/null | head -1 | awk '{print $2}')
-WORKFLOW_MODE=${WORKFLOW_MODE:-spec-driven}
+WORKFLOW_MODE=$(oat project status --field project.workflowMode 2>/dev/null || echo null)
 ```
 
 Read (as available):

package/assets/skills/oat-project-progress/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-progress
-version: 1.2.2
+version: 1.2.3
 description: Use when resuming work, checking status, or unsure which OAT skill to run next. Evaluates project progress and routes to the appropriate next step.
 disable-model-invocation: true
 user-invocable: true
@@ -202,8 +202,8 @@ PLAN_TASKS=$(grep -cE '^### Task p[0-9]+-t[0-9]+:' "$ACTIVE_PROJECT_PATH/plan.md
 IMPL_COMPLETED=$(grep -cE '^\*\*Status:\*\* completed' "$ACTIVE_PROJECT_PATH/implementation.md" 2>/dev/null || echo 0)
 
 # Check for commits since last tracked SHA
-LAST_SHA=$(grep "^oat_last_commit:" "$ACTIVE_PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
-if [ -n "$LAST_SHA" ]; then
+LAST_SHA=$(oat project status --project-path "$ACTIVE_PROJECT_PATH" --field project.lastCommit 2>/dev/null || echo null)
+if [ -n "$LAST_SHA" ] && [ "$LAST_SHA" != "null" ]; then
   UNTRACKED_COMMITS=$(git rev-list --count "$LAST_SHA"..HEAD 2>/dev/null || echo 0)
 else
   UNTRACKED_COMMITS=0

package/assets/skills/oat-project-reconcile/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-reconcile
-version: 1.0.0
+version: 1.0.1
 description: Use when human-implemented commits need to be mapped back to planned tasks. Reconciles implementation.md and state.md after manual work outside the OAT workflow.
 disable-model-invocation: true
 user-invocable: true
@@ -104,9 +104,13 @@ Verify the project is ready for reconciliation:
 
 2. **Check project phase:**
 
+   The shell snippet below is indented so it remains inside this numbered list;
+   the leading whitespace is shell-safe when copied.
+
    ```bash
-   PHASE=$(grep "^oat_phase:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
-   PHASE_STATUS=$(grep "^oat_phase_status:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
+   eval "$(oat project status --shell \
+     PHASE=project.phase \
+     PHASE_STATUS=project.phaseStatus 2>/dev/null)"
    ```
 
    - If `PHASE` is `implement`: proceed

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.3.1
+version: 1.3.2
 description: Use when completed work in an active OAT project needs a quality gate before merge. Performs a lifecycle-scoped review after a task, phase, or full implementation, unlike oat-review-provide.
 disable-model-invocation: true
 user-invocable: true
@@ -122,9 +122,10 @@ If validation passes, derive `{project-name}` as basename of `PROJECT_PATH`.
 Read `state.md` frontmatter to propose the most likely review type and scope:
 
 ```bash
-PHASE=$(grep "^oat_phase:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
-PHASE_STATUS=$(grep "^oat_phase_status:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
-WORKFLOW_MODE=$(grep "^oat_workflow_mode:" "$PROJECT_PATH/state.md" 2>/dev/null | awk '{print $2}')
+eval "$(oat project status --shell \
+  PHASE=project.phase \
+  PHASE_STATUS=project.phaseStatus \
+  WORKFLOW_MODE=project.workflowMode 2>/dev/null)"
 ```
 
 Inference rules (first match wins):
@@ -244,11 +245,12 @@ If the review is intentionally inline-only and the user explicitly wants to insp
 
 ### Step 2: Validate Artifacts Exist (Mode-Aware)
 
-Resolve workflow mode from state (default `spec-driven`):
+Resolve workflow mode from the resolved project state path:
 
 ```bash
-WORKFLOW_MODE=$(grep "^oat_workflow_mode:" "$PROJECT_PATH/state.md" 2>/dev/null | head -1 | awk '{print $2}')
-WORKFLOW_MODE=${WORKFLOW_MODE:-spec-driven}
+# Step 1.5 may retarget PROJECT_PATH into another worktree, so read from the
+# resolved project path instead of the active-project pointer.
+WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field project.workflowMode 2>/dev/null || echo null)
 ```
 
 **Required for code review (by mode):**

package/dist/commands/project/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/project/status.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACjE;AAmFD,wBAAgB,0BAA0B,CACxC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAcT"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/project/status.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACjE;AAgND,wBAAgB,0BAA0B,CACxC,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CA0BT"}

package/dist/commands/project/status.js

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { buildCommandContext, } from '../../app/command-context.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { resolveActiveProject, } from '../../config/oat-config.js';
@@ -11,6 +11,9 @@ const DEFAULT_DEPENDENCIES = {
     resolveActiveProject,
     getProjectState,
 };
+function resolveTargetProjectPath(repoRoot, projectPath) {
+    return isAbsolute(projectPath) ? projectPath : join(repoRoot, projectPath);
+}
 function formatProjectStatusLines(project) {
     return [
         `Project: ${project.name}`,
@@ -22,9 +25,61 @@ function formatProjectStatusLines(project) {
         `Reason: ${project.recommendation.reason}`,
     ];
 }
-async function runProjectStatus(context, dependencies) {
+function readDotPath(payload, path) {
+    const parts = path.split('.').filter(Boolean);
+    let cursor = payload;
+    for (const part of parts) {
+        if (cursor === null || typeof cursor !== 'object') {
+            return undefined;
+        }
+        if (!Object.prototype.hasOwnProperty.call(cursor, part)) {
+            return undefined;
+        }
+        cursor = cursor[part];
+    }
+    return cursor;
+}
+function formatRawValue(value) {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function shellQuote(value) {
+    return `'${value.split("'").join("'\\''")}'`;
+}
+const SHELL_ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.+)$/;
+function formatShellAssignment(assignment, payload) {
+    const match = SHELL_ASSIGNMENT_RE.exec(assignment);
+    if (!match) {
+        return null;
+    }
+    const name = match[1];
+    const path = match[2];
+    if (!name || !path) {
+        return null;
+    }
+    const value = formatRawValue(readDotPath(payload, path));
+    return `${name}=${shellQuote(value)}`;
+}
+async function runProjectStatus(context, dependencies, options) {
     try {
+        if (options.projectPath && isAbsolute(options.projectPath)) {
+            const project = await dependencies.getProjectState(options.projectPath);
+            writeProjectStatusOutput(context, options, { status: 'ok', project });
+            return;
+        }
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+        if (options.projectPath) {
+            const project = await dependencies.getProjectState(resolveTargetProjectPath(repoRoot, options.projectPath));
+            writeProjectStatusOutput(context, options, { status: 'ok', project });
+            return;
+        }
         const activeProject = await dependencies.resolveActiveProject(repoRoot);
         if (activeProject.status === 'unset') {
             const message = 'No active project set (.oat/config.local.json has no activeProject).';
@@ -56,15 +111,7 @@ async function runProjectStatus(context, dependencies) {
             return;
         }
         const project = await dependencies.getProjectState(join(repoRoot, activeProject.path));
-        if (context.json) {
-            context.logger.json({ status: 'ok', project });
-        }
-        else {
-            for (const line of formatProjectStatusLines(project)) {
-                context.logger.info(line);
-            }
-        }
-        process.exitCode = 0;
+        writeProjectStatusOutput(context, options, { status: 'ok', project });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -77,6 +124,44 @@ async function runProjectStatus(context, dependencies) {
         process.exitCode = 1;
     }
 }
+function writeProjectStatusOutput(context, options, payload) {
+    if (options.field && options.shell?.length) {
+        context.logger.error('`--field` and `--shell` are mutually exclusive; pass only one.');
+        process.exitCode = 1;
+        return;
+    }
+    if (options.field) {
+        context.logger.info(formatRawValue(readDotPath(payload, options.field)));
+        process.exitCode = 0;
+        return;
+    }
+    if (options.shell?.length) {
+        const lines = [];
+        for (const assignment of options.shell) {
+            const line = formatShellAssignment(assignment, payload);
+            if (!line) {
+                context.logger.error(`Invalid shell assignment "${assignment}". Expected NAME=path with a shell-safe variable name.`);
+                process.exitCode = 1;
+                return;
+            }
+            lines.push(line);
+        }
+        for (const line of lines) {
+            context.logger.info(line);
+        }
+        process.exitCode = 0;
+        return;
+    }
+    if (context.json) {
+        context.logger.json(payload);
+    }
+    else {
+        for (const line of formatProjectStatusLines(payload.project)) {
+            context.logger.info(line);
+        }
+    }
+    process.exitCode = 0;
+}
 export function createProjectStatusCommand(overrides = {}) {
     const dependencies = {
         ...DEFAULT_DEPENDENCIES,
@@ -84,8 +169,11 @@ export function createProjectStatusCommand(overrides = {}) {
     };
     return new Command('status')
         .description('Show the current OAT project state')
-        .action(async (_options, command) => {
+        .option('--field <path>', 'Print a single field from the project status payload by dot path')
+        .option('--project-path <path>', 'Read status from an explicit project path instead of the active project')
+        .option('--shell <assignment...>', 'Print shell-safe NAME=value assignments for one or more NAME=path pairs')
+        .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
-        await runProjectStatus(context, dependencies);
+        await runProjectStatus(context, dependencies, options);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.0.55"
+    "@open-agent-toolkit/control-plane": "0.0.56"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",