@jterrats/open-orchestra 0.5.0-beta.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -0
- package/dist/workspace-classification.js +10 -10
- package/dist/workspace-classification.js.map +1 -1
- package/docs/architecture.md +35 -0
- package/docs/orchestra-mvp.md +29 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -17,12 +17,28 @@ orchestra status
|
|
|
17
17
|
orchestra roles list --json
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
+
Stable installs use `npm install -g @jterrats/open-orchestra@latest`. Beta
|
|
21
|
+
dogfooding uses `npm install -g @jterrats/open-orchestra@beta`, followed by:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
orchestra upgrade --smoke --json
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
For discovery or audits before adopting project-owned instruction files, start
|
|
28
|
+
in advisory mode:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
orchestra init --advisory
|
|
32
|
+
orchestra advisory convert --json
|
|
33
|
+
```
|
|
34
|
+
|
|
20
35
|
When developing Open Orchestra from this repository, use `npm install`,
|
|
21
36
|
`npm run build`, and `node bin/orchestra.js ...` to exercise the local source.
|
|
22
37
|
|
|
23
38
|
For Claude, Codex, Cursor, VS Code, Windsurf, and generic LLM usage, see
|
|
24
39
|
[docs/runtime-llm-flow.md](docs/runtime-llm-flow.md) and
|
|
25
40
|
[docs/runtime-adapters.md](docs/runtime-adapters.md).
|
|
41
|
+
For the system map, see [docs/architecture.md](docs/architecture.md).
|
|
26
42
|
To start by job-to-be-done, use the
|
|
27
43
|
[persona workflows guide](docs/persona-workflows.md) for PO refinement,
|
|
28
44
|
developer execution, QA validation, tech lead oversight, and release
|
|
@@ -42,6 +58,11 @@ Known limitations: publish/release automation may still use GitHub-hosted
|
|
|
42
58
|
Linux shell steps, but local development, validation, and installed CLI
|
|
43
59
|
dogfooding are expected to be cross-platform.
|
|
44
60
|
|
|
61
|
+
Release readiness should be judged against the latest pushed commit. A
|
|
62
|
+
production release is ready only after the local precommit gate and CI
|
|
63
|
+
installed-package dogfood pass on Ubuntu, macOS, and Windows for the current
|
|
64
|
+
HEAD.
|
|
65
|
+
|
|
45
66
|
## Autonomous Workflow
|
|
46
67
|
|
|
47
68
|
The `workflow run` command executes a full story lifecycle as a governed multi-phase sequence without manual step-by-step commands. Each phase creates a sub-task, generates handoff artifacts, and persists state in an append-only run log.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { access, stat } from "node:fs/promises";
|
|
1
|
+
import { access, realpath, stat } from "node:fs/promises";
|
|
2
2
|
import os from "node:os";
|
|
3
3
|
import path from "node:path";
|
|
4
4
|
import { detectProjectProfile } from "./project-detection.js";
|
|
@@ -59,15 +59,14 @@ export async function classifyWorkspace({ root = process.cwd(), advisory = false
|
|
|
59
59
|
confidence: signals.length > 1 ? "high" : "medium",
|
|
60
60
|
});
|
|
61
61
|
}
|
|
62
|
+
const isTempChild = await isTemporaryChild(normalizedRoot);
|
|
62
63
|
return buildClassification({
|
|
63
64
|
root,
|
|
64
65
|
normalizedRoot,
|
|
65
66
|
kind: "unknown",
|
|
66
67
|
signals,
|
|
67
68
|
reasons: ["no project signals detected"],
|
|
68
|
-
writePolicy:
|
|
69
|
-
? "allow"
|
|
70
|
-
: "confirm_required",
|
|
69
|
+
writePolicy: isTempChild ? "allow" : "confirm_required",
|
|
71
70
|
recommendedAction: "Use --confirm-unknown for an intentional empty workspace, --advisory for consulting mode, or --target-dir for a project directory.",
|
|
72
71
|
confidence: "low",
|
|
73
72
|
});
|
|
@@ -87,7 +86,7 @@ async function collectUnsafeReasons(root) {
|
|
|
87
86
|
if (root === os.homedir()) {
|
|
88
87
|
reasons.push("user home directory");
|
|
89
88
|
}
|
|
90
|
-
if (temporaryRootCandidates().includes(root)) {
|
|
89
|
+
if ((await temporaryRootCandidates()).includes(root)) {
|
|
91
90
|
reasons.push("system temporary directory");
|
|
92
91
|
}
|
|
93
92
|
if (isBroadParentDirectory(root)) {
|
|
@@ -109,19 +108,20 @@ function isBroadParentDirectory(root) {
|
|
|
109
108
|
const baseName = path.basename(root).toLowerCase();
|
|
110
109
|
return BROAD_PARENT_NAMES.has(baseName);
|
|
111
110
|
}
|
|
112
|
-
function isTemporaryChild(root) {
|
|
113
|
-
return temporaryRootCandidates().some((tempRoot) => {
|
|
111
|
+
async function isTemporaryChild(root) {
|
|
112
|
+
return (await temporaryRootCandidates()).some((tempRoot) => {
|
|
114
113
|
const relativePath = path.relative(tempRoot, root);
|
|
115
114
|
return (relativePath !== "" &&
|
|
116
115
|
!relativePath.startsWith("..") &&
|
|
117
116
|
!path.isAbsolute(relativePath));
|
|
118
117
|
});
|
|
119
118
|
}
|
|
120
|
-
function temporaryRootCandidates() {
|
|
119
|
+
async function temporaryRootCandidates() {
|
|
121
120
|
const tempRoot = path.resolve(os.tmpdir());
|
|
121
|
+
const roots = [tempRoot, await realpath(tempRoot).catch(() => tempRoot)];
|
|
122
122
|
if (tempRoot.startsWith("/var/")) {
|
|
123
|
-
|
|
123
|
+
roots.push(path.join("/private", tempRoot));
|
|
124
124
|
}
|
|
125
|
-
return [
|
|
125
|
+
return [...new Set(roots)];
|
|
126
126
|
}
|
|
127
127
|
//# sourceMappingURL=workspace-classification.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"workspace-classification.js","sourceRoot":"","sources":["../src/workspace-classification.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"workspace-classification.js","sourceRoot":"","sources":["../src/workspace-classification.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
Open Orchestra is a local-first workflow control plane. The CLI remains the
|
|
4
|
+
source of truth, while web, VS Code, and agent runtimes use the same workflow
|
|
5
|
+
files and JSON command contracts.
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
## How To Read It
|
|
10
|
+
|
|
11
|
+
- **Entry points** are humans, agent runtimes, the local web console, and IDE
|
|
12
|
+
surfaces. They all route through the public `orchestra` command surface.
|
|
13
|
+
- **CLI layer** owns command parsing, command manifest metadata, JSON contracts,
|
|
14
|
+
and stable local behavior.
|
|
15
|
+
- **Core workflow services** coordinate task graphs, autonomous workflow runs,
|
|
16
|
+
gates, role-scoped memory, skills, and release readiness.
|
|
17
|
+
- **State and integrations** stay explicit: `.agent-workflow/` is local
|
|
18
|
+
durable state; model providers and trackers are integration boundaries; docs,
|
|
19
|
+
site, npm, and release tags are delivery outputs.
|
|
20
|
+
|
|
21
|
+
## Design Principles
|
|
22
|
+
|
|
23
|
+
- Local workflow state is durable and reviewable.
|
|
24
|
+
- Network calls are explicit, opt-in, or CI-owned.
|
|
25
|
+
- Tracker integrations use stable child-process calls locally, or runtime MCP
|
|
26
|
+
skills/adapters when the tracker belongs to the agent runtime.
|
|
27
|
+
- Release decisions are evidence-based: acceptance coverage, smoke, rollback,
|
|
28
|
+
locks, reviews, and blockers are visible before publish.
|
|
29
|
+
|
|
30
|
+
## Related Docs
|
|
31
|
+
|
|
32
|
+
- [MVP guide](orchestra-mvp.md)
|
|
33
|
+
- [Persona workflows](persona-workflows.md)
|
|
34
|
+
- [Runtime adapters](runtime-adapters.md)
|
|
35
|
+
- [Traceability flow](traceability-flow.md)
|
package/docs/orchestra-mvp.md
CHANGED
|
@@ -4,6 +4,9 @@ Open Orchestra is a local-first, provider-agnostic framework for governed multi-
|
|
|
4
4
|
|
|
5
5
|
It stores workflow state in `.agent-workflow/` and coordinates agents through files, events, handoffs, reviews, evidence, gates, locks, and model provenance.
|
|
6
6
|
|
|
7
|
+
See [architecture.md](architecture.md) for the system diagram and layer
|
|
8
|
+
overview.
|
|
9
|
+
|
|
7
10
|
## Compatibility
|
|
8
11
|
|
|
9
12
|
- `orchestra` is the only public CLI name.
|
|
@@ -113,6 +116,23 @@ labels -> risks, milestone -> scope, and `## Test Evidence Required` -> test
|
|
|
113
116
|
strategy. Teams can make the mapping explicit per run with command flags until
|
|
114
117
|
project-level mapping policy is added.
|
|
115
118
|
|
|
119
|
+
Advisory mode is the consulting or audit entry point. It creates
|
|
120
|
+
`.agent-workflow/advisory/` artifacts without writing root instruction files
|
|
121
|
+
such as `AGENTS.md` or `ORCHESTRA.md`. Use it when the target repository still
|
|
122
|
+
needs evaluation or owner approval:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
orchestra init --advisory
|
|
126
|
+
orchestra status --json
|
|
127
|
+
orchestra health --json
|
|
128
|
+
orchestra advisory convert --json
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The advisory artifacts include a README, role guides, portable decisions,
|
|
132
|
+
conversion guide, and `project-task.json`. After the target project is
|
|
133
|
+
confirmed, `orchestra advisory convert` promotes that JSON into a real workflow
|
|
134
|
+
task while keeping writes inside workflow-owned paths.
|
|
135
|
+
|
|
116
136
|
Context, memory, skills, and runtime rendering:
|
|
117
137
|
|
|
118
138
|
```bash
|
|
@@ -166,6 +186,15 @@ dogfooding uses `npm install -g @jterrats/open-orchestra@beta` or the exact
|
|
|
166
186
|
version reported by `orchestra upgrade --beta`. After upgrading, run the smoke
|
|
167
187
|
command shown by the CLI to verify the installed binary and health report.
|
|
168
188
|
|
|
189
|
+
Release go/no-go:
|
|
190
|
+
|
|
191
|
+
- Run `npm run precommit` locally before pushing release changes.
|
|
192
|
+
- Confirm GitHub Actions CI is green for the latest pushed HEAD.
|
|
193
|
+
- Confirm installed-package dogfooding passes on `ubuntu-latest`,
|
|
194
|
+
`macos-latest`, and `windows-latest`.
|
|
195
|
+
- Confirm `Create release tag`, site publish, and npm publish workflows are
|
|
196
|
+
successful for the intended release commit.
|
|
197
|
+
|
|
169
198
|
Model routing, budget, telemetry, and release:
|
|
170
199
|
|
|
171
200
|
```bash
|