@jterrats/open-orchestra 0.4.2-beta.1 → 0.5.0-beta.0

package/AGENTS.md

@@ -150,7 +150,7 @@
 - Mark breaking changes with `!` and a `BREAKING CHANGE:` footer.
 - Keep PRs <400 lines. Review your own diff before requesting review.
 
-<!-- open-orchestra:start block-id="runtime-bootstrap" generator="open-orchestra runtime bootstrap" version="1" target="codex" source-manifest="open-orchestra command-manifest,runtime-bootstrap" content-sha256="c215b82bf89b09651384dbee3c7bd8c4e66cab148adc844b4979788848017be5" updated-at="2026-05-06T22:12:02.623Z" -->
+<!-- open-orchestra:start block-id="runtime-bootstrap" generator="open-orchestra runtime bootstrap" version="1" target="codex" source-manifest="open-orchestra command-manifest,runtime-bootstrap" content-sha256="411e2d184a03aafe61fc4b71d49011f83a4f94d33d3a64cc4cd590a979d07319" updated-at="2026-05-10T05:17:06.513Z" -->
 # Open Orchestra Runtime Bootstrap
 
 Runtime target: Codex. Reference Open Orchestra from AGENTS.md so local CLI work follows workflow gates.
@@ -210,9 +210,11 @@ orchestra benchmark --task <ID>
 ```
 
 ## Active Work
-- Run `orchestra health --json`.
-- Run `orchestra task list --json` and identify the active task.
+- At session start, run `orchestra health --json` before implementation or file edits.
+- Run `orchestra task list --json --status pending,blocked,in_progress` and identify resumable work before creating a new task.
 - For the active task, run context, delegation, plan, skills, protocol, and workflow render commands.
+- Run `orchestra validate --pre-run --task <ID> --json` before implementation; resolve missing estimate, workflow run, evidence, or review checks.
+- If a user accepts a smaller/advisory path, record it with `orchestra validate --pre-run --task <ID> --bypass --bypass-rationale "..."`.
 
 ## Task Loop
 - `orchestra health` - Check local tools and workflow readiness.

package/README.md

@@ -4,19 +4,43 @@ Open Orchestra is a local-first, provider-agnostic framework for governed multi-
 
 It coordinates agents through task graphs, durable workflow files, handoffs, reviews, evidence, gates, locks, model routing, model provenance, budget controls, and an autonomous multi-phase workflow engine. The public CLI is `orchestra`.
 
+Package naming: install `@jterrats/open-orchestra`; run the CLI as
+`orchestra`. The shorter `@jterrats/orchestra` package is not the canonical
+published install target.
+
 ## Quick Start
 
 ```bash
-npm install
-npm run build
-node bin/orchestra.js init
-node bin/orchestra.js status
-node bin/orchestra.js roles list --json
+npm install -g @jterrats/open-orchestra
+orchestra init
+orchestra status
+orchestra roles list --json
 ```
 
+When developing Open Orchestra from this repository, use `npm install`,
+`npm run build`, and `node bin/orchestra.js ...` to exercise the local source.
+
 For Claude, Codex, Cursor, VS Code, Windsurf, and generic LLM usage, see
 [docs/runtime-llm-flow.md](docs/runtime-llm-flow.md) and
 [docs/runtime-adapters.md](docs/runtime-adapters.md).
+To start by job-to-be-done, use the
+[persona workflows guide](docs/persona-workflows.md) for PO refinement,
+developer execution, QA validation, tech lead oversight, and release
+management.
+For package naming rules, see [docs/package-naming.md](docs/package-naming.md).
+
+## Supported Platforms
+
+Open Orchestra supports current Node.js LTS/runtime releases on macOS, Linux,
+and Windows. Repository scripts avoid Unix-only shell requirements for the
+core quality and workflow gates; `npm run validate:workflow` runs through a
+Node helper so it works in Windows shells as well as POSIX shells. The CI
+dogfood path validates installed-package init and workflow validation on
+`ubuntu-latest`, `macos-latest`, and `windows-latest`.
+
+Known limitations: publish/release automation may still use GitHub-hosted
+Linux shell steps, but local development, validation, and installed CLI
+dogfooding are expected to be cross-platform.
 
 ## Autonomous Workflow
 

package/dist/advisory-artifacts.d.ts

@@ -0,0 +1,20 @@
+import type { WorkspaceClassification } from "./types.js";
+export interface AdvisoryArtifactsResult {
+    files: string[];
+    projectTask: {
+        id: string;
+        title: string;
+        ownerRole: string;
+        goal: string;
+        scope: string;
+        acceptanceCriteria: string[];
+        assumptions: string[];
+        risks: string[];
+        paths: string[];
+        testStrategy: string;
+    };
+}
+export declare function writeAdvisoryArtifacts({ root, classification, }: {
+    root: string;
+    classification: WorkspaceClassification;
+}): Promise<AdvisoryArtifactsResult>;

package/dist/advisory-artifacts.js

@@ -0,0 +1,136 @@
+import { WORKFLOW_DIR } from "./constants.js";
+import { defaultRoles } from "./defaults.js";
+import { writeArtifact } from "./workspace.js";
+const ADVISORY_DIRECTORY = "advisory";
+export async function writeAdvisoryArtifacts({ root, classification, }) {
+    const projectTask = advisoryProjectTask();
+    const files = [
+        await writeArtifact(root, ADVISORY_DIRECTORY, "README.md", renderAdvisoryReadme(classification)),
+        await writeArtifact(root, ADVISORY_DIRECTORY, "role-guides.md", renderRoleGuides(defaultRoles)),
+        await writeArtifact(root, ADVISORY_DIRECTORY, "decisions.md", renderPortableDecisions()),
+        await writeArtifact(root, ADVISORY_DIRECTORY, "conversion.md", renderConversionGuide()),
+        await writeArtifact(root, ADVISORY_DIRECTORY, "project-task.json", `${JSON.stringify(projectTask, null, 2)}\n`),
+    ];
+    return { files, projectTask };
+}
+function advisoryProjectTask() {
+    return {
+        id: "ADVISORY-CONVERSION",
+        title: "Convert advisory findings into a project task",
+        ownerRole: "product_owner",
+        goal: "Convert advisory findings into a project delivery task",
+        scope: "Advisory findings, decisions, role guides, and conversion path",
+        acceptanceCriteria: [
+            "Target project is confirmed",
+            "Backlog item and scope are approved",
+            "Risks and assumptions are reviewed",
+            "Evidence from advisory artifacts is linked",
+        ],
+        assumptions: ["Target project repository is confirmed before conversion."],
+        risks: ["Advisory findings may require project-owner validation."],
+        paths: [".agent-workflow/advisory"],
+        testStrategy: "Review advisory artifacts and attach project evidence.",
+    };
+}
+function renderAdvisoryReadme(classification) {
+    return `# Advisory Workspace
+
+This workspace was initialized in advisory mode. Open Orchestra created workflow
+state and portable guidance under \`${WORKFLOW_DIR}/advisory\` without writing
+root instruction files.
+
+## Use This For
+
+- Product and technical discovery before choosing a target repository.
+- Reviewing requirements, risks, acceptance criteria, and delivery evidence.
+- Preparing a project task that can be copied into a real project workspace.
+
+## Safe Next Steps
+
+1. Refine findings in \`${WORKFLOW_DIR}/advisory/decisions.md\`.
+2. Review role-specific responsibilities in \`${WORKFLOW_DIR}/advisory/role-guides.md\`.
+3. Follow \`${WORKFLOW_DIR}/advisory/conversion.md\` after the target repo is confirmed.
+4. Convert \`${WORKFLOW_DIR}/advisory/project-task.json\` with \`orchestra advisory convert --json\`.
+
+## Classification
+
+- Kind: \`${classification.kind}\`
+- Write policy: \`${classification.writePolicy}\`
+- Signals: ${classification.signals.map((signal) => `\`${signal}\``).join(", ")}
+`;
+}
+function renderConversionGuide() {
+    return `# Advisory Conversion
+
+Use this checklist after the target project repository is confirmed.
+
+## Convert To A Task
+
+\`\`\`sh
+orchestra advisory convert --json
+\`\`\`
+
+Optional flags:
+
+- \`--file <file>\` converts a different project-task JSON file.
+- \`--id <id>\` overrides the advisory task ID.
+- \`--backlog <url>\` links the converted task to an external backlog item.
+- \`--target-dir <dir>\` writes the task into a specific project workspace.
+
+## Verify
+
+\`\`\`sh
+orchestra status --json
+orchestra health --json
+\`\`\`
+
+Attach the advisory README, decisions, role guides, and this conversion result as evidence on the project task.
+`;
+}
+function renderRoleGuides(roles) {
+    const advisoryRoles = roles.filter((role) => [
+        "product_owner",
+        "analyst",
+        "architect",
+        "developer",
+        "qa",
+        "security",
+        "release_manager",
+        "technical_writer",
+    ].includes(role.id));
+    return `# Advisory Role Guides
+
+${advisoryRoles.map(renderRoleGuide).join("\n\n")}
+`;
+}
+function renderRoleGuide(role) {
+    const activates = (role.activationCriteria ?? ["requested by workflow"])
+        .slice(0, 3)
+        .map((item) => `- ${item}`)
+        .join("\n");
+    return `## ${role.name}
+
+Focus: ${role.description}
+
+Activation:
+${activates}
+`;
+}
+function renderPortableDecisions() {
+    return `# Portable Advisory Decisions
+
+Use this file for decisions that should survive the move from advisory mode to a
+project workspace.
+
+## Decision Template
+
+- Title:
+- Context:
+- Decision:
+- Consequences:
+- Evidence:
+- Owner:
+- Status: proposed
+`;
+}
+//# sourceMappingURL=advisory-artifacts.js.map

package/dist/advisory-artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisory-artifacts.js","sourceRoot":"","sources":["../src/advisory-artifacts.ts"],"names":[],"mappings":"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"}