orchestrix-skills 0.4.0 → 0.5.0

package/package.json

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

package/project-scaffold/core-config.yaml

@@ -12,7 +12,11 @@ work: # work products — skills WRITE these (outputs:), humans review at gates
   stories: docs/stories # <slug>.md (flat, origin tag)
   research: docs/research # research briefs
 
-runtime: .orchestrix/runtime # ledger + step handoff files (ephemeral, gitignored)
+# FIXED platform protocol — the orchestrate skill writes, and the platform polls,
+# `.orchestrate/ledger.jsonl` + `.orchestrate/verify/` at this literal path. It is
+# NOT a remappable namespace: changing it breaks live progress rendering. Listed
+# here for transparency only.
+runtime: .orchestrate # ledger + verify logs (ephemeral, gitignored)
 
 # Org-level cascade (shared taste/standards across many products) is intentionally
 # NOT enabled yet (YAGNI). When needed: add an `extends:` base that project paths

package/project-scaffold/knowledge/taste/coding-standards.md

@@ -1,16 +1,19 @@
 # taste/coding-standards
 
 Rules `implement` and `review-code` read as their taste slice. Terse rules, each
-with provenance. Not prose. Seed examples below — replace with this project's.
+with provenance. Not prose. Seed is empty — this is honest: no project
+preferences exist yet. Rows enter via human seeding (orchestrate's first-run
+preflight offers this) or the metabolism loop — never as unapproved defaults.
 
-| id            | rule                                                                | rationale                                  | source | added      | approved_by |
-| ------------- | ------------------------------------------------------------------- | ------------------------------------------ | ------ | ---------- | ----------- |
-| ts-strict     | TypeScript strict mode on; no `any` without an inline justification | Catches runtime errors at compile time     | human  | 2026-06-27 | dorayo      |
-| named-exports | Named exports only; no default exports                              | Refactor-safe imports, better autocomplete | human  | 2026-06-27 | dorayo      |
-| no-swallow    | Never swallow errors; handle or rethrow with context                | Silent failures are undebuggable           | human  | 2026-06-27 | dorayo      |
-| pure-io-split | Keep I/O at the edges; core logic pure and testable                 | Testability, fewer mocks                   | human  | 2026-06-27 | dorayo      |
+| id  | rule | rationale | source | added | approved_by |
+| --- | ---- | --------- | ------ | ----- | ----------- |
 
 <!--
+Row shape (copy per rule — every row needs real provenance):
+
+| ts-strict     | TypeScript strict mode on; no `any` without inline justification | Catches runtime errors at compile time     | human | <date> | <who> |
+| named-exports | Named exports only; no default exports                            | Refactor-safe imports, better autocomplete | human | <date> | <who> |
+
 Metabolism: when a human corrects taste at the accept gate, append or supersede a
 row here (source: <skill or human>, with date + approver). Supersede, don't
 delete — keep what the org learned visible.

package/skills/brainstorm/SKILL.md

@@ -29,8 +29,9 @@ but always presented and approved.
 
 ## Process
 
-1. **Explore context.** Read the relevant `knowledge/*` slices and existing
-   code before asking anything.
+1. **Explore context.** Read the relevant knowledge slices (`taste/*`,
+   `architecture/*`, `registry/*` — physical paths from `core-config.yaml`,
+   default under `knowledge/`) and existing code before asking anything.
 2. **Scope check first.** If the intent spans independent subsystems, say so and
    help decompose into sub-projects — each gets its own spec → stories → build.
    Don't refine details of something that should be split.

package/skills/draft-story/SKILL.md

@@ -7,8 +7,8 @@ metadata:
   contract:
     inputs: [requirement, context]
     reads: [taste/coding-standards, registry/api, registry/db, front-end-spec?]
-    outputs: [docs/stories/<slug>.md]
-    authority: "Write one flat story file at docs/stories/<slug>.md. No folders. No source code. No production. No spend."
+    outputs: [stories/<slug>.md]
+    authority: "Write one flat story file in the stories namespace (physical path from core-config.yaml; default docs/stories/). No folders. No source code. No production. No spend."
     verify: "Every requirement maps to at least one acceptance criterion; constraints are copied verbatim; no placeholders (no TBD/TODO/'handle edge cases')."
     accept:
       when: "Always — this output sets the direction the whole build rests on."
@@ -25,7 +25,8 @@ implement it without guessing.
 
 ## Output
 
-Write ONE flat Markdown file: `docs/stories/<slug>.md` — `<slug>` is a kebab
+Write ONE flat Markdown file in the stories namespace (physical path from
+`core-config.yaml`, default `docs/stories/`): `<slug>.md` — `<slug>` is a kebab
 handle from the title. No folders, no `epic.story` numbering. Produce exactly
 these sections (with frontmatter) and nothing more.
 
@@ -76,9 +77,9 @@ What this story deliberately does NOT do.
 ## Rules
 
 - **One story, one coherent deliverable.** If it spans independent subsystems,
-  split into separate stories — each its own `docs/stories/<slug>.md`, all
-  sharing the same `origin` so the set is queryable as one group.
-- **Flat, no hierarchy.** One file per story under `docs/stories/`. Grouping is
+  split into separate stories — each its own `<slug>.md` in the stories
+  namespace, all sharing the same `origin` so the set is queryable as one group.
+- **Flat, no hierarchy.** One file per story in the stories dir. Grouping is
   the `origin` field (a query the AI runs), never a folder. Order comes from
   Interfaces (dependencies), never from a number.
 - **No placeholders.** "Add validation", "handle errors", "TBD" are failures.
@@ -101,6 +102,7 @@ What this story deliberately does NOT do.
 
 ## Done
 
-Write `docs/stories/<slug>.md`. Hand off its path for direction confirmation
+Write the story file in the stories namespace. Hand off its path for direction
+confirmation
 (this skill's `accept` is `inline`): the human approves the direction, or sends
 it back, before `implement` begins.

package/skills/map-codebase/SKILL.md

@@ -8,7 +8,7 @@ metadata:
     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/*."
+    authority: "Read-only on source; non-mutating commands only (ls, grep, git log, test discovery). Writes go ONLY to the registry/* namespace (physical path from core-config.yaml; default 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."
@@ -39,8 +39,10 @@ and the source describe what it is.
 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):
+5. **Write back to the `registry/*` namespace** (physical path from
+   `core-config.yaml`; default `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
@@ -67,7 +69,7 @@ and the source describe what it is.
 - 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/`
+- Editing anything outside the `registry/*` namespace
 
 ## Done
 

package/skills/orchestrate/SKILL.md

@@ -4,10 +4,10 @@ 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: 4
+  version: 5
   contract:
     inputs: [intent, constraints?]
-    reads: [skill-registry, taste/*]
+    reads: [core-config, skill-registry, taste/*]
     outputs: [accepted_deliverable, run_ledger]
     authority: "Dispatch leaf skills, each within its own authority. Do not directly touch source, production, or spend — leaf skills do that, gated. Enforce every accept gate."
     verify: "Every dispatched skill's verify passed; final review is clean; all inline accepts were obtained."
@@ -32,14 +32,17 @@ no step above intent.
 ## The loop
 
 1. **Bind intent.** Read the human's goal and constraints. This is the only
-   place intent enters.
+   place intent enters. Then run the first-run preflight (below) before any
+   wiring.
 2. **Select.** Read the skill registry. Pick skills by their `description`
    (when-to-use). Load a skill's full `contract` only when it is a candidate —
    never load every contract at once.
 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.** Hand the skill exactly the `inputs` it declares, as files. Run
+4. **Dispatch.** Hand the skill exactly the `inputs` it declares, as files —
+   resolving each logical namespace it reads/writes to a physical path via
+   `core-config.yaml` (see Namespace resolution). 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
@@ -66,6 +69,49 @@ no step above intent.
 8. **Final acceptance.** Present the batched deferred accepts and a final review
    to the human, once. Apply corrections (see Metabolism), then deliver.
 
+## Namespace resolution (`core-config.yaml`)
+
+Skill contracts address knowledge and work products by **logical namespace**
+(`taste/*`, `architecture/*`, `registry/*`, `specs/*`, `stories/*`,
+`research/*`), never by physical path. At run start, read `core-config.yaml`
+once and build the logical→physical map. When you dispatch a skill, resolve
+every namespace in its `reads:` / `outputs:` / `updates:` to a real path via
+that map, and hand the resolved files as its inputs. If `core-config.yaml` is
+absent, fall back to the scaffold defaults (`knowledge/taste`,
+`knowledge/architecture`, `knowledge/registry`, `docs/specs`, `docs/stories`,
+`docs/research`).
+
+This is what makes brownfield work: a project keeps its brain wherever it
+already lives, the mapping changes, the skills do not.
+
+**Exception — the ledger/verify path is a FIXED platform protocol, not a
+namespace.** Always write to `.orchestrate/ledger.jsonl` and
+`.orchestrate/verify/…` literally. The platform polls that exact path to render
+live progress; it is NOT resolved through `core-config.yaml` and must not be
+remapped.
+
+## First-run preflight (brownfield guard)
+
+Emergent wiring alone can silently skip brownfield entry. So after binding
+intent, run two DETERMINISTIC checks (cheap: one `ls`/`test -d` each on the
+resolved paths):
+
+1. **Empty registry + existing code → map-codebase is MANDATORY.** If the
+   resolved `registry/*` namespace is empty or missing AND the repo already
+   contains source code, wire `map-codebase` before any design or build skill.
+   This is a hard rule, not a description-match: building on an unmapped
+   codebase produces changes that fight it.
+2. **Empty taste → surface it once.** If the resolved `taste/*` namespace is
+   empty — no project-specific entries; file headers, shape comments, and
+   unedited scaffold examples do NOT count — tell the human at the front gate: the brain has no preferences yet;
+   offer to draft `taste/coding-standards` from existing material (CLAUDE.md,
+   lint configs, review conventions) for their approval. Never seed taste
+   without human sign-off (opinions enter the brain only through a human —
+   same rule as Metabolism). If they decline, proceed with defaults and do not
+   ask again this run.
+
+Both checks are per-run and idempotent: a populated brain makes them no-ops.
+
 ## Accept gate
 
 | Skill's `accept.timing` | Skill's `authority`                                               | Action                                                                                        |
@@ -169,4 +215,6 @@ a false claim.
 - 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)
+- Dispatching a design/build skill in an existing codebase while `registry/*`
+  is empty (first-run preflight skipped)
 - Marking the run complete without every step's `verify` evidence