@jstn-sdk/ma 0.1.11 → 0.1.13

package/mcp/local/team-run.js

@@ -0,0 +1,113 @@
+import fs from "node:fs/promises";
+import {
+  controlTask,
+  getTask,
+  getTaskMailboxRoot,
+  listMaestroTasks,
+  listTasks,
+  loadTaskRegistry,
+  submitTask,
+} from "../../src/runtime/orchestrator.js";
+
+const teamRunResources = [
+  "team-run://tasks",
+  "team-run://maestro-tasks",
+  "team-run://registry",
+  "team-run://mailbox",
+];
+const teamRunTools = [
+  "team_run.submit_task",
+  "team_run.get_status",
+  "team_run.list_tasks",
+  "team_run.wait_task",
+  "team_run.control_task",
+];
+const terminalTaskStatuses = new Set(["done", "blocked", "cancelled"]);
+
+export function listTeamRunResources() {
+  return [...teamRunResources];
+}
+
+export function listTeamRunTools() {
+  return [...teamRunTools];
+}
+
+export async function readTeamRunResource(uri) {
+  if (uri === "team-run://tasks") {
+    return listTasks();
+  }
+  if (uri === "team-run://maestro-tasks") {
+    return listMaestroTasks();
+  }
+  if (uri === "team-run://registry") {
+    return loadTaskRegistry();
+  }
+  if (uri === "team-run://mailbox") {
+    return fs.readdir(getTaskMailboxRoot());
+  }
+
+  throw new Error(`Unknown team_run resource: ${uri}`);
+}
+
+export async function callTeamRunTool(name, args = {}, options = {}) {
+  const localOptions = { ...options, actor: "local-capability:team_run" };
+  if (name === "team_run.submit_task") {
+    return submitTask(args.task ?? args, localOptions);
+  }
+  if (name === "team_run.get_status") {
+    return getTask(args.taskId);
+  }
+  if (name === "team_run.list_tasks") {
+    return args.managerOwner === "$maestro" ? listMaestroTasks() : listTasks();
+  }
+  if (name === "team_run.wait_task") {
+    return waitForTask(args.taskId, args);
+  }
+  if (name === "team_run.control_task") {
+    return controlTask(args.taskId, args.action, localOptions);
+  }
+
+  throw new Error(`Unknown team_run tool: ${name}`);
+}
+
+export async function waitForTask(taskId, { timeoutMs = 1_000, pollMs = 50 } = {}) {
+  if (typeof taskId !== "string" || taskId.trim() === "") {
+    throw new Error("team_run.wait_task requires a taskId");
+  }
+
+  const boundedTimeoutMs = Math.max(0, Math.min(Number(timeoutMs) || 0, 30_000));
+  const boundedPollMs = Math.max(10, Math.min(Number(pollMs) || 50, 1_000));
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt <= boundedTimeoutMs) {
+    const task = await getTask(taskId);
+    if (terminalTaskStatuses.has(task.status)) {
+      return {
+        record_type: "team_run_wait_result",
+        terminal: true,
+        timed_out: false,
+        task,
+      };
+    }
+
+    if (boundedTimeoutMs === 0) {
+      break;
+    }
+    await new Promise((resolve) => setTimeout(resolve, boundedPollMs));
+  }
+
+  return {
+    record_type: "team_run_wait_result",
+    terminal: false,
+    timed_out: true,
+    task: await getTask(taskId),
+  };
+}
+
+export async function checkTeamRunCapability() {
+  const registry = await readTeamRunResource("team-run://registry");
+  return {
+    ready: Array.isArray(registry.tasks),
+    detail: `task registry loaded with ${registry.tasks.length} task(s)`,
+  };
+}

package/mcp/local/trace.js

@@ -0,0 +1,60 @@
+import fs from "node:fs/promises";
+import {
+  getActiveManagerRun,
+  loadManagerRunRegistryOrDefault,
+} from "../../src/runtime/maestro-manager.js";
+import { getTaskMailboxRoot } from "../../src/runtime/orchestrator.js";
+import { createRuntimeSummary, loadRuntimeSnapshot } from "../../src/runtime/runtime-state.js";
+import {
+  loadRuntimeHooksAuditLog,
+  loadRuntimeHooksConfig,
+} from "../../src/runtime/signal-hooks.js";
+
+const traceResources = [
+  "trace://hooks/audit",
+  "trace://hooks/config",
+  "trace://runtime/summary",
+  "trace://manager/runs",
+  "trace://manager/active",
+];
+
+export function listTraceResources() {
+  return [...traceResources];
+}
+
+export async function readTraceResource(uri) {
+  if (uri === "trace://hooks/audit") {
+    return loadRuntimeHooksAuditLog();
+  }
+  if (uri === "trace://hooks/config") {
+    return loadRuntimeHooksConfig();
+  }
+  if (uri === "trace://runtime/summary") {
+    return createRuntimeSummary(await loadRuntimeSnapshot());
+  }
+  if (uri === "trace://manager/runs") {
+    return loadManagerRunRegistryOrDefault();
+  }
+  if (uri === "trace://manager/active") {
+    const registry = await loadManagerRunRegistryOrDefault();
+    return getActiveManagerRun(registry);
+  }
+
+  throw new Error(`Unknown trace resource: ${uri}`);
+}
+
+export async function listTraceEvents() {
+  return fs.readdir(getTaskMailboxRoot());
+}
+
+export async function checkTraceCapability() {
+  const [audit, summary, managerRuns] = await Promise.all([
+    readTraceResource("trace://hooks/audit"),
+    readTraceResource("trace://runtime/summary"),
+    readTraceResource("trace://manager/runs"),
+  ]);
+  return {
+    ready: typeof audit === "string",
+    detail: `trace surfaces loaded; pending mailbox proposals=${summary.pendingMailboxCount}; manager runs=${managerRuns.runs.length}`,
+  };
+}

package/mcp/local-capabilities.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": "0.1.0",
+  "capabilities": [
+    {
+      "kind": "local-capability",
+      "capability": "_state",
+      "transport": "inproc",
+      "module": "./local/state.js",
+      "readinessCheck": "checkStateCapability",
+      "seededByBootstrap": true,
+      "authorityMode": "proposal-only-write-surface"
+    },
+    {
+      "kind": "local-capability",
+      "capability": "memory",
+      "transport": "inproc",
+      "module": "./local/memory.js",
+      "readinessCheck": "checkMemoryCapability",
+      "seededByBootstrap": true
+    },
+    {
+      "kind": "local-capability",
+      "capability": "trace",
+      "transport": "inproc",
+      "module": "./local/trace.js",
+      "readinessCheck": "checkTraceCapability",
+      "seededByBootstrap": true,
+      "observability": ["runtime-summary", "manager-runs"]
+    },
+    {
+      "kind": "local-capability",
+      "capability": "team_run",
+      "transport": "inproc",
+      "module": "./local/team-run.js",
+      "readinessCheck": "checkTeamRunCapability",
+      "seededByBootstrap": true,
+      "authorityMode": "proposal-only-write-surface"
+    },
+    {
+      "kind": "local-capability",
+      "capability": "code_intel",
+      "transport": "inproc",
+      "module": "./local/code-intel.js",
+      "readinessCheck": "checkCodeIntelCapability",
+      "seededByBootstrap": true
+    },
+    {
+      "kind": "local-capability",
+      "capability": "playbooks",
+      "transport": "inproc",
+      "module": "./local/playbooks.js",
+      "readinessCheck": "checkPlaybooksCapability",
+      "seededByBootstrap": true
+    }
+  ]
+}

package/mcp/native-playbooks.json

@@ -0,0 +1,117 @@
+{
+  "schemaVersion": "0.1.0",
+  "packs": [
+    {
+      "id": "native-ingest-core",
+      "title": "Native Ingest Core",
+      "summary": "Read-only Meta-Architect playbook pack for support-bundle-aware runtime wiring and native packaging discipline.",
+      "readOnly": true,
+      "applicableSkills": ["maestro", "sage", "vet", "align", "diagnose", "tdd", "cleanup"],
+      "runtimeSurfaces": [
+        "mcp/native-playbooks.json",
+        "mcp/local/playbooks.js",
+        "mcp/local-capabilities.json",
+        "docs/installed-sdk.md",
+        "docs/mcp-setup.md"
+      ],
+      "patterns": [
+        {
+          "id": "single-umbrella-routing",
+          "title": "Keep maestro singular",
+          "guidance": "Route native helper families through maestro while keeping the gated release sequence unchanged.",
+          "appliesTo": ["maestro"]
+        },
+        {
+          "id": "read-only-local-capability",
+          "title": "Expose playbooks read-only",
+          "guidance": "Treat playbooks as a packaged local capability with allowlisted resource reads and no mutating local tools.",
+          "appliesTo": ["maestro", "align", "diagnose", "tdd", "cleanup"]
+        },
+        {
+          "id": "bundle-first-support-assets",
+          "title": "Prefer packaged assets",
+          "guidance": "Use support-bundle-installed docs and packaged MCP assets instead of source-checkout-relative guessing.",
+          "appliesTo": ["maestro", "sage", "vet"]
+        }
+      ],
+      "references": [
+        {
+          "id": "installed-support-bundle",
+          "title": "Installed support bundle contract",
+          "path": "docs/installed-sdk.md",
+          "role": "support-bundle"
+        },
+        {
+          "id": "mcp-setup",
+          "title": "MCP setup and GitMCP verification",
+          "path": "docs/mcp-setup.md",
+          "role": "mcp-setup"
+        },
+        {
+          "id": "native-engineering-patterns",
+          "title": "Native engineering patterns",
+          "path": "docs/reference/native-engineering-patterns.md",
+          "role": "reference"
+        },
+        {
+          "id": "native-style-and-deslop",
+          "title": "Native style and deslop",
+          "path": "docs/reference/native-style-and-deslop.md",
+          "role": "reference"
+        },
+        {
+          "id": "native-security-playbooks",
+          "title": "Native security playbooks",
+          "path": "docs/reference/native-security-playbooks.md",
+          "role": "reference"
+        },
+        {
+          "id": "native-source-selection",
+          "title": "Native source selection",
+          "path": "docs/reference/native-source-selection.md",
+          "role": "reference"
+        },
+        {
+          "id": "maestro-native-ingest-map",
+          "title": "Maestro native ingest map",
+          "path": "skills/maestro/references/native-ingest-map.md",
+          "role": "skill-reference"
+        },
+        {
+          "id": "sage-source-selection-pack",
+          "title": "Sage source selection pack",
+          "path": "skills/sage/references/source-selection.md",
+          "role": "skill-reference"
+        },
+        {
+          "id": "vet-security-playbooks-pack",
+          "title": "Vet security playbooks pack",
+          "path": "skills/vet/references/security-playbooks.md",
+          "role": "skill-reference"
+        },
+        {
+          "id": "align-shared-language-pack",
+          "title": "Align shared language pack",
+          "path": "skills/align/references/shared-language.md",
+          "role": "skill-reference"
+        },
+        {
+          "id": "cleanup-style-and-deslop-pack",
+          "title": "Cleanup style and deslop pack",
+          "path": "skills/cleanup/references/style-and-deslop.md",
+          "role": "skill-reference"
+        }
+      ],
+      "provenance": [
+        {
+          "kind": "product-rule",
+          "note": "Repo-owned native curation only; do not expose upstream-branded catalogs as first-class product surfaces."
+        },
+        {
+          "kind": "release-scope",
+          "note": "Playbooks stay read-only in this release and extend the existing first-party local capability registry."
+        }
+      ]
+    }
+  ]
+}

package/mcp/servers.json

@@ -2,54 +2,88 @@
   "schemaVersion": "0.1.0",
   "servers": [
     {
+      "kind": "gitmcp-evidence",
       "category": "meta-list",
       "repo": "sindresorhus/awesome",
       "endpoint": "https://gitmcp.io/sindresorhus/awesome"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "typescript",
       "repo": "dzharii/awesome-typescript",
       "endpoint": "https://gitmcp.io/dzharii/awesome-typescript"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "rust",
       "repo": "rust-unofficial/awesome-rust",
       "endpoint": "https://gitmcp.io/rust-unofficial/awesome-rust"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "go",
       "repo": "avelino/awesome-go",
       "endpoint": "https://gitmcp.io/avelino/awesome-go"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "python",
       "repo": "vinta/awesome-python",
       "endpoint": "https://gitmcp.io/vinta/awesome-python"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "java",
       "repo": "akullpp/awesome-java",
       "endpoint": "https://gitmcp.io/akullpp/awesome-java"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "dotnet",
       "repo": "quozd/awesome-dotnet",
       "endpoint": "https://gitmcp.io/quozd/awesome-dotnet"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "security",
       "repo": "sbilly/awesome-security",
       "endpoint": "https://gitmcp.io/sbilly/awesome-security"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "self-hosted",
       "repo": "awesome-selfhosted/awesome-selfhosted",
       "endpoint": "https://gitmcp.io/awesome-selfhosted/awesome-selfhosted"
     },
     {
+      "kind": "gitmcp-evidence",
       "category": "system-design",
       "repo": "checkcheckzz/system-design-interview",
       "endpoint": "https://gitmcp.io/checkcheckzz/system-design-interview"
+    },
+    {
+      "kind": "gitmcp-evidence",
+      "category": "obsidian-api-docs",
+      "repo": "obsidianmd/obsidian-api",
+      "endpoint": "https://gitmcp.io/obsidianmd/obsidian-api"
+    },
+    {
+      "kind": "gitmcp-evidence",
+      "category": "obsidian-plugin-scaffold",
+      "repo": "obsidianmd/obsidian-sample-plugin",
+      "endpoint": "https://gitmcp.io/obsidianmd/obsidian-sample-plugin"
+    },
+    {
+      "kind": "gitmcp-evidence",
+      "category": "context-economy",
+      "repo": "JuliusBrussee/caveman",
+      "endpoint": "https://gitmcp.io/JuliusBrussee/caveman"
+    },
+    {
+      "kind": "gitmcp-evidence",
+      "category": "prompt-techniques",
+      "repo": "NirDiamant/Prompt_Engineering",
+      "endpoint": "https://gitmcp.io/NirDiamant/Prompt_Engineering"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
   "license": "MIT",
   "author": "JustineDevs",
@@ -41,9 +41,12 @@
     "sprint/",
     "skills/",
     "docs/",
+    "data/",
     "scripts/",
     "index.js",
     "README.md",
+    "DEMO.md",
+    "COVERAGE.md",
     "LICENSE"
   ],
   "exports": {
@@ -56,13 +59,16 @@
   "scripts": {
     "prepare": "husky",
     "postinstall": "node ./scripts/postinstall.js",
-    "test": "node --test",
+    "test": "node --test --test-concurrency=1",
     "status": "node ./bin/ma.js status",
+    "linux:packages:build": "node ./scripts/build-linux-packages.mjs",
+    "linux:packages:smoke": "node ./scripts/linux-package-smoke.mjs",
     "build:gate": "node ./bin/ma.js run '$build'",
     "release:meta": "node ./scripts/release-metadata.js",
     "release:sync": "node ./scripts/release-sync.js",
     "release:advance": "node ./scripts/release-sync.js --force --bump patch",
     "release:verify": "node ./scripts/release-verify.js",
+    "release:assets": "node ./.github/scripts/validate-release-assets.js",
     "release:check": "npm run release:verify && npm run skills:manifest && npm run plugin:sync && npm run skills:validate && npm run plugin:verify && npm run skills:pack && npm run check && npm test && npm run pack:inspect",
     "skills:manifest": "node ./scripts/skills-manifest.js",
     "skills:validate": "node ./scripts/skills-validate.js",

package/plugins/meta-architect/.app.json

@@ -1,7 +1,7 @@
 {
   "name": "meta-architect",
   "displayName": "Meta-Architect",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Programmatic architecture and verified engineering skills for Codex-native workflows.",
   "entry": "./README.md",
   "skillsDir": "./skills"

package/plugins/meta-architect/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "meta-architect",
-  "version": "0.1.11",
-  "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
+  "version": "0.1.13",
+  "description": "Skills-first workflow layer for Codex with a bounded autonomous manager, architecture, evidence, review, and gated build guidance.",
   "author": {
     "name": "JustineDevs",
     "url": "https://github.com/JustineDevs"
@@ -15,8 +15,8 @@
   "apps": "./.app.json",
   "interface": {
     "displayName": "Meta-Architect",
-    "shortDescription": "Architecture-first skill bundle for Codex workflows.",
-    "longDescription": "Meta-Architect packages reusable Codex skills plus plugin-scoped MCP and app metadata. The in-session skill workflow is primary. The ma helper command and .ma state only support setup, release gates, and optional local helper automation.",
+    "shortDescription": "Architecture-first skill bundle with a bounded in-session autonomous manager.",
+    "longDescription": "Meta-Architect packages reusable Codex skills plus plugin-scoped MCP and app metadata. The in-session skill workflow is primary, with `$maestro` as the single bounded autonomous manager over the fixed gated sequence and the publishable non-gating helper skills. The `ma` helper command and `.ma` state only support setup, release gates, and optional local helper automation.",
     "developerName": "JustineDevs",
     "category": "Developer Tools"
   }

package/plugins/meta-architect/.mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "collections": [
     "sindresorhus/awesome",
     "dzharii/awesome-typescript",

package/plugins/meta-architect/README.md

@@ -9,6 +9,10 @@ This plugin bundle packages the Meta-Architect skill surfaces for consumers that
   - `.app.json`
   - `.mcp.json`
 - bundled Meta-Architect skill surfaces under `skills/`
+- one umbrella autonomous manager: `$maestro`
+- fixed gated lanes: `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
+- non-gating helper skills: `$align`, `$diagnose`, `$tdd`, `$cleanup`
+- packaged native reference files mirrored under the relevant skill folders
 - a release-scoped version line aligned to the repo
 
 ## What the plugin does not contain
@@ -44,8 +48,35 @@ Use the core repo when you want to develop Meta-Architect itself. Use the plugin
 
 The plugin-facing bundle should be consumed alongside the repository’s documented packaging/install flow.
 
+Recommended CLI install for macOS, Linux, WSL, and Git-Bash:
+
+```bash
+# One-line install (POSIX shells only; use WSL/Git-Bash on Windows)
+curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh
+```
+
 Canonical package/runtime path:
 
+Debian-family install:
+
+```bash
+sudo apt install ./meta-architect_<version>_all.deb
+```
+
+Arch-family install:
+
+```bash
+sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
+```
+
+Fedora/openSUSE install:
+
+```bash
+sudo dnf install ./meta-architect-<version>-1.noarch.rpm
+```
+
+npm fallback/default supported path:
+
 ```bash
 # Install
 npm i -g @openai/codex@latest @jstn-sdk/ma@latest
@@ -79,6 +110,8 @@ npm run skills:install -- --path ./dist/installed-skills
 
 Consumer expectation:
 - the plugin ships the same public skill contracts as the canonical `skills/` directory
+- `$maestro` remains the only umbrella surface in the plugin bundle and acts as the bounded autonomous manager for the in-session workflow
+- helper skills are installable mirrors, but they remain non-gating and do not create new release gates
 - it does not define a looser or simplified product contract
 
 ## MCP wiring expectations
@@ -105,7 +138,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.11`
+- plugin scope is aligned to Meta-Architect `v0.1.13`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.