Add agent workbench package

Author: CharGrnmn

.github/workflows/agent-workbench-release.yml

@@ -0,0 +1,48 @@
+name: agent-workbench Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/agent-workbench
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'agent-workbench-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#agent-workbench-v}"
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Verify required CI passed for release commit
+        uses: ./.github/actions/verify-release-gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify package.json version matches release tag
+        run: npm run release:check-source -- "$VERSION"
+
+      - name: Install (workspace root)
+        run: npm ci
+        working-directory: .
+
+      - name: Publish to npm (with provenance)
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/ci.yml

@@ -101,6 +101,9 @@ jobs:
           - workspace: "@agent-pattern-labs/iso-guard"
             node: "20.6.0"
             extra: ""
+          - workspace: "@agent-pattern-labs/agent-workbench"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@agent-pattern-labs/agentmd"
             node: "22.0.0"
             extra: ""

README.md

@@ -35,7 +35,7 @@ Today, agent workflow reliability is fragmented on three axes:
   "what already happened." Those invariants belong in deterministic local packages,
   not in repeatedly re-tokenized instructions.
 
-Twenty-five packages solve that in one pipeline with runtime control and a
+Twenty-six packages solve that in one pipeline with runtime control and a
 feedback loop:
 
 - **Four build-time tools** turn your authored source into every harness's file layout:
@@ -87,6 +87,11 @@ feedback loop:
   [`@agent-pattern-labs/iso-eval`](./packages/iso-eval) scores *did the agent complete the task?* and
   [`@agent-pattern-labs/iso-trace`](./packages/iso-trace) parses production transcripts to show *what the agent actually did*,
   while [`@agent-pattern-labs/iso-guard`](./packages/iso-guard) enforces operational policies against those event streams.
+- **One local operator workbench** helps you see the harness fleet you already
+  have on disk: [`@agent-pattern-labs/agent-workbench`](./packages/agent-workbench)
+  discovers ISO, JobForge, leads-rig, and ProfileScribe harness projects and
+  summarizes scripts, MCP config, generated harness files, ledgers, caches, and
+  traces.
 
 ```
                 authoring                          build                               output                        feedback
@@ -263,7 +268,7 @@ of the prompt:
 - `iso-guard` audits the normalized event streams from real runs so runtime
   policy stays verifiable after deploy.
 
-## Packages (25 Total)
+## Packages (26 Total)
 
 1. **[`packages/iso`](./packages/iso)** — [`@agent-pattern-labs/iso`](https://www.npmjs.com/package/@agent-pattern-labs/iso) · *recommended entry point*
    The wrapper CLI for the whole flow. If `agent.md` is your authored
@@ -438,6 +443,12 @@ of the prompt:
    packages can move invariants out of prompt prose and shell scripts.
    Library-first today: no CLI, no harness-specific task-dispatch adapter.
 
+26. **[`packages/agent-workbench`](./packages/agent-workbench)** — [`@agent-pattern-labs/agent-workbench`](https://www.npmjs.com/package/@agent-pattern-labs/agent-workbench)
+   Local operator workbench for ISO-based agent harness projects. Discovers
+   harnesses on disk, classifies JobForge/leads-rig/ProfileScribe/ISO projects,
+   and summarizes scripts, MCP servers, generated harness config, ledgers,
+   caches, traces, and attention items before you choose the next command.
+
 Each package is independently published on npm and works on its own.
 They're in one repo because they're designed to compose.
 
@@ -729,7 +740,8 @@ iso/
     ├── iso-redact/       # deterministic sensitive-data redaction
     ├── iso-migrate/      # deterministic consumer project migrations
     ├── iso-contract/     # deterministic artifact contracts
-    └── iso-capabilities/ # deterministic role capability policy
+    ├── iso-capabilities/ # deterministic role capability policy
+    └── agent-workbench/  # local operator view across harness projects
 ```
 
 ## Build & test
@@ -758,6 +770,7 @@ npm --workspace @agent-pattern-labs/iso-lineage run test    # iso-lineage artifa
 npm --workspace @agent-pattern-labs/iso-preflight run test  # iso-preflight dispatch planning tests
 npm --workspace @agent-pattern-labs/iso-postflight run test # iso-postflight settlement tests
 npm --workspace @agent-pattern-labs/iso-redact run test     # iso-redact policy/redaction tests
+npm --workspace @agent-pattern-labs/agent-workbench run test # local workbench discovery tests
 npm --workspace @agent-pattern-labs/iso-migrate run test    # iso-migrate project migration tests
 npm --workspace @agent-pattern-labs/iso-contract run test   # iso-contract artifact contract tests
 npm --workspace @agent-pattern-labs/iso-capabilities run test # iso-capabilities policy tests
@@ -815,7 +828,7 @@ downstream repo would use.
 
 `npm run test:pack` goes one level further: it packs the local workspaces into
 tarballs, installs them into fresh temp projects, and smoke-tests the packaged
-`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `iso-facts`, `iso-canon`, `iso-score`, `iso-timeline`, `iso-prioritize`, `iso-lineage`, `iso-preflight`, `iso-postflight`, `iso-redact`, `iso-migrate`, `iso-contract`, and `iso-capabilities`
+`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `iso-facts`, `iso-canon`, `iso-score`, `iso-timeline`, `iso-prioritize`, `iso-lineage`, `iso-preflight`, `iso-postflight`, `iso-redact`, `iso-migrate`, `iso-contract`, `iso-capabilities`, and `agent-workbench`
 CLIs. This guards against packaging regressions that workspace-only tests can
 miss.
 

package-lock.json

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razroo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/agent-workbench/LICENSE

@@ -0,0 +1,70 @@
+# @agent-pattern-labs/agent-workbench
+
+Local operator workbench for ISO-based agent harness projects.
+
+`agent-workbench` discovers harness projects on disk and summarizes the
+configuration, scripts, MCP servers, and local state files an operator usually
+needs before deciding what to run next.
+
+## Install
+
+```bash
+npm install -D @agent-pattern-labs/agent-workbench
+```
+
+Or run it ad hoc:
+
+```bash
+npx @agent-pattern-labs/agent-workbench scan ~/AgentPatternLabs
+```
+
+## CLI
+
+```bash
+agent-workbench scan [root] [--max-depth 3] [--json]
+agent-workbench status [project] [--json]
+agent-workbench doctor [root] [--max-depth 3] [--json]
+```
+
+`scan` is the default command:
+
+```bash
+agent-workbench ~/AgentPatternLabs
+```
+
+The scanner recognizes:
+
+- ISO projects with `agent.md`, `iso/`, `models.yaml`, or generated harness files.
+- JobForge projects and packages.
+- `@agent-pattern-labs/leads-rig` projects and packages.
+- `@agent-pattern-labs/profile-scribe-rig` projects and packages.
+- Generic package workspaces that depend on ISO or Agent Pattern Labs packages.
+
+## Library API
+
+```js
+import {
+  discoverProjects,
+  readProjectStatus,
+  summarizeWorkspace,
+  formatSummary,
+} from '@agent-pattern-labs/agent-workbench';
+
+const summary = summarizeWorkspace('/Users/charlie/AgentPatternLabs');
+console.log(formatSummary(summary));
+```
+
+## What It Checks
+
+For each discovered project, the workbench reports:
+
+- project kind and package name
+- common operational scripts such as `verify`, `smoke:iso`, `build:config`,
+  `trace:list`, and `guard:audit`
+- agent/harness markers such as `AGENTS.md`, `agent.md`, `iso/`,
+  `models.yaml`, `.codex/config.toml`, `.mcp.json`, and `opencode.json`
+- MCP server names found in JSON MCP config or Codex TOML config
+- local event ledgers, cache directories, and trace-like directories
+
+The package is intentionally local-only. It does not upload traces, read
+secrets, or call model APIs.

packages/agent-workbench/README.md

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import {
+  formatDoctor,
+  formatProjectStatus,
+  formatSummary,
+  readProjectStatus,
+  summarizeWorkspace,
+} from '../src/index.mjs';
+
+function printHelp() {
+  console.log(`agent-workbench
+
+Usage:
+  agent-workbench scan [root] [--max-depth 3] [--json]
+  agent-workbench status [project] [--json]
+  agent-workbench doctor [root] [--max-depth 3] [--json]
+  agent-workbench --help
+  agent-workbench --version
+`);
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  let command = 'scan';
+  let target = null;
+  let json = false;
+  let maxDepth = 3;
+
+  if (args[0] && !args[0].startsWith('-')) {
+    command = args.shift();
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+    if (arg === '--max-depth') {
+      const value = args[i + 1];
+      if (!value) {
+        throw new Error('--max-depth requires a value');
+      }
+      maxDepth = Number(value);
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--max-depth=')) {
+      maxDepth = Number(arg.slice('--max-depth='.length));
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      command = 'help';
+      continue;
+    }
+    if (arg === '--version' || arg === '-v') {
+      command = 'version';
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`unknown option: ${arg}`);
+    }
+    if (target) {
+      throw new Error(`unexpected argument: ${arg}`);
+    }
+    target = arg;
+  }
+
+  if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+    throw new Error('--max-depth must be a non-negative integer');
+  }
+
+  return { command, target, json, maxDepth };
+}
+
+function main() {
+  const { command, target, json, maxDepth } = parseArgs(process.argv.slice(2));
+
+  if (command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'version') {
+    console.log('0.1.0');
+    return;
+  }
+
+  if (command === 'status') {
+    const status = readProjectStatus(target ?? process.cwd());
+    console.log(json ? JSON.stringify(status, null, 2) : formatProjectStatus(status));
+    return;
+  }
+
+  if (command === 'scan') {
+    const summary = summarizeWorkspace(target ?? process.cwd(), { maxDepth });
+    console.log(json ? JSON.stringify(summary, null, 2) : formatSummary(summary));
+    return;
+  }
+
+  if (command === 'doctor') {
+    const summary = summarizeWorkspace(target ?? process.cwd(), { maxDepth });
+    console.log(json ? JSON.stringify(summary.attention, null, 2) : formatDoctor(summary));
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`agent-workbench: ${error.message}`);
+  process.exit(2);
+}