@azure-id/orc 0.55.0 โ 0.56.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/CHANGELOG.md +2139 -2017
- package/README-id.md +592 -521
- package/README.md +610 -485
- package/bin/cli.js +29236 -29050
- package/bin/webui/i18n/en/overview.json +90 -89
- package/bin/webui/i18n/id/overview.json +90 -89
- package/bin/webui/js/03-md.js +9 -3
- package/bin/webui/js/panels/overview.js +453 -447
- package/package.json +39 -39
- package/templates/skills/orc-fast/SKILL.md +187 -188
- package/templates/skills/orc-quick/SKILL.md +313 -306
package/README.md
CHANGED
|
@@ -1,485 +1,610 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# ๐ ORC
|
|
4
|
-
|
|
5
|
-
**An orchestrator skill constellation for [Claude Code](https://claude.com/claude-code).**
|
|
6
|
-
|
|
7
|
-
*Intake โ analyze โ plan โ score โ parallel subagents โ review โ verify โ ship.*
|
|
8
|
-
|
|
9
|
-
.**
|
|
6
|
+
|
|
7
|
+
*Intake โ analyze โ plan โ score โ parallel subagents โ review โ verify โ ship.*
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
**Latest: v0.56.0** ยท updated 2026-08-27 ยท [full changelog](CHANGELOG.md)
|
|
18
|
+
|
|
19
|
+
**On npm: [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)** โ `npm i -g @azure-id/orc`
|
|
20
|
+
|
|
21
|
+
**๐ฎ๐ฉ [Baca dalam Bahasa Indonesia](README-id.md)**
|
|
22
|
+
|
|
23
|
+
</div>
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
> [!CAUTION]
|
|
28
|
+
> **Upgrading from a version before v0.56.0? Do this once.**
|
|
29
|
+
>
|
|
30
|
+
> The package moved from the unscoped `orc` to **`@azure-id/orc`**. Both declare
|
|
31
|
+
> the same `orc` command, and npm will not hand that command to the new package
|
|
32
|
+
> while the old one still holds it โ so **every** install source fails with the
|
|
33
|
+
> same error, and `orc upgrade` cannot fix itself:
|
|
34
|
+
>
|
|
35
|
+
> ```text
|
|
36
|
+
> npm error code EEXIST
|
|
37
|
+
> npm error File exists: C:\Users\you\AppData\Roaming\npm\orc
|
|
38
|
+
> ```
|
|
39
|
+
>
|
|
40
|
+
> Run these two lines once. Nothing in your `.claude/` is touched, and your
|
|
41
|
+
> `orc.config.yaml` survives:
|
|
42
|
+
>
|
|
43
|
+
> ```bash
|
|
44
|
+
> npm uninstall -g orc # release the `orc` command from the old package
|
|
45
|
+
> npm i -g @azure-id/orc # install the current one
|
|
46
|
+
> orc update # re-apply into this project (add --global for ~/.claude)
|
|
47
|
+
> ```
|
|
48
|
+
>
|
|
49
|
+
> **From v0.56.0 onward `orc upgrade` handles this for you** โ it removes the old
|
|
50
|
+
> package first, then installs, and says so while it does it. `orc doctor` also
|
|
51
|
+
> reports the old package by name if it is still there.
|
|
52
|
+
>
|
|
53
|
+
> Do **not** reach for `npm i -g -f`. `--force` overwrites the command file and
|
|
54
|
+
> leaves the superseded package installed underneath, owning nothing and never
|
|
55
|
+
> updated again.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
> [!IMPORTANT]
|
|
60
|
+
> **`orc-open` is released โ ORC for non-Claude agents.**
|
|
61
|
+
> A provider-agnostic port of the pipeline:
|
|
62
|
+
> **[github.com/azure-id/orc-open](https://github.com/azure-id/orc-open)**. Use it
|
|
63
|
+
> if you run a different coding agent. This repository stays Claude Codeโnative.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## What ORC is
|
|
68
|
+
|
|
69
|
+
You give ORC a feature โ or a requirements document. It works out what you
|
|
70
|
+
meant, plans the work, sends each task to the **cheapest model that can still do
|
|
71
|
+
it**, runs the tasks that do not collide **at the same time**, reviews the
|
|
72
|
+
result, verifies it against a definition of done you signed off, and ships it.
|
|
73
|
+
|
|
74
|
+
It writes its state to disk as it goes, so a long run survives a pause, a token
|
|
75
|
+
limit, or a brand new chat session.
|
|
76
|
+
|
|
77
|
+
**ORC is not a program that runs.** It is a set of markdown **skills**, **slash
|
|
78
|
+
commands** and **subagent definitions** that Claude Code reads and follows. This
|
|
79
|
+
zero-dependency npm package copies those files into your `.claude/` folder.
|
|
80
|
+
|
|
81
|
+
```text
|
|
82
|
+
โโโโโโโโโโโโโโโโโ you own scope + sign-off โโโโโโโโโโโโโโโโโ
|
|
83
|
+
feature / doc โโโถ intake โโถ analyze โโถ plan โโถ score โโถ โ parallel waves โ โโถ review โโถ verify โโถ ship
|
|
84
|
+
(grounded) (per task) (cheapest capable model) (checkpointed to disk)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## ๐ See it run before you run it
|
|
90
|
+
|
|
91
|
+
Every lane is written out as a **mocked run**: what you type, what ORC prints
|
|
92
|
+
back, and the files that land on disk. Nothing was executed to make them โ they
|
|
93
|
+
exist so you never have to spend tokens to find out what a command does.
|
|
94
|
+
|
|
95
|
+
### **โถ [Start here: `mock-run/INDEX.md`](mock-run/INDEX.md)**
|
|
96
|
+
|
|
97
|
+
Also available without leaving your machine:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
orc mock-run list # every walkthrough, in reading order
|
|
101
|
+
orc mock-run show orc-pact # read one
|
|
102
|
+
orc ui # โธ Mocked Skill Use โ the same docs, searchable
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Why it works this way
|
|
108
|
+
|
|
109
|
+
A single agent handed a real feature fails the same ways every time: it silently
|
|
110
|
+
picks one reading of your request, runs the most expensive model on everything,
|
|
111
|
+
forgets decisions when the context compacts, says "done" against a definition
|
|
112
|
+
nobody wrote, cites code that does not exist, and leaves nothing to inspect.
|
|
113
|
+
|
|
114
|
+
Those are **process problems** โ the ones teams solved with roles, reviews and
|
|
115
|
+
written agreements. ORC writes that discipline down as skills:
|
|
116
|
+
|
|
117
|
+
- **Coordinating and doing are different jobs.** The orchestrator never
|
|
118
|
+
implements. Even a one-line change goes to a subagent, which keeps its own
|
|
119
|
+
context lean for the whole run.
|
|
120
|
+
- **Every task is scored, and the score picks the model.** You see the table
|
|
121
|
+
before anything starts, and the agents are named and model-pinned, so what ran
|
|
122
|
+
is a fact you can check.
|
|
123
|
+
- **"Done" is written before the work starts.** Intake produces a signed-off
|
|
124
|
+
spec whose definition of done becomes the final verification.
|
|
125
|
+
- **Nothing is trusted, everything is attested.** `file:line` quotes, verbatim
|
|
126
|
+
build output, anchored findings โ and the orchestrator spot-checks them, so a
|
|
127
|
+
made-up citation bounces instead of riding into a task.
|
|
128
|
+
- **Disk beats memory.** Eager checkpoints turn every pause into a clean resume,
|
|
129
|
+
including in a fresh session.
|
|
130
|
+
- **Rigor is a dial.** The same spine runs as `/orc-mini` (one subagent), `/orc`
|
|
131
|
+
(real features), and `/orc-ultra` (advisor plus judgment gates).
|
|
132
|
+
- **It learns.** Code patterns make executors write like your codebase, the wiki
|
|
133
|
+
sharpens every future plan, and traces feed `/orc-retro`, which recalibrates
|
|
134
|
+
the scoring from real runs.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Quick start
|
|
139
|
+
|
|
140
|
+
ORC is on npm as **[`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)**.
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npm i -g @azure-id/orc # install
|
|
144
|
+
npm i -g @azure-id/orc@latest # update to the newest release
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
<details>
|
|
148
|
+
<summary>Install straight from GitHub instead</summary>
|
|
149
|
+
|
|
150
|
+
<br>
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
npm i -g https://github.com/azure-id/orc/archive/refs/heads/main.tar.gz
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
</details>
|
|
157
|
+
|
|
158
|
+
Then, inside a project:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
orc init # install into ./.claude (this project)
|
|
162
|
+
orc init --global # install into ~/.claude (all projects)
|
|
163
|
+
orc onboarding # the whole walkthrough in the terminal โ no GitHub needed
|
|
164
|
+
orc config # view or change settings (zero model tokens)
|
|
165
|
+
orc ui # the local control panel
|
|
166
|
+
orc --help # every command
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
After installing:
|
|
170
|
+
|
|
171
|
+
1. Paste your team's PR template into `skills/orc/subskills/orc-pr/pr.md`.
|
|
172
|
+
2. Add `.claude/orc/run/` to your project `.gitignore`.
|
|
173
|
+
3. Run **`/agents`** to confirm your Claude Code accepts the agent model ids.
|
|
174
|
+
4. **Run your main session on Opus 5.** A subagent can never use a better model
|
|
175
|
+
than your session. This is the most common cause of "it used the wrong
|
|
176
|
+
model" โ see [model selection](guides/model-selection.md).
|
|
177
|
+
5. If a `/command` does not appear, your Claude Code may read commands from a
|
|
178
|
+
different folder โ move the files in `commands/` there.
|
|
179
|
+
|
|
180
|
+
<details>
|
|
181
|
+
<summary><b>Staying up to date</b></summary>
|
|
182
|
+
|
|
183
|
+
<br>
|
|
184
|
+
|
|
185
|
+
`orc update` re-copies the files already in this package. It never uses the
|
|
186
|
+
network. **`orc upgrade` is the one that pulls a new version**: it fetches the
|
|
187
|
+
newest package first, then applies it. Your `.claude/orc.config.yaml` survives
|
|
188
|
+
both.
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
orc version # what you have, and whether something newer exists
|
|
192
|
+
orc changelog # what you would GET by upgrading
|
|
193
|
+
orc upgrade # fetch the latest, then update this project
|
|
194
|
+
orc upgrade --global # the same for ~/.claude
|
|
195
|
+
orc upgrade --from @azure-id/orc # explicitly from npm
|
|
196
|
+
orc upgrade --from github:azure-id/orc # a fork, or any npm spec
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Or update the package yourself and re-apply it:
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
npm i -g @azure-id/orc@latest
|
|
203
|
+
orc update
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The update check reads the source over HTTPS, is cached for 24 hours, and fails
|
|
207
|
+
silently when you are offline. Turn it off with `ORC_NO_UPDATE_CHECK=1`.
|
|
208
|
+
|
|
209
|
+
You do not have to run a command to hear about it: the same notice appears
|
|
210
|
+
inside Claude Code through ORC's hooks, at **zero model tokens** โ hooks are
|
|
211
|
+
scripts Claude Code runs, not model turns.
|
|
212
|
+
|
|
213
|
+
`orc upgrade` tries the npm registry first, then a plain tarball, then the
|
|
214
|
+
GitHub spec โ and it remembers which one worked. If the old unscoped `orc`
|
|
215
|
+
package is still installed, it removes that first (announced), because npm
|
|
216
|
+
cannot give the `orc` command to `@azure-id/orc` while another package owns it.
|
|
217
|
+
See the caution at the top of this README for the one-time manual version.
|
|
218
|
+
|
|
219
|
+
</details>
|
|
220
|
+
|
|
221
|
+
> **"ORC cannot see my wiki"?** Run **`orc wiki sync`**, not a new scan. Docs
|
|
222
|
+
> without a manifest are *unregistered*, not missing โ common when a scan stopped
|
|
223
|
+
> at one of `/orc-wiki`'s pauses. Sync rebuilds the index from the docs you
|
|
224
|
+
> already have, for free.
|
|
225
|
+
|
|
226
|
+
> **"What does ORC actually know about my project?"** `orc wiki docs` lists every
|
|
227
|
+
> registered doc, `orc wiki coverage` says how much of your code is written about
|
|
228
|
+
> at all, and `orc pattern show <lang>` prints the conventions that go into every
|
|
229
|
+
> agent that writes code here. All free, all read-only โ
|
|
230
|
+
> **[`guides/knowledge-reads.md`](guides/knowledge-reads.md)**.
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
## Terminal Hook
|
|
234
|
+
ORC have terminal hook to see: Context Window %, 5 Hour usage %, Weekly usage % and others you might see
|
|
235
|
+
|
|
236
|
+
<img width="725" height="96" alt="image" src="https://github.com/user-attachments/assets/6a649c87-81ea-4fd9-9d0b-6bb4b97fe9cd" />
|
|
237
|
+
|
|
238
|
+
<br>
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## The lanes
|
|
243
|
+
|
|
244
|
+
> [!TIP]
|
|
245
|
+
> They chain naturally: **`/orc-brainstorm` โ `/orc-grill` โ `/orc-analyze` โ
|
|
246
|
+
> `/orc-plan` โ `/orc-route` โ `/orc`**. You can start anywhere.
|
|
247
|
+
|
|
248
|
+
### Build something
|
|
249
|
+
|
|
250
|
+
| Command | What it does | Mocked run |
|
|
251
|
+
|---|---|---|
|
|
252
|
+
| **`/orc`** | The full pipeline: intake โ plan โ scored parallel waves โ review โ verify โ ship. Checkpoints eagerly; resumes in a fresh session. | [see it](mock-run/orc.md) |
|
|
253
|
+
| **`/orc-ultra`** | The same, plus an Opus 5 **xhigh** advisor and three judgment gates. Deep analysis, patterns, tests and security forced on. Costly by design. | [see it](mock-run/orc-ultra.md) |
|
|
254
|
+
| **`/orc-mini`** | One Sonnet 5 executor, a build + test smoke gate, ship. Skips full review and verify. Switches to the full flow mid-run on request. | [see it](templates/skills/orc-mini/examples/mini-run-mock.md) |
|
|
255
|
+
| **`/orc-fast`** | The fastest lane. Needs a fresh wiki **and** a cached code pattern; then it skips the analyst and planner entirely. A missing prerequisite falls back to `/orc-mini` โ the chat never stops. | [see it](mock-run/orc-fast.md) |
|
|
256
|
+
| **`/orc-quick`** | Ask for anything: a fix, a question, a defect hunt, a dependency bump, PR comments. Look โ ask once โ do. **It always asks which agent to dispatch**, and no setting can change that. | [see it](mock-run/orc-quick.md) |
|
|
257
|
+
| **`/orc-diy`** | Your own lane, composed in the terminal with `orc diy` and compiled. Unconfigured or stale โ it refuses and offers plain `/orc`. | [see it](mock-run/orc-diy.md) |
|
|
258
|
+
|
|
259
|
+
### Work out what to build
|
|
260
|
+
|
|
261
|
+
| Command | What it does | Mocked run |
|
|
262
|
+
|---|---|---|
|
|
263
|
+
| **`/orc-brainstorm`** | You do not have the idea yet. It generates candidates against named thinking lenses with **no criticism while generating**, clusters them into a few real directions, stress-tests each, then recommends one and **waits โ it never picks for you**. Every menu ends with your own slot. | [see it](mock-run/orc-brainstorm.md) |
|
|
264
|
+
| **`/orc-grill`** | You have one idea and it is still vague. It asks rounds of questions, **looks facts up itself** instead of making you recite your own codebase, and never answers its own question. Ends when *you* say the idea matches what you meant. | [see it](mock-run/orc-grill.md) |
|
|
265
|
+
| **`/orc-analyze`** | A document or a request โ a scope-bounded, code-grounded spec. Every claim carries `file:line` evidence or becomes a question. Deep mode adds parallel scouts. | [see it](templates/skills/orc-analyze/examples/analyze-mock.md) |
|
|
266
|
+
| **`/orc-plan`** | A request or a spec โ a real task plan: grounded files, dependencies, facets, and a test disposition per task. | [see it](mock-run/orc-plan.md) |
|
|
267
|
+
| **`/orc-doc`** | Writes the long document โ a PRD, a TSD, a cross-team agreement, a status report or a runbook โ as portable Markdown that imports cleanly into Notion, Obsidian, Docs, Coda, Craft and GitHub. **ORC never reads the document body**: each section is its own file under `sections/`, each writer owns exactly one of them, each checker reads one bounded part, and `document.md` is a build artifact rebuilt for free. Every wave is a stop you can walk away from, and it resumes months later without you explaining anything twice. | [see it](mock-run/orc-doc.md) |
|
|
268
|
+
| **`/orc-route`** | You have a plan โ which lane should build it? It names one lane, the runners-up with what each costs you, and any lane that is impossible with the condition blocking it. **It refuses to route a sentence**, because that would be guessing. | [see it](mock-run/orc-route.md) |
|
|
269
|
+
| **`/orc-explain`** | "Wait, what?" It says the last message again: the point first, then the background it assumed, then every ORC-only word defined in your project's terms. | [see it](mock-run/orc-explain.md) |
|
|
270
|
+
| **`/orc-poly`** | One change across two or more repos, without drift. Peer source is read-only; it freezes the shared boundary into a contract and writes one plan per repo. It never builds. | [see it](templates/skills/orc-poly/examples/poly-run-mock.md) |
|
|
271
|
+
|
|
272
|
+
### Teach ORC your project
|
|
273
|
+
|
|
274
|
+
| Command | What it does | Mocked run |
|
|
275
|
+
|---|---|---|
|
|
276
|
+
| **`/orc-wiki`** | Scans your codebase into a persistent `wiki/`, evidence-anchored, and points `CLAUDE.md` at it. Freshness is computed on read, never stored. Expensive and opt-in โ it always warns first. | [see it](templates/skills/orc-wiki/examples/wiki-run-mock.md) |
|
|
277
|
+
| **`/orc-pattern`** | Learns your real conventions per language, so executors write code that matches your codebase. Your conventions win; security and correctness invariants always carry through. | [see it](mock-run/orc-pattern.md) |
|
|
278
|
+
| **`/orc-learn`** | Onboarding docs for a human, one feature at a time, `file:line`-anchored. Local and git-ignored. | [see it](templates/skills/orc-learn/examples/learn-run-mock.md) |
|
|
279
|
+
| **`/orc-claude`** | Builds or refreshes this repo's `CLAUDE.md` from verified facts. Zero questions; your own content is never trimmed. | [see it](templates/skills/orc-claude/examples/claude-run-mock.md) |
|
|
280
|
+
| **`/orc-export`** | Compiles the wiki, patterns, `PACT.md` and boundary cards into a portable `AGENTS.md` โ derived, fingerprinted, `--check`able. So ORC is not a trap. | [see it](mock-run/orc-export.md) |
|
|
281
|
+
|
|
282
|
+
### Check what happened
|
|
283
|
+
|
|
284
|
+
| Command | What it does | Mocked run |
|
|
285
|
+
|---|---|---|
|
|
286
|
+
| **`/orc-challenge`** | Grades a **finished** artifact โ a TSD, a PRD, an ADR, an API contract, a README, a module โ against a goal **you** state, then **stops and makes you fix it in a different session**. ORC judges, you fix, ORC re-judges: **it never fixes what it judged**, because a session that just wrote the fix would grade its own homework. **And it never guesses what "good" means here.** | [see it](mock-run/orc-challenge.md) |
|
|
287
|
+
| **`/orc-pact`** | The promises your project makes, and which are in doubt right now. Four states, all **computed on read**: HOLDING ยท DRIFTED ยท **UNCHECKABLE** (the honest state โ never a failure) ยท BROKEN. It never invents a promise and never retires one for you. | [see it](mock-run/orc-pact.md) |
|
|
288
|
+
| **`/orc-boundary`** | What ORC should **not** try here, and exactly what would change that. EXECUTE ยท ESCALATE ยท REFUSE, per area. **A REFUSE always names what would make it a yes.** It gates ORC's own dispatch, never your instructions. | [see it](mock-run/orc-boundary.md) |
|
|
289
|
+
| **`/orc-verify`** | Verifies only your git-modified changes: build, tests, diff sanity, findings on a P0โP3 ladder. Read-only. | [see it](templates/skills/orc-verify/examples/verify-mock.md) |
|
|
290
|
+
| **`/orc-aftermath`** | Did what we shipped hold up? Graded from the repository's own future: churn, reverts, deleted tests, broken promises. **Churn is a signal, never a verdict**, and it never names a person. | [see it](mock-run/orc-aftermath.md) |
|
|
291
|
+
| **`/orc-budget`** | What a run costs, in the unit you are billed in. A **token vector** โ fresh input, cache write, cache read, output, never blended โ shown four ways: tokens, dollars, percent of your 5-hour window, and context risk. Needs a plan, not a sentence. | [see it](mock-run/orc-budget.md) |
|
|
292
|
+
| **`/orc-retro`** | Mines the behavior traces into a calibration report and files it upstream as a PR. | [see it](templates/skills/orc-retro/examples/retro-mock.md) |
|
|
293
|
+
|
|
294
|
+
### Ship and hand over
|
|
295
|
+
|
|
296
|
+
| Command | What it does | Mocked run |
|
|
297
|
+
|---|---|---|
|
|
298
|
+
| **`/orc-pr-setup`** | Decides where a big change gets cut into stacked pull requests: ordered layers, each with a purpose, a file list and a measured budget. It stops and asks at every uncertain seam, and never touches git. | [see it](mock-run/orc-pr-setup.md) |
|
|
299
|
+
| **`/orc-pr-driver`** | Executes that plan: a branch per layer, a **mandatory green gate at each layer's own base**, `gh stack submit`, then restack and bottom-up merge. | [see it](mock-run/orc-pr-setup.md) |
|
|
300
|
+
| **`/orc-handoff`** | For someone who does not read code. The grade comes from **whether a cheap check exists**, not from the file type. It shows the undo command *before* it writes, and never touches a red file. | [see it](mock-run/orc-handoff.md) |
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Documents that go somewhere
|
|
305
|
+
|
|
306
|
+
`/orc-doc` writes the long document โ and Markdown is the deliverable because of
|
|
307
|
+
where a Markdown file can actually go:
|
|
308
|
+
|
|
309
|
+
| Target | Imports `.md`? |
|
|
310
|
+
|---|---|
|
|
311
|
+
| Notion ยท Obsidian ยท Google Docs ยท Coda ยท Craft ยท Apple Notes ยท GitHub | **natively** |
|
|
312
|
+
| Docusaurus ยท Hugo ยท Jekyll ยท MkDocs | yes โ and these *want* YAML front matter |
|
|
313
|
+
| Confluence | not natively. Plan for a marketplace importer app |
|
|
314
|
+
| Microsoft OneNote | **no**. Convert to Word or PDF first |
|
|
315
|
+
|
|
316
|
+
That table is load-bearing, not decoration: `orc doc lint --target` enforces the
|
|
317
|
+
real limit of the place your document is going. Notion has three heading levels,
|
|
318
|
+
so an H4 is an **error** there. A hard-wrapped paragraph is an error everywhere,
|
|
319
|
+
because a wrap at 80 columns becomes a line break inside a Notion paragraph.
|
|
320
|
+
|
|
321
|
+
Five base templates โ `prd` ยท `tsd` ยท `collaboration` ยท `report` ยท `workflow` โ
|
|
322
|
+
each a floor rather than a cage. `orc doc templates` prints them; bring your own
|
|
323
|
+
and its headings become the outline.
|
|
324
|
+
|
|
325
|
+
**Full detail: [`guides/documents.md`](guides/documents.md).**
|
|
326
|
+
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
## `orc ui` โ the control panel
|
|
330
|
+
|
|
331
|
+
A local web page for **everything in ORC that is not ai**. One boundary defines
|
|
332
|
+
it: **it never runs a lane, never spawns `claude`, never calls a model API.**
|
|
333
|
+
Everything it shows or writes is deterministic CLI output.
|
|
334
|
+
|
|
335
|
+
<img width="1870" height="1269" alt="image" src="https://github.com/user-attachments/assets/207fe821-9aa6-430e-bdcc-968340cc687f" />
|
|
336
|
+
|
|
337
|
+
> ๐ฌ **Video walkthrough โ not recorded yet.** The player belongs here; see
|
|
338
|
+
> [`mock-run/media/README.md`](mock-run/media/README.md) for the two files to
|
|
339
|
+
> drop in. Until then, the panel is written out screen by screen in
|
|
340
|
+
> [`mock-run/orc-ui.md`](mock-run/orc-ui.md).
|
|
341
|
+
|
|
342
|
+
```bash
|
|
343
|
+
orc ui # binds 127.0.0.1:9921 and opens a browser
|
|
344
|
+
orc ui --port 9930 # an explicit port never auto-walks โ a collision is an error
|
|
345
|
+
orc ui --no-open # print the URL only
|
|
346
|
+
orc ui --idle 0 # disable the idle shutdown (default: 30 minutes)
|
|
347
|
+
orc ui --fixtures # canned data, no project needed
|
|
348
|
+
orc ui --stop # shut this project's server down
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
| Panel | Shows | Can change |
|
|
352
|
+
|---|---|---|
|
|
353
|
+
| Overview | version, `orc doctor`, wiki tier, what is waiting โ plus **Worth doing**, one list of everything wanting a decision | โ |
|
|
354
|
+
| Settings | every config key, grouped, each with its own control | staged edits, applied together |
|
|
355
|
+
| Runs | run history as an accordion: a row opens in place into state-of-play, resume prompt, checkpoint, trace tail | โ |
|
|
356
|
+
| **Knowledge** | **five tabs**: the wiki's tier AND its **contents** (every doc, what it covers, how often it is read), coverage against your tracked files, the code patterns with the conflicts the codifier flagged, repair memory with a **preview-then-apply** prune, and a read-only view of the linked repos | `wiki sync`, `gotcha prune` |
|
|
357
|
+
| Stats | lane and agent usage, downgrades, and a **Cost** tab whose stacked bar keeps cache-read visible | โ |
|
|
358
|
+
| Flow | the compiled DIY flow, its gate, and a stepper of every phase in order | `diy set`, `diy compile`, presets |
|
|
359
|
+
| Crosslink | **Design** (the boundary as a graph) and **Settings** (each peer's freshness) | `crosslink add` / `remove` |
|
|
360
|
+
| Promises ยท Boundary ยท Self-serve | the pact ledger, the boundary cards, and the surfaces a non-developer can change | `pact check`, `pact sync`, `handoff set` |
|
|
361
|
+
| **Docs** | every `/orc-doc` document as a **ribbon** โ one block per section, sized by its length and coloured by its state โ plus the section files with their sub-parts, the wave strip, the lint health card and the wave preview | `doc compile` ยท `doc migrate` |
|
|
362
|
+
| **Mocked Skill Use** | every mocked run that ships with ORC, grouped and searchable, with a reading pane | โ |
|
|
363
|
+
| Learn | the `orc onboarding` walkthrough, one section at a time | โ |
|
|
364
|
+
| Experiment | every lane with a copy button; opens a Claude session in a terminal | โ |
|
|
365
|
+
| Maintenance | `update`, `update --prune`, `doctor --fix`, `upgrade` | preview, then apply |
|
|
366
|
+
|
|
367
|
+
- **The panel *is* the CLI.** It reads `orc <command> --json` and shells the real
|
|
368
|
+
command for every write, so it cannot drift from the CLI โ it has no second
|
|
369
|
+
copy of anything.
|
|
370
|
+
- **A free action gets a button. A paid action gets a command to copy.**
|
|
371
|
+
- **Nothing is automatic**, and a prune names **every** file. A count is not
|
|
372
|
+
consent.
|
|
373
|
+
- **Treated as a write surface**: loopback only, a fresh token per launch, a
|
|
374
|
+
Host-header check against DNS rebinding, no CORS, POST-only mutations.
|
|
375
|
+
- **Project-scoped, no `--global` config.** If a global install exists that could
|
|
376
|
+
win skill resolution, every page carries a banner. It reports that; it never
|
|
377
|
+
edits global config.
|
|
378
|
+
- **English and Indonesian.** Only the panel's own words are translated โ config
|
|
379
|
+
keys, model ids, paths, commands and doctor messages are printed exactly as the
|
|
380
|
+
CLI wrote them, because a translated config key is a key that does not exist.
|
|
381
|
+
|
|
382
|
+
Zero dependencies, zero build step: `node:http`, plain JavaScript, hand-written
|
|
383
|
+
CSS.
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## How the model is picked
|
|
388
|
+
|
|
389
|
+
Each task is scored 0โ100 by **arithmetic, not judgement**: the planner reports
|
|
390
|
+
facets (breadth, novelty, logic, test surface, cited risk, uncertainty) and a
|
|
391
|
+
fixed published formula turns them into a number. A cited risk forces a floor of
|
|
392
|
+
70. The score maps through a published table to a **named, model-pinned agent**,
|
|
393
|
+
so what ran is inspectable rather than requested in prose.
|
|
394
|
+
|
|
395
|
+
> **The rule that catches everyone:** a subagent's model can never be higher than
|
|
396
|
+
> your main session's. Run your session on Opus 5.
|
|
397
|
+
|
|
398
|
+
**Full detail โ the bands, `opus5_only`, and the tier guard `orc init` installs:
|
|
399
|
+
[guides/model-selection.md](guides/model-selection.md).**
|
|
400
|
+
|
|
401
|
+
---
|
|
402
|
+
|
|
403
|
+
## Configuration
|
|
404
|
+
|
|
405
|
+
Settings are edited with the **`orc config` CLI** โ deterministic terminal I/O,
|
|
406
|
+
so it costs **zero model tokens**.
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
orc config # interactive menu
|
|
410
|
+
orc config list # the effective config
|
|
411
|
+
orc config recommend # read this repo, suggest ONE profile, with reasons
|
|
412
|
+
orc config profile paranoid
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
Your changes live in `.claude/orc.config.yaml`, which `orc update` never
|
|
416
|
+
clobbers. `orc ui` โธ Settings edits the same keys through the same validators.
|
|
417
|
+
|
|
418
|
+
**Every key, with defaults and what each one does:
|
|
419
|
+
[guides/configuration.md](guides/configuration.md).**
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## What is inside the package
|
|
424
|
+
|
|
425
|
+
```
|
|
426
|
+
templates/
|
|
427
|
+
โโโ skills/ 29 skills โ the lanes above, plus the ones with no command of
|
|
428
|
+
โ their own: context-combiner, orc-advisor, orc-judge,
|
|
429
|
+
โ orc-analyze-mini, and _shared/ (cross-lane contract prose)
|
|
430
|
+
โโโ commands/ 27 slash commands
|
|
431
|
+
โโโ hooks/ effort guard (PreToolUse) ยท statusline warning ยท behavior trace
|
|
432
|
+
โโโ agents/ 40 model-pinned subagents + MODEL-MAPPING.md
|
|
433
|
+
bin/cli.js installer, config editor, flow composer, run-state reader, and
|
|
434
|
+
the deterministic half of every lane. Every read speaks --json
|
|
435
|
+
bin/webui/ `orc ui` โ the local control panel: css/ + js/ + i18n/<lang>/ +
|
|
436
|
+
fixtures/, one file per layer and per panel. Zero deps, no build step
|
|
437
|
+
bin/mockrun-catalog.js the mocked-run catalogue (derived from the files on disk)
|
|
438
|
+
mock-run/ the mocked runs themselves โ start at INDEX.md
|
|
439
|
+
guides/ configuration ยท model selection ยท documents ยท knowledge reads ยท other AI models
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
The `orc` skill is a thin **spine**: it loads a reference or a subskill only when
|
|
443
|
+
that phase actually runs, so a small task never pays for the machinery of a big
|
|
444
|
+
one.
|
|
445
|
+
|
|
446
|
+
---
|
|
447
|
+
|
|
448
|
+
## Longer guides
|
|
449
|
+
|
|
450
|
+
Some lanes ship a full how-to next to the skill, in plain language:
|
|
451
|
+
|
|
452
|
+
| Guide | Read it when |
|
|
453
|
+
|---|---|
|
|
454
|
+
| [ORC-QUICK](templates/skills/orc-quick/README.md) | you want the quick lane's complete worked runs |
|
|
455
|
+
| [ORC-DIY](templates/skills/orc-diy/README.md) | you want to compose your own lane |
|
|
456
|
+
| [ORC-WIKI](templates/skills/orc-wiki/README.md) | you want the knowledge base, and cross-repo crosslink setup |
|
|
457
|
+
| [ORC-PR-SETUP](templates/skills/orc-pr-setup/README.md) | you want to split a big change into stacked PRs |
|
|
458
|
+
| [ORC-PR-DRIVER](templates/skills/orc-pr-driver/README.md) | you have a stack plan and want to build, submit and merge it |
|
|
459
|
+
| [Configuration](guides/configuration.md) ยท [Model selection](guides/model-selection.md) | you want every key, or the scoring bands |
|
|
460
|
+
| [Other AI models](guides/extra-models.md) | you want part of the ladder to run somewhere other than Claude |
|
|
461
|
+
|
|
462
|
+
Every skill also ships its own `SKILL.md` and `references/`. The guides above are
|
|
463
|
+
the human-facing versions.
|
|
464
|
+
|
|
465
|
+
---
|
|
466
|
+
|
|
467
|
+
## Eval status
|
|
468
|
+
|
|
469
|
+
The constellation is graded **end to end**, not file by file: one executable
|
|
470
|
+
spec per lane, run against a sandboxed Express fixture, graded from on-disk
|
|
471
|
+
evidence โ behavior traces, run folders and artifacts.
|
|
472
|
+
|
|
473
|
+
The last full round was the **30-eval suite against the v0.34.0 payload**: 25
|
|
474
|
+
filled result files and 38 trace files, with 5 evals never graded and 2 only
|
|
475
|
+
partly graded โ all named in the report. Everything found there was either fixed
|
|
476
|
+
in a later release or is still listed. Read it as a record of that round, not as
|
|
477
|
+
a current audit: [EVAL-REPORT.md](EVAL-REPORT.md).
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
## Design principles
|
|
482
|
+
|
|
483
|
+
- **Never implement at the top.** The orchestrator coordinates; scored subagents
|
|
484
|
+
do the work.
|
|
485
|
+
- **Bound the scope before parallelizing.** A misunderstanding is cheap to fix
|
|
486
|
+
before five agents build on it.
|
|
487
|
+
- **Disk over memory.** Every pause is a clean resume point.
|
|
488
|
+
- **Pinned, inspectable models.** Named agents, models in frontmatter.
|
|
489
|
+
- **Your codebase wins.** Learned patterns defer to your project; only security
|
|
490
|
+
and correctness invariants are non-negotiable.
|
|
491
|
+
- **Additive knowledge.** The wiki improves planning when it is there and costs
|
|
492
|
+
nothing when it is not.
|
|
493
|
+
- **Say what you do not know.** `UNCHECKABLE`, `no card`, `insufficient history`
|
|
494
|
+
are real answers. A confident guess is worse than an honest gap.
|
|
495
|
+
|
|
496
|
+
---
|
|
497
|
+
|
|
498
|
+
## Changelog
|
|
499
|
+
|
|
500
|
+
**Full history: [CHANGELOG.md](CHANGELOG.md)** โ or `orc changelog`, which prints
|
|
501
|
+
only what is newer than the version you have.
|
|
502
|
+
|
|
503
|
+
### v0.56.0 - a rename moved the command, and nobody could reach the fix _(2026-08-27)_
|
|
504
|
+
|
|
505
|
+
**READ THIS FIRST IF YOUR `orc upgrade` IS FAILING.** On a version before
|
|
506
|
+
v0.56.0, this release cannot install itself - your `orc upgrade` is the OLD one.
|
|
507
|
+
Run these three lines once, by hand:
|
|
508
|
+
|
|
509
|
+
- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
|
|
510
|
+
- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
|
|
511
|
+
- **Step 3 - re-apply it to your project:** `orc update` (add `--global` to also
|
|
512
|
+
refresh `~/.claude`)
|
|
513
|
+
|
|
514
|
+
Then `orc version` should print 0.56.0 or newer. Your `.claude/` and your
|
|
515
|
+
`orc.config.yaml` are untouched. **Do not use `npm i -g -f`.**
|
|
516
|
+
|
|
517
|
+
**The package moved from the unscoped `orc` to `@azure-id/orc`, and every
|
|
518
|
+
upgrade path in the field died at once.** Both names declare the same `orc` bin,
|
|
519
|
+
and npm will not link it for the new package while the old one owns it - so the
|
|
520
|
+
tarball, the `github:` spec and the registry all failed with the same `EEXIST`
|
|
521
|
+
on the command file. It is a FILE conflict, not a source problem, which is why
|
|
522
|
+
changing sources never helped and `npm i -g -f` was the only thing that worked.
|
|
523
|
+
|
|
524
|
+
- **`orc upgrade` evicts the legacy package BEFORE trying any source**, because
|
|
525
|
+
the collision fails every source identically. Announced, never silent.
|
|
526
|
+
Detection is by OWNERSHIP - a package that does not declare the `orc` bin is
|
|
527
|
+
never touched.
|
|
528
|
+
- **The npm registry is tried first**, then the tarball, then the `github:` spec.
|
|
529
|
+
`freshCliPath()` now resolves the SCOPED directory, so step 2 stops re-applying
|
|
530
|
+
the templates step 1 just superseded.
|
|
531
|
+
- **`--force` is kept for the one case it fits** - an orphaned command file no
|
|
532
|
+
package owns - and never for an unrelated `EEXIST`.
|
|
533
|
+
- **`orc doctor` reports `legacy-global-package` by name.** Not `--fix`-able on
|
|
534
|
+
purpose: `--fix` is scoped to this project's `.claude/`.
|
|
535
|
+
- **A CAUTION at the top of this README** carries the one-time manual fix, since
|
|
536
|
+
anyone still on the old package does not have this code yet.
|
|
537
|
+
|
|
538
|
+
### v0.55.2 - a gate that is never probed is a gate that is always off _(2026-08-27)_
|
|
539
|
+
|
|
540
|
+
**`/orc-quick` and `/orc-fast` documented the foreign-worker option and then
|
|
541
|
+
never went and looked for it.** Both carried the whole `orc extra` slot contract
|
|
542
|
+
but neither preflight ever ran the probe that answers whether a position is
|
|
543
|
+
held, so an armed `extra_enabled` plus a slot row still offered only the shipped
|
|
544
|
+
Claude executors.
|
|
545
|
+
|
|
546
|
+
- **orc-quick Q0 gains one PROBE** - `orc extra resolve --slot quick-executor
|
|
547
|
+
--json`, the single exception to "read no other key" - so the menu can render
|
|
548
|
+
line 3. Still an option: never a default, never sticky.
|
|
549
|
+
- **orc-fast F0 gains gate `d`** - `orc extra resolve --slot fast-executor
|
|
550
|
+
--json` - and prints the P0 `extra:` line where the prose always said it
|
|
551
|
+
would, naming the agent it displaces.
|
|
552
|
+
- **`/orc-doc` was never affected**: `orc doc next` resolves its targets in the
|
|
553
|
+
CLI, which is the shape the other two now borrow.
|
|
554
|
+
|
|
555
|
+
### v0.55.1 โ ORC is on npm _(2026-08-27)_
|
|
556
|
+
|
|
557
|
+
**ORC is published as [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc).**
|
|
558
|
+
The GitHub tarball still works and nothing about the payload changed โ this is
|
|
559
|
+
the install path getting a name.
|
|
560
|
+
|
|
561
|
+
- **`npm i -g @azure-id/orc`** is the install, and
|
|
562
|
+
**`npm i -g @azure-id/orc@latest`** is the update. `orc upgrade` already did
|
|
563
|
+
both steps for you and continues to; `--from @azure-id/orc` names npm
|
|
564
|
+
explicitly.
|
|
565
|
+
- **The GitHub tarball is now the fallback**, not the headline โ it is kept in
|
|
566
|
+
the Quick start behind a fold for forks and for anyone pinning a branch.
|
|
567
|
+
|
|
568
|
+
### v0.55.0 โ a score is what a band needs, and four lanes do not have one _(2026-08-26)_
|
|
569
|
+
|
|
570
|
+
**`/orc-quick`, `/orc-fast`, `/orc-doc` and `/orc-wiki` pin an agent to a
|
|
571
|
+
position instead of scoring a task. `orc extra` routed them by reading that
|
|
572
|
+
agent's score band โ arithmetic on a number nobody chose. It was wrong twice and
|
|
573
|
+
dead once.**
|
|
574
|
+
|
|
575
|
+
- **`orc extra role` holds six POSITIONS** โ `quick-executor` ยท `fast-executor` ยท
|
|
576
|
+
`doc-writer` ยท `doc-checker` ยท `wiki-scanner-deep` ยท `wiki-scanner-light`. One
|
|
577
|
+
connection and one model each, and a row's presence is the arming. All six are
|
|
578
|
+
always listed: an unrouted one keeps its slot and reads as the Claude agent it
|
|
579
|
+
falls back to.
|
|
580
|
+
- **`orc extra resolve --slot` never touches a band**, and the Claude answer it
|
|
581
|
+
carries is a pinned NAME rather than an interval. Nine hold-backs, each named.
|
|
582
|
+
- **Precedence, one sentence:** extra decides *whether* a Claude agent runs at
|
|
583
|
+
all; `opus5_only` and the score tables only decide *which* one runs where extra
|
|
584
|
+
did not take it. Under a taken position `opus5_only` is not consulted โ and it
|
|
585
|
+
stays fully live for every position with no row.
|
|
586
|
+
- **The bridge accepts a slot** (`band` becomes `slot:<slot>`, so cost reporting
|
|
587
|
+
splits per position for free) with **zero new engines, zero new dispatch paths
|
|
588
|
+
and zero new agents**. A doc checker now resolves its OWN position, `/orc-wiki`
|
|
589
|
+
can route at all, and `/orc-quick` gets a THIRD OPTION on its menu โ never a
|
|
590
|
+
default, never sticky, re-asked after a failure.
|
|
591
|
+
- **A second ladder in `orc ui โธ Extra โธ Routing`**, and **zero config keys
|
|
592
|
+
added**.
|
|
593
|
+
|
|
594
|
+
Before that: **v0.54.0 โ a failed dispatch is a POSITION, not a blank page**,
|
|
595
|
+
**v0.53.4 โ the reload that dropped its own token**, **v0.53.3 โ the key it never
|
|
596
|
+
sent**, **v0.53.2 โ the cost that was paid and never written down**, and
|
|
597
|
+
**v0.53.1 โ "up to date" now names what it checked**.
|
|
598
|
+
[Read them in the changelog](CHANGELOG.md).
|
|
599
|
+
|
|
600
|
+
---
|
|
601
|
+
|
|
602
|
+
## Requirements
|
|
603
|
+
|
|
604
|
+
- **Claude Code** โ it reads the skills, commands and agents.
|
|
605
|
+
- **Node 18+** โ for the installer only. The skills themselves have zero
|
|
606
|
+
dependencies.
|
|
607
|
+
|
|
608
|
+
## License
|
|
609
|
+
|
|
610
|
+
MIT โ the `license` field in `package.json` is the canonical statement.
|