@starci/skills 1.1.0

package/resources/orchestrator.json

@@ -0,0 +1,71 @@
+{
+  "schemaVersion": 8,
+  "note": "How operators become agents. One invocation of one operator is one agent, created fresh on the operator's own profile (operator.json → resources) with the aliases its Context table declares and nothing else. The orchestrator owns dispatch: it writes the branch's request/request.json, validates it (scripts/validate-request.mjs), starts the agent, validates the response (scripts/validate-response.mjs, then the operator's validate.mjs), and follows routing.json to the next operator, user, or external party. It never merges two operators into one agent and never lets an agent start another; a nested exchange (a step that pauses with status waiting, e.g. architecture.decide's critique) is served by a second fresh agent the orchestrator spawns, with its own request/ and response/ inside the branch.",
+  "agentPerOperator": true,
+  "maxConcurrentAgents": 3,
+  "dispatch": "routing.json",
+  "agent": {
+    "profile": "operator.json → resources.profile",
+    "grants": "operator.json → resources.tools: each @tools/<id> with one mode from resources/tools.json, and nothing the profile would otherwise permit",
+    "refs": "operator.md → Context table, resolved through alias/alias.json; an unlisted location is unreadable",
+    "requirements": "operator.md → Requirements table; the orchestrator fills defaults into request.json and asks a person only for fields whose Default is — or whose value a stop code names",
+    "prompt": "rendered at dispatch from operator.md plus request.json; never stored",
+    "isolation": "fresh, no inherited turns",
+    "writes": "only response/ of its own branch (step-N/parallel-M/response/); a nested-exchange agent writes only <exchange>/response/ of that branch; a source-writing operator also writes the session branch of its checkout under an exclusive lease (see sourceWrites)"
+  },
+  "concurrency": {
+    "rule": "at most maxConcurrentAgents agents at once; branches of one step run concurrently only when their Writes touch no common alias",
+    "sharedCheckout": "two agents may read one checkout; only one may hold it for writing (backend.source.apply, frontend.source.apply, git.publish are exclusive per checkout)",
+    "sharedRoot": "business.decide is exclusive per businesses root; platform.operate is exclusive per runtime owner"
+  },
+  "handoff": {
+    "carrier": "response.json fields: kind → path relative to the branch; the next branch's request.json inputs point at step-N/parallel-M/<path> from the session root, written explicitly by the orchestrator (nearest earlier producer guides the orchestrator, never the agent)",
+    "stop": "response.json status blocked with stop = code; errors/ says whether the code terminates or falls back, and routing.json says where a terminated step hands to",
+    "waiting": "response.json status waiting with awaiting { exchange, kind }: the orchestrator validates the fields written so far, creates <exchange>/request/request.json in the same branch, runs a fresh agent for it, and resumes the paused agent when <exchange>/response/response.json is done; other branches of the step keep running",
+    "resume": "a blocked branch re-enters the same operator as a new agent in step-(N+1)/parallel-1, with request.json.resume naming the blocked step and parallel; the blocked branch stays on disk as evidence"
+  },
+  "session": {
+    "root": "<Source>/.worktrees/sessions/<sessionId>/",
+    "id": "<yyyymmdd-HHMMss>-<project>-<first operator>, e.g. 20260903-142200-starci-academy-frontend.direction.decide",
+    "manifest": "state.json: id, project, startedAt, status (running | blocked | done), chain [[\"1/1\"], [\"2/1\", \"2/2\"], ...], steps { \"N/M\": operatorId }, current, leases { \"N/M\": { agent, holds } }, requestHashes { \"N/M\": sha256 of request/request.json }",
+    "branch": "step-<N>/parallel-<M>/ — N is the position in the chain, M the parallel branch; parallel-1 always exists",
+    "branchLayout": [
+      "request/request.json",
+      "response/response.json",
+      "response/response.md",
+      "response/<other>.md when the operator has one",
+      "response/data/",
+      "response/artifacts/",
+      "<exchange>/request/request.json and <exchange>/response/ for a nested exchange"
+    ],
+    "paths": "inside request.json inputs: from the session root (step-1/parallel-1/response/response.md); inside response.json fields and operator.md Outputs: from the branch (response/response.md, critique/response/critique.md)",
+    "lifecycle": [
+      "create: the orchestrator writes state.json and takes the leases before the first agent starts",
+      "branch: each agent gets a fresh step-N/parallel-M/ with request/request.json already written and hashed into state.json, and writes only response/",
+      "advance: response.json status done and both validators green; the orchestrator writes the next branches' request.json from the Next table and routing.json",
+      "wait: status waiting runs the nested exchange, then resumes the same agent; the branch stays running in state.json",
+      "block: status blocked keeps the session on disk; the orchestrator asks the person for the field the stop names, then re-enters the operator in step-(N+1)/parallel-1 with resume set",
+      "done: when routing reaches user or external, or git.publish emits done, the orchestrator releases the leases and deletes the session folder; what survives is what the steps published (commits, business heads, UAT pairs, remote runs) and any audit record the owner copies out first"
+    ]
+  },
+  "sourceWrites": {
+    "rule": "an operator that writes source (frontend.source.apply, backend.source.apply) writes only on the session branch session/<sessionId> of the routed checkout, in a git worktree the orchestrator prepared from the frozen head; it commits the declared write set once and records the sha in response.json.commits; the person's checked-out branch is never touched",
+    "track": "changes.md names every path with before/after hashes and the commit; the next requests pin @workspaces/<role> at that sha (contexts[].head) so quality.verify and frontend.surface.audit verify exactly what was written",
+    "publish": "git.publish merges the session branch into the target branch: fast-forward when the target has not moved; a merge commit only when there is no conflict and the gates are re-run on the merge result; a conflict is NON_FAST_FORWARD and a person resolves it; never rebase, never force",
+    "cleanup": "after a successful publish the worktree and the session branch are removed together with the session folder; a blocked session keeps both",
+    "policy": "the routed checkout must declare gitPolicy.worktreeBranches = session-only (readiness/initialization/workspaces); a route declaring forbidden binds read-only and no source-writing operator may run against it"
+  },
+  "profileEquivalents": {
+    "rule": "an operator binds one profile; when the processor runs on a runtime that lacks that profile, it runs the equivalent profile of its own runtime with exactly the grants the operator requires, and response.json records both (boundProfile, ranProfile) so an audit can tell a stand-in from the binding",
+    "pairs": {
+      "opus": "sol-fresh",
+      "sonnet": "luna",
+      "fable": "sol-reviewer",
+      "sol-fresh": "opus",
+      "luna": "sonnet",
+      "sol-reviewer": "fable"
+    },
+    "grants": "the equivalent runs with the tools the operator declares that its own profile permits and its runtime supports (resources/tools.json); a tool the runtime does not support is unavailable for that run: a judged imagegen step records that no artwork could be made and continues, any other unsupported tool blocks the branch with the operator's own code",
+    "imageVersusVisualize": "imageGeneration means artwork: a digital image produced by an image model (OpenAI profiles only). Rendering HTML (direction candidates, audit sheets, previews) is visualization, needs no grant, and every runtime does it."
+  }
+}

package/resources/tools.json

@@ -0,0 +1,85 @@
+{
+  "schemaVersion": 9,
+  "note": "The closed registry of tools an operator may call, addressed as @tools/<id> in a Steps table. A tool is what an operator is allowed to do beyond reading aliases; an alias is what it may read. Each tool lists the modes an operator may declare in operator.json → resources.tools, and how each runtime provides it, so the same operator.md runs on Codex and on Claude without a second home for the rule. A runtime that does not support a tool cannot run an operator that declares it in a mode other than never; the processor then runs the profile equivalent on a runtime that does, or reports the gap. A tool absent from this file does not exist for an operator.",
+  "runtimes": {
+    "openai": "Codex (desktop app or CLI) running an OpenAI profile from resources/agents/profiles/openai.json",
+    "claude": "Claude Code (desktop app or CLI) running a Claude profile from resources/agents/profiles/claude.json"
+  },
+  "tools": {
+    "fileread": {
+      "purpose": "Read files and directories at the aliases the Context table names, at the frozen head.",
+      "modes": { "never": "the operator reads nothing on disk", "context-aliases": "only locations the Context table resolves to" },
+      "support": { "openai": { "supported": true, "via": "Codex file reads" }, "claude": { "supported": true, "via": "Claude Code Read, Glob and Grep" } }
+    },
+    "sourcewrite": {
+      "purpose": "Write files inside a routed checkout or an authority root.",
+      "modes": { "never": "the operator writes no file outside its own response/", "declared-write-set": "only the paths the request declared, only on the session branch or the authority root the alias names, only values the bound receipts already contain" },
+      "support": { "openai": { "supported": true, "via": "Codex file edits" }, "claude": { "supported": true, "via": "Claude Code Write and Edit" } }
+    },
+    "git": {
+      "purpose": "Read and change repository state: heads, branches, worktrees, commits, merges, pushes.",
+      "modes": { "never": "no git at all", "read": "rev-parse, status, log, diff, show; nothing that writes", "commit-session-branch": "create or reuse the session/<sessionId> worktree from the frozen head and commit the declared write set there exactly once; never the person's branch", "merge-and-push": "merge the session branch into the target (fast-forward, or a merge commit with the gates re-run), push without force, remove the session worktree and branch; never rebase, never force, never --no-verify" },
+      "support": { "openai": { "supported": true, "via": "git through the Codex shell" }, "claude": { "supported": true, "via": "git through the Claude Code Bash tool" } }
+    },
+    "shell": {
+      "purpose": "Run declared commands: gates, builds, proofs, hooks, deployment plans.",
+      "modes": { "never": "the operator runs no command", "declared-commands": "only the commands the route, the contract, or the manifest pins, with their output captured as evidence" },
+      "support": { "openai": { "supported": true, "via": "the Codex shell" }, "claude": { "supported": true, "via": "the Claude Code Bash tool" } }
+    },
+    "websearch": {
+      "purpose": "Read public web pages to close one named gap in the evidence; results are references with URLs, never authority.",
+      "modes": { "never": "the operator does not search", "bounded": "the operator searches only for the gap the step names and records every source it used with its URL" },
+      "support": { "openai": { "supported": true, "via": "Codex web search" }, "claude": { "supported": true, "via": "Claude Code WebSearch and WebFetch" } }
+    },
+    "imagegen": {
+      "purpose": "Produce artwork: a digital image from an image model, made to one stated claim. Rendering HTML is the visualize tool, not this one.",
+      "modes": { "never": "the operator produces no artwork", "judged": "the operator decides on its own, from the direction, whether a region reads empty enough to need artwork, records why, and never decorates", "required": "artwork is a step of the job" },
+      "support": { "openai": { "supported": true, "via": "the OpenAI image model available to the Codex session" }, "claude": { "supported": false, "via": "none; a judged step records that no artwork could be made and the branch continues; a required step blocks with the operator's own code" } }
+    },
+    "visualize": {
+      "purpose": "Render HTML for a person to look at: direction candidates, audit sheets, alternative comparisons, previews. No model grant is involved.",
+      "modes": { "never": "the operator renders nothing", "html": "the operator writes HTML under response/artifacts/ and links it from response.md" },
+      "support": { "openai": { "supported": true, "via": "files written by the Codex session" }, "claude": { "supported": true, "via": "files written by the Claude Code session" } }
+    },
+    "browsercontrol": {
+      "purpose": "Drive a real browser against a served route: navigate, act, capture screenshots and DOM measurements.",
+      "modes": { "never": "the operator opens no browser", "required": "the operator's evidence comes from a driven browser" },
+      "support": { "openai": { "supported": true, "via": "Codex computer use, which opens the person's own Chrome; every UAT or audit run must use a dedicated browser profile (the shared UAT identity), never the person's logged-in profile" }, "claude": { "supported": true, "via": "the in-app Browser pane, or Claude in Chrome when the task needs the person's sessions" } }
+    },
+    "http": {
+      "purpose": "Probe an endpoint: readiness, health, a served route, a GraphQL typename, a status page.",
+      "modes": { "never": "no probes", "probe": "GET or HEAD against the endpoints the runtime registry or the manifest names, with the observed status recorded" },
+      "support": { "openai": { "supported": true, "via": "curl through the Codex shell" }, "claude": { "supported": true, "via": "curl through Bash, or WebFetch for a public URL" } }
+    },
+    "registry": {
+      "purpose": "Read a package registry: the published Grammar, its version, its files.",
+      "modes": { "never": "no registry reads", "read": "npm view and the installed package in node_modules; publishing stays with a person" },
+      "support": { "openai": { "supported": true, "via": "npm through the Codex shell" }, "claude": { "supported": true, "via": "npm through Bash" } }
+    },
+    "container": {
+      "purpose": "Inspect or operate containers and images: compose services, GHCR images by digest.",
+      "modes": { "never": "no container operations", "read": "inspect, logs, digests", "operate": "start, stop, roll out, roll back the services the approved plan names" },
+      "support": { "openai": { "supported": true, "via": "docker and the GHCR API through the Codex shell" }, "claude": { "supported": true, "via": "docker and the GHCR API through Bash" } }
+    },
+    "ci": {
+      "purpose": "Observe or dispatch continuous-integration runs.",
+      "modes": { "never": "no CI access", "read": "list and read runs and their logs", "dispatch": "trigger the workflow the release manifest names" },
+      "support": { "openai": { "supported": true, "via": "gh through the Codex shell" }, "claude": { "supported": true, "via": "gh through Bash" } }
+    },
+    "objectstorage": {
+      "purpose": "Read or write objects in the content store (MinIO): curriculum, style references, published units.",
+      "modes": { "never": "no object store access", "read": "read the objects the unit names", "write": "publish the objects the unit produced, under a person's approval" },
+      "support": { "openai": { "supported": true, "via": "the MinIO client or its HTTP API through the Codex shell" }, "claude": { "supported": true, "via": "the MinIO client or its HTTP API through Bash" } }
+    },
+    "secrets": {
+      "purpose": "Resolve a sealed credential by name at the moment it is used; never read, print or store its value.",
+      "modes": { "never": "no credential is resolved", "resolve-by-name": "the name comes from device-state or a route; decryption happens in the tool that consumes it; a value never enters response/" },
+      "support": { "openai": { "supported": true, "via": "SOPS and age through the Codex shell" }, "claude": { "supported": true, "via": "SOPS and age through Bash" } }
+    },
+    "database": {
+      "purpose": "Read or write the product database for verification: seeds, fixtures, is_uat records.",
+      "modes": { "never": "no database access", "read": "select only", "namespaced-write": "insert and delete only rows carrying the run namespace and is_uat=true" },
+      "support": { "openai": { "supported": true, "via": "psql or the service's API through the Codex shell" }, "claude": { "supported": true, "via": "psql or the service's API through Bash" } }
+    }
+  }
+}

package/routing.json

@@ -0,0 +1,272 @@
+{
+  "schemaVersion": 9,
+  "note": "Closed routing map. A skill reads a validated operator output and routes on outcome, then on failure.owningDomain. It never reads prose to decide the next step.",
+  "kinds": {
+    "operator": "Invoke the named operator next.",
+    "resume": "Invoke the same operator again with the required delta from its resume token.",
+    "user": "Stop. A person owns this and must decide or publish before the mission continues.",
+    "external": "Stop. The blocker is outside the runtime and no operator can clear it."
+  },
+  "routes": {
+    "architecture.decide": {
+      "architecture": {
+        "kind": "resume"
+      },
+      "business": {
+        "kind": "operator",
+        "target": "business.decide"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "backend.source.apply": {
+      "backend": {
+        "kind": "resume"
+      },
+      "business": {
+        "kind": "operator",
+        "target": "business.decide"
+      },
+      "contract": {
+        "kind": "user"
+      },
+      "platform": {
+        "kind": "operator",
+        "target": "platform.operate"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "business.decide": {
+      "business": {
+        "kind": "resume"
+      },
+      "backend": {
+        "kind": "operator",
+        "target": "backend.source.apply"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "content.generate": {
+      "content": {
+        "kind": "resume"
+      },
+      "curriculum": {
+        "kind": "user"
+      },
+      "engineering": {
+        "kind": "user"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "frontend.direction.decide": {
+      "business": {
+        "kind": "operator",
+        "target": "business.decide"
+      },
+      "backend": {
+        "kind": "operator",
+        "target": "backend.source.apply"
+      },
+      "architecture": {
+        "kind": "operator",
+        "target": "architecture.decide"
+      },
+      "grammar": {
+        "kind": "user"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      },
+      "frontend": {
+        "kind": "resume"
+      }
+    },
+    "frontend.presentation.resolve": {
+      "grammar": {
+        "kind": "user"
+      },
+      "knowledge": {
+        "kind": "user"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      },
+      "frontend": {
+        "kind": "resume"
+      }
+    },
+    "frontend.source.apply": {
+      "resolution": {
+        "kind": "operator",
+        "target": "frontend.presentation.resolve"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "frontend.surface.audit": {
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      },
+      "platform": {
+        "kind": "operator",
+        "target": "platform.operate"
+      },
+      "frontend": {
+        "kind": "resume"
+      }
+    },
+    "git.publish": {
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "source": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "remote": {
+        "kind": "external"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "platform.operate": {
+      "platform": {
+        "kind": "resume"
+      },
+      "provider": {
+        "kind": "external"
+      },
+      "product": {
+        "kind": "user"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "quality.verify": {
+      "platform": {
+        "kind": "operator",
+        "target": "platform.operate"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "release.deploy": {
+      "deployment": {
+        "kind": "resume"
+      },
+      "platform": {
+        "kind": "operator",
+        "target": "platform.operate"
+      },
+      "provider": {
+        "kind": "external"
+      },
+      "backend": {
+        "kind": "operator",
+        "target": "backend.source.apply"
+      },
+      "approval": {
+        "kind": "user"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    },
+    "uat.verify": {
+      "control-panel": {
+        "kind": "external"
+      },
+      "runtime": {
+        "kind": "external"
+      },
+      "backend": {
+        "kind": "operator",
+        "target": "backend.source.apply"
+      },
+      "quality": {
+        "kind": "operator",
+        "target": "quality.verify"
+      },
+      "caller": {
+        "kind": "user"
+      },
+      "platform": {
+        "kind": "operator",
+        "target": "platform.operate"
+      },
+      "workspace": {
+        "kind": "operator",
+        "target": "workspace.bind"
+      }
+    },
+    "workspace.bind": {
+      "workspace": {
+        "kind": "resume"
+      },
+      "source": {
+        "kind": "resume"
+      },
+      "runtime": {
+        "kind": "external"
+      },
+      "identity": {
+        "kind": "external"
+      },
+      "caller": {
+        "kind": "user"
+      }
+    }
+  }
+}

package/scripts/alias-registry.mjs

@@ -0,0 +1,31 @@
+// alias/alias.json is a tree: one root per zone (@workspaces, @grammar, @knowledge, @worktrees,
+// @remote, @dynamic), children by path segment, and a node is a definition when it carries
+// `resolvesTo`. This module is the one place the tree is flattened to `@root/segment/...` keys, so
+// the validator and the generator cannot disagree about what an alias is called.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEF_KEYS = new Set(['params', 'kind', 'resolvesTo', 'scheme', 'bind', 'writers', 'purpose', 'note']);
+
+export async function loadAliasRegistry(root) {
+  const raw = JSON.parse(await readFile(path.join(root, 'alias', 'alias.json'), 'utf8'));
+  const aliases = {};
+  const walk = (node, prefix, zone) => {
+    if (node.resolvesTo !== undefined) aliases[prefix] = { ...Object.fromEntries(Object.entries(node).filter(([k]) => DEF_KEYS.has(k))), zone };
+    for (const [key, child] of Object.entries(node)) {
+      if (DEF_KEYS.has(key) || typeof child !== 'object' || child === null || Array.isArray(child)) continue;
+      walk(child, `${prefix}/${key}`, zone);
+    }
+  };
+  for (const [rootKey, node] of Object.entries(raw.tree ?? {})) walk(node, rootKey, rootKey.slice(1));
+  // @tools/<id> is what an operator may call, not read; it comes from resources/tools.json so a Steps cell can
+  // name a tool next to the aliases it reads and the same resolver answers both.
+  const toolsDoc = JSON.parse(await readFile(path.join(root, 'resources', 'tools.json'), 'utf8'));
+  const tools = {};
+  for (const [id, tool] of Object.entries(toolsDoc.tools ?? {})) {
+    tools[`@tools/${id}`] = { params: [], kind: 'tool', resolvesTo: `resources/tools.json#tools.${id}`, scheme: `tool://${id}`, bind: `mode declared in operator.json → resources.tools; modes: ${Object.keys(tool.modes).join(' | ')}`, writers: [], purpose: tool.purpose, zone: 'tools', support: tool.support };
+  }
+  return { schemaVersion: raw.schemaVersion, note: raw.note, zones: raw.zones ?? {}, segments: raw.segments ?? {}, aliases: { ...aliases, ...tools }, tree: raw.tree ?? {}, tools };
+}
+
+export const baseOf = (aliases, alias) => Object.keys(aliases).filter((k) => alias === k || alias.startsWith(`${k}/`)).sort((a, b) => b.length - a.length)[0] ?? null;