orchestrix-skills 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
   "type": "module",
   "bin": {

package/skills/orchestrate/SKILL.md

@@ -4,6 +4,7 @@ description: Use when a goal must be delivered end-to-end by composing skills, w
 license: MIT
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
 metadata:
+  version: 3
   contract:
     inputs: [intent, constraints?]
     reads: [skill-registry, taste/*]
@@ -38,12 +39,27 @@ no step above intent.
 3. **Wire (emergent, not hardcoded).** Build the path by matching one skill's
    `outputs` to the next skill's `inputs`. Skills do not know each other; only
    you do. Do not assume a fixed pipeline — wire what this intent needs.
-4. **Dispatch one step.** Hand the skill exactly the `inputs` it declares, as
-   files. Run it as a fresh subagent for isolation. Choose the cheapest model
-   that can do the step.
-5. **Verify (gate).** Run the skill's `verify`. If it fails, re-dispatch the
-   **same** skill with the failure as feedback (see Rework). If it passes,
-   continue.
+4. **Dispatch.** Hand the skill exactly the `inputs` it declares, as files. Run
+   it as a fresh subagent for isolation. Choose the cheapest model that can do
+   the step. **Dispatch independent steps in PARALLEL** (whose `inputs` don't
+   depend on each other) — as concurrent FOREGROUND subagents awaited together in
+   the same turn, for speed. Keep dependent steps sequential. NEVER fire-and-forget
+   a background subagent and end the turn waiting to be woken — run foreground and
+   await; there is no reliable async wake.
+5. **Verify (gate) — executable, not prose.** Prove the skill's `verify` with a
+   REAL command you run yourself via Bash, and capture the proof:
+
+   ```
+   .orchestrate/verify/step-<n>-attempt-<k>.log   ← exact command + exit code + output tail
+   ```
+
+   The command comes from the step's nature (test runner, build, `git fsck`,
+   `test -f`, a curl against the running app …) — pick the one that would FAIL
+   if the claim were false. The subagent's own success report is NOT
+   verification. A prose-only verify is acceptable only when no command can
+   prove the claim (e.g. judging tone) — say so in the log file. If verify
+   fails, re-dispatch the **same** skill with the failure as feedback (see
+   Rework). If it passes, continue.
 6. **Accept (gate).** Apply the rule below. Then continue — do not pause to ask
    "should I keep going?" mid-run.
 7. **Repeat** 3–6 until the intent is fulfilled.
@@ -61,25 +77,52 @@ no step above intent.
 
 You are the teeth. The fields are only data; you enforce them.
 
-## Rework is a loop, not a skill
+## Rework is a loop, not a skill — and the loop is BOUNDED
 
 A failed `verify` or a `changes_requested` review is not a separate "fix" step.
 Re-dispatch the same skill with the feedback as an input (e.g. `qa_feedback`).
 Same capability, new input.
 
+**Hard cap: 3 attempts per step.** If a step's verify still fails on attempt 3,
+STOP the run — do not burn a 4th attempt. Write a `gate` event to the ledger
+(`{"e":"gate","kind":"rework_exhausted","question":"step <n> (<skill>) failed 3
+attempts: <one-line why>"}`), summarize the three failures for the human, and
+report AWAIT. A step that cannot pass its own verify after three tries needs a
+human decision (wrong approach, wrong spec, or wrong verify), not more tokens.
+
 ## Metabolism
 
 When the human corrects something at final acceptance ("not on-brand", "wrong
 tone"), write the correction back into the relevant `taste/*` knowledge base, so
 the next run reads the improved taste. The run teaches the organization.
 
+## The ledger (`.orchestrate/ledger.jsonl`)
+
+The ledger is the run's durable state — for YOU (recover after compaction or an
+interrupted session: trust it and `git log`, not memory) and for MACHINES (the
+platform renders it as live progress). It is append-only JSONL: one JSON event
+per line, appended with `Bash` (`echo '<json>' >> .orchestrate/ledger.jsonl`).
+Never rewrite or delete lines. Timestamps: `date -u +%FT%TZ`.
+
+Events and when to write them:
+
+| Event | When | Shape |
+| ----- | ---- | ----- |
+| `run_start` | right after binding intent | `{"e":"run_start","run":"r-<yyyymmdd>-<slug>","intent":"...","ts":"..."}` |
+| `plan` | after wiring the graph, and EVERY time the graph changes | `{"e":"plan","run":"...","steps":[{"n":1,"skill":"research","title":"..."}, …]}` — full current plan; latest `plan` line wins; steps may be added, never removed |
+| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed","attempt":1,"evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt` |
+| `gate` | when stopping at a human gate | `{"e":"gate","run":"...","kind":"inline_accept","question":"...","ts":"..."}` |
+| `run_end` | at delivery or abandonment | `{"e":"run_end","run":"...","result":"delivered\|paused\|abandoned","ts":"..."}` |
+
+A step recorded `done` is done — do not re-dispatch it. `evidence` on a `done`
+step is required and should be the step's verify log path
+(`.orchestrate/verify/step-<n>-attempt-<k>.log`); a `done` with no evidence is
+a false claim.
+
 ## Context discipline (stay lean)
 
 - **Files, not paste.** Move artifacts between steps as files. Never paste a
   step's full output into your context — it would be re-read every later turn.
-- **Ledger.** Append each finished step to a progress ledger file
-  (`.orchestrate/ledger.md`). After a compaction, trust the ledger and `git
-log`, not memory. A step recorded done is done — do not re-dispatch it.
 - **Cheapest model per step.** Mechanical step → cheap model. Judgment step →
   capable model. State the model explicitly on every dispatch.
 - **Keep your own context small.** You coordinate; the leaves do the heavy work.
@@ -91,4 +134,8 @@ log`, not memory. A step recorded done is done — do not re-dispatch it.
 - Hardcoding a fixed skill order instead of wiring outputs→inputs
 - Pasting a step's full output into your context instead of handing a file
 - Re-dispatching a step the ledger already marks done
+- Dispatching a step without first writing its `dispatched` ledger line
+- Ending a run without a `run_end` ledger line
+- Marking a step done on the subagent's say-so, without your own verify command
+- A 4th rework attempt on the same step (cap is 3 — stop and gate)
 - Marking the run complete without every step's `verify` evidence