orchestrix-skills 0.2.0 → 0.4.0

package/README.md

@@ -15,11 +15,15 @@ hosting, and team features are the premium layer — see below.
 intent
   └─ orchestrate (root: warm context, wires skills by output→input, enforces gates)
        ├─ brainstorm ──(needs facts?)─→ research
+       ├─ (existing repo?) ──→ map-codebase (brownfield entry: evidence-based map → registry)
        ├─ (has UI?) ──→ design-system (once) → design-ui
        ├─ (arch decision?) ──→ design-architecture
-       └─ draft-story → implement → run-tests → review-code → commit
-                                      ↑ verify         ↑ design-review (UI only)
-                                      (objective)      ↑ accept (batched)
+       ├─ draft-story → implement → run-tests → review-code → commit
+       │                              ↑ verify         ↑ design-review (UI only)
+       │                              (objective)      ↑ accept (batched)
+       ├─ (verify failing, cause unknown?) ──→ investigate (root cause → rework)
+       ├─ (runnable app?) ──→ smoke-test (drive real flows, evidence captured)
+       └─ (accepted + ship it?) ──→ deploy (inline gate, rollback-first)
 ```
 
 Human gates are front-loaded (planning = direction) and at the end (acceptance);

package/package.json

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

package/skills/deploy/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: deploy
+description: Use when an ACCEPTED deliverable must be shipped to a live environment. Never mid-run, never on unaccepted work.
+license: MIT
+allowed-tools: [Read, Bash]
+metadata:
+  contract:
+    inputs: [accepted_deliverable, target]
+    reads: [registry/deploy]
+    outputs: [deploy_report]
+    authority: "Run the project's DOCUMENTED deploy command for the named target, and its rollback. No infra provisioning, no DNS/billing/secret changes, no undocumented deploy paths."
+    verify: "A real request against the LIVE target succeeds post-deploy (the deploy tool's own 'success' does not count), and one core flow responds correctly."
+    accept:
+      when: "always — deploying is irreversible and user-facing."
+      timing: inline
+---
+
+# Deploy (Ship Accepted Work, With a Way Back)
+
+The most dangerous skill in the graph. Everything here is designed around two
+facts: deploys are user-facing, and the only safe deploy is one you can undo.
+
+**Core principle:** No rollback plan, no deploy. If you cannot state the exact
+command that undoes this deploy, you are not ready to run the one that does it.
+
+## Preconditions — ALL must hold, verify each now
+
+1. **The work is accepted.** Final acceptance happened; you are not deploying
+   to "see if it works" (that is `smoke-test`'s job, locally).
+2. **The tree is clean and tested.** `git status` clean; `run-tests` green on
+   the exact commit being shipped (fresh run, not remembered).
+3. **The deploy method is documented** in `registry/deploy` (or the project's
+   own deploy config/scripts). Not documented → STOP and ask the human how this
+   project ships. NEVER guess a deploy path — a guessed deploy against the
+   wrong target is the worst failure this graph can produce.
+4. **The target is unambiguous.** "Deploy" without a named target defaults to
+   asking, not to production.
+
+## Process
+
+1. **Write the rollback plan first.** Record: the currently-live version
+   identifier (commit/tag/deployment id) and the exact rollback command.
+   Put both in the report BEFORE deploying.
+2. **Inline human gate (this skill's accept).** Present: target, version to
+   ship, one-line change summary, rollback command. Deploy only on explicit
+   sign-off. This gate cannot be batched or deferred.
+3. **Deploy** with the documented command. Capture the full output to
+   `.orchestrate/verify/deploy-<target>.log`.
+4. **Post-verify against the LIVE target.** A real HTTP request (or the
+   platform equivalent) to the deployed URL: correct status AND expected
+   content, plus one core flow. The deploy tool saying "success" is step 3,
+   not step 4.
+5. **On post-verify failure: roll back immediately** with the recorded
+   command, re-verify the old version is live again, and report honestly.
+   A failed deploy cleanly rolled back is a good outcome; a broken prod
+   left up while you debug is not.
+
+## Output: `deploy_report`
+
+```markdown
+# Deploy — <target>
+
+Shipped: <version/commit> (previous live: <version>)
+Command: <documented command used>
+Post-verify: <request + result> — passed/failed
+Rollback: <command> — standing by | EXECUTED at <time>, old version re-verified live
+Log: .orchestrate/verify/deploy-<target>.log
+```
+
+## Red flags — stop
+
+- Deploying work that has not passed final acceptance
+- Guessing the deploy method because `registry/deploy` is empty
+- No recorded rollback command before deploying
+- Treating the deploy tool's success message as proof the site works
+- An ambiguous target resolved to production by default
+- Debugging a broken deploy IN production instead of rolling back first
+
+## Done
+
+Live target verified serving the new version (or cleanly rolled back), report
+written. Durable facts learned (the deploy command, the health URL) go back to
+`registry/deploy` via the metabolism rules.

package/skills/investigate/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: investigate
+description: Use when something is broken and the CAUSE is unknown — a repeatedly failing verify, a bug report, a regression — before any fix is attempted.
+license: MIT
+allowed-tools: [Read, Bash, Grep, Glob]
+metadata:
+  contract:
+    inputs: [symptom, context?, prior_attempts?]
+    reads: [registry/architecture, taste/coding-standards]
+    outputs: [root_cause_report]
+    authority: "Read code and run diagnostics/reproductions. Temporary instrumentation is allowed but MUST be reverted before finishing. No fixes — the fix belongs to a re-dispatched implement."
+    verify: "The report contains a reproduction command that fails, and a mechanism that explains every observed symptom (not just the loudest one)."
+    accept:
+      when: "never — informational; it feeds the rework loop."
+      timing: deferred
+---
+
+# Investigate (Root Cause Before Any Fix)
+
+Debugging is not "try changes until it passes". It is locating the mechanism.
+
+**Core principle:** A fix you cannot explain mechanistically is not a fix — it
+is a coincidence that will regress.
+
+## The Iron Law
+
+```
+NO FIX WITHOUT A ROOT CAUSE STATED AS:
+"X happens BECAUSE Y — evidenced by Z (something I observed this session)"
+```
+
+## Process
+
+1. **Reproduce.** Find the exact command/steps that show the symptom, run them,
+   capture the output verbatim. Read the error LITERALLY — the message usually
+   says what is wrong, not what you assume is wrong. Cannot reproduce → that IS
+   the finding (report the conditions tried; do not "fix" what you cannot see).
+2. **Localize.** Shrink the search space with evidence, not intuition:
+   - `git log`/`git bisect` when it used to work — what changed?
+   - Binary-search the pipeline: add temporary instrumentation (prints/asserts)
+     at midpoints to find where good state becomes bad state.
+   - Minimize the reproduction — smallest input that still fails.
+3. **Hypothesize and FALSIFY.** For each hypothesis, design the observation
+   that would DISPROVE it, then run it. A hypothesis you only sought
+   confirmation for is not tested. Two failed rounds on the same theory →
+   the bug is in an assumption one level deeper (the config, the framework
+   contract, the data, the environment) — widen, don't re-try harder.
+4. **State the root cause** in the iron-law form, plus:
+   - the minimal fix scope (which file/function, what change class),
+   - the regression test that would have caught it,
+   - any OTHER symptoms this mechanism predicts (check them — a mechanism
+     that doesn't explain all symptoms is incomplete).
+5. **Revert your instrumentation.** `git diff` must be clean when you finish.
+
+## Output: `root_cause_report`
+
+```markdown
+# Root cause — <symptom, one line>
+
+## Reproduction — exact command; fails with <output tail>.
+## Mechanism — X happens because Y. Evidence: Z (file:line / captured output).
+## Fix scope — <file(s)>, <change class>. Explicitly NOT needed: <what a shotgun fix would have touched>.
+## Regression test — <the test to add so this cannot silently return>.
+## Ruled out — <hypotheses falsified and how> (saves the next person re-walking them).
+```
+
+## Red flags — stop and re-localize
+
+- "Probably" / "might be" in the mechanism line
+- A symptom fix: retry loops, sleeps, broad try/catch, widened types — with no
+  mechanism behind it
+- Changing several things at once and observing "it passes now"
+- A mechanism that explains one symptom but not the others
+- Finishing with instrumentation still in the diff
+
+## Done
+
+Report written; reproduction demonstrably fails; diff clean. The orchestrator
+re-dispatches `implement` with this report as `qa_feedback` — same capability,
+now with a target instead of a guess.

package/skills/map-codebase/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: map-codebase
+description: Use when entering an EXISTING codebase (brownfield) before designing or changing anything — build an evidence-based map of its architecture, conventions, and hazards.
+license: MIT
+allowed-tools: [Read, Bash, Grep, Glob]
+metadata:
+  contract:
+    inputs: [repo_path, focus?]
+    reads: []
+    outputs: [codebase_map, registry_updates]
+    authority: "Read-only on source; non-mutating commands only (ls, grep, git log, test discovery). Writes go ONLY to knowledge/registry/*."
+    verify: "Every architectural claim in the map cites a file path you actually read; the traced flows exist in code, not in the README."
+    accept:
+      when: "never — informational; it feeds design and implement."
+      timing: deferred
+---
+
+# Map Codebase (Brownfield Entry)
+
+Greenfield runs start from intent; brownfield runs start from SOMEONE ELSE'S
+decisions. Changing code you haven't mapped produces changes that fight the
+codebase — wrong layer, wrong convention, duplicated machinery.
+
+**Core principle:** The map comes from reading code, not from directory names
+or the README. A README describes what the project wishes it were; `git log`
+and the source describe what it is.
+
+## Process
+
+1. **Inventory.** Layout, manifests (`package.json`/`pyproject`/`go.mod`…),
+   scripts, CI config, generated/vendored dirs (mark them DO-NOT-EDIT).
+2. **Trace one or two REAL flows end to end** (guided by `focus` if given):
+   entry point → routing/dispatch → business logic → persistence/IO. Read the
+   actual files; record the chain as `file:symbol → file:symbol`. This step is
+   what separates a map from a guess.
+3. **Extract conventions from evidence** — for each, cite the example file you
+   derived it from: naming, module boundaries, error handling style, test
+   location and framework, how config/env is read, commit message style.
+4. **Hazards.** Migrations and how they run; generated code and what generates
+   it; global state; areas with no test coverage; anything `git log` shows as
+   churn-heavy (bug-prone) or untouched-for-years (fragile assumptions).
+5. **Write back to `knowledge/registry/`** following the metabolism governance
+   in `orchestrate` (read-before-write, update-don't-append, facts only):
+   - `registry/architecture.md` — the traced structure
+   - `registry/conventions.md` — the evidenced conventions
+   Registry holds FACTS about this codebase. Opinions and preferences belong
+   in `taste/*`, and only via a human correction — not from this skill.
+
+## Output: `codebase_map`
+
+```markdown
+# Codebase map — <repo> @ <commit>
+
+## Shape — <stack, top-level layout, one paragraph>
+## Traced flows
+- <flow>: entry `a.ts:handler` → `b.ts:service` → `c.ts:repo` → <storage>
+## Conventions (evidence-cited)
+- <convention> — see <file>
+## Hazards
+- <hazard> — <why it bites> — <file/dir>
+## Where a change like "<focus>" belongs — <layer/files>, following <convention>
+```
+
+## Red flags — stop
+
+- Architecture described from folder names without opening the files
+- Repeating a README/document claim without spot-checking it in code
+- A "convention" cited from zero examples
+- Writing preferences/judgments into `registry/` (facts only)
+- Editing anything outside `knowledge/`
+
+## Done
+
+Map written with citations; registry updated. Downstream `design-architecture`
+and `implement` read the registry and MUST follow the documented conventions —
+that is the point of having mapped them.

package/skills/orchestrate/SKILL.md

@@ -4,7 +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: 2
+  version: 4
   contract:
     inputs: [intent, constraints?]
     reads: [skill-registry, taste/*]
@@ -46,9 +46,20 @@ no step above intent.
    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).** Run the skill's `verify`. If it fails, re-dispatch the
-   **same** skill with the failure as feedback (see Rework). If it passes,
-   continue.
+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.
@@ -66,17 +77,53 @@ 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.
 
-## Metabolism
+**Rework without understanding is a coin flip.** If a verify failure's CAUSE
+is not understood after the first failed attempt, dispatch `investigate` before
+spending the next attempt — its `root_cause_report` becomes the re-dispatch's
+`qa_feedback`. An attempt aimed at a stated mechanism converges; an attempt
+aimed at a symptom re-rolls the dice.
+
+**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 — governed writeback
 
 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.
+tone"), fold it back into `taste/*` (preferences) or `registry/*` (facts about
+this codebase), so the next run starts smarter. The run teaches the
+organization — but memory rots without curation, so writeback is GOVERNED:
+
+1. **Read before write.** Open the target file first. An existing entry on the
+   same topic gets UPDATED in place — never append a near-duplicate.
+2. **Contradiction = replacement.** A correction that contradicts an existing
+   entry REPLACES it (add a short `supersedes: <old rule> (<date>)` note).
+   Never leave both standing — two contradictory rules poison every later run
+   that reads them.
+3. **Durable preferences only.** Taste holds style/architecture/process
+   preferences that apply to FUTURE runs. One-off task facts, transient state,
+   and anything the repo or ledger already records do not belong there.
+4. **One lesson per entry** — imperative phrasing, a one-line why, and a date.
+5. **Size bound: ~100 lines per file.** If a write would push past it,
+   consolidate in the same edit (merge near-duplicates, drop obsolete entries)
+   — never blind-append to a bloated file.
+6. **The human sees the diff.** taste/registry changes made during a run are
+   part of final acceptance: present what changed and why, so a bad lesson can
+   be vetoed before it contaminates future runs.
+
+`taste/*` vs `registry/*`: taste is HOW we prefer things done (opinions,
+overridable); registry is WHAT is true of this project (facts, verifiable).
+A correction usually lands in taste; a discovered fact (the deploy command,
+the test runner) lands in registry.
 
 ## The ledger (`.orchestrate/ledger.jsonl`)
 
@@ -97,8 +144,9 @@ Events and when to write them:
 | `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 (the verify output file or a one-line result); a `done` with no
-evidence is a false claim.
+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)
 
@@ -117,4 +165,8 @@ evidence is a false claim.
 - 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)
+- A second rework attempt with no `investigate` when the failure isn't understood
+- Appending to `taste/*` without reading it first (duplicate/contradiction risk)
 - Marking the run complete without every step's `verify` evidence

package/skills/smoke-test/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: smoke-test
+description: Use when the deliverable is a runnable app or service and its real user flows must be proven working from the OUTSIDE (browser/HTTP/CLI) before acceptance — unit tests passing is not that proof.
+license: MIT
+allowed-tools: [Read, Bash, Grep, Glob]
+metadata:
+  contract:
+    inputs: [run_instructions, flows, qa_feedback?]
+    reads: [registry/app]
+    outputs: [smoke_report, verify_evidence]
+    authority: "Start and stop the app locally; drive it via browser automation, HTTP, or CLI. Read-only on source. No deploy, no external spend, no mutations outside the app's own local state."
+    verify: "self — this skill PRODUCES the acceptance evidence; every flow verdict points at a captured artifact."
+    accept:
+      when: "never — the evidence feeds final acceptance; it does not replace it."
+      timing: deferred
+---
+
+# Smoke Test (Prove It Works From the Outside)
+
+Unit tests prove functions; a smoke test proves the PRODUCT. Launch the real
+app and walk the real flows the user will walk.
+
+**Core principle:** A flow is "passed" only when you drove it yourself and
+captured the evidence. "The tests are green so it probably works" is a claim,
+not a smoke test.
+
+## The Iron Law
+
+```
+UNTESTED IS NOT PASSED. Every flow ends in exactly one of:
+passed (with evidence) | failed (with evidence) | untested (with the reason)
+```
+
+## Process
+
+1. **Discover how to run it.** `registry/app` first; else the project's
+   manifest (`package.json` scripts, `Makefile`, `README`). If the launch
+   method is genuinely undocumented and unguessable, report `untested:
+   cannot launch` — do not invent a server.
+2. **Launch in the background, capture logs.** Redirect stdout/stderr to
+   `.orchestrate/verify/smoke-server.log`. Record the PID. Pick a free port if
+   configurable (avoid colliding with anything already running).
+3. **Wait for readiness, bounded.** Poll the health endpoint / port / ready
+   line for up to ~60s. Not ready → flow verdicts are `failed: app did not
+   start`, attach the server log, skip to cleanup.
+4. **Exercise EVERY listed flow** with the best driver available, in order of
+   fidelity:
+   - **Browser automation** (a Playwright/Chrome MCP tool, if available in
+     this session) — for UI flows: navigate, interact, assert on rendered
+     state, screenshot.
+   - **HTTP** (`curl`) — assert status code AND response content (a 200
+     serving an error page is a fail; check for a string the flow implies).
+   - **CLI** — invoke the command, assert exit code and output.
+   Use the highest-fidelity driver the flow needs: an interactive UI flow
+   "verified" by curling `/` is `untested`, not `passed`.
+5. **Capture evidence per flow** to `.orchestrate/verify/smoke-<flow-slug>.log`
+   (the exact command/steps + relevant output tail, or the screenshot path).
+6. **ALWAYS clean up** — kill the processes you started (and only those),
+   remove temp state you created. Cleanup runs even when flows fail.
+
+## Output: `smoke_report`
+
+```markdown
+# Smoke Report — <app> @ <commit>
+
+| Flow | Verdict | Evidence |
+|---|---|---|
+| signup happy path | passed | .orchestrate/verify/smoke-signup.log |
+| checkout | failed — 500 on POST /pay | .orchestrate/verify/smoke-checkout.log |
+| admin export | untested — needs OAuth I can't complete | (reason) |
+
+Server log: .orchestrate/verify/smoke-server.log
+Started/stopped: <pid(s)>, cleaned up: yes
+```
+
+## Red flags — stop
+
+- Reporting `passed` for a flow you did not drive
+- A UI flow "verified" with a single `curl /` status check
+- Conflating "the app is broken" with "my harness is broken" — say which
+- Leaving the server (or any process you spawned) running after the report
+- Only testing the happy path when `flows` lists error/edge flows
+
+## Done
+
+Every flow has a verdict + evidence artifact; processes cleaned up. `failed`
+and `untested` are honest, valid results — report them verbatim, never rounded
+up. The report feeds the orchestrator's verify gate and final acceptance.