role-os 2.8.0 → 2.9.1

package/starter-pack/README.md

@@ -16,38 +16,46 @@ starter-pack/
     feature-packet.md        Building a new capability
     integration-packet.md    Wiring systems together
     identity-packet.md       Repairing inherited drift
-  agents/                  ← Role contracts. The spine.
-    core/
-      orchestrator.md        Decomposes and routes work
-      product-strategist.md  Shapes scope and intent
-      critic-reviewer.md     Accepts or rejects against contract
-    engineering/
-      frontend-developer.md  Implements user-facing surfaces
-      backend-engineer.md    Implements server/data/contracts
-      test-engineer.md       Verifies and defends against regression
-    design/
-      ui-designer.md         Designs hierarchy and interaction
-    marketing/
-      launch-copywriter.md   Writes truthful launch messaging
+  agents/                  ← 39 role contracts across 8 packs. The spine.
+    core/                    (3)  orchestrator, product-strategist, critic-reviewer
+    product/                 (4)  spec-writer, roadmap-prioritizer, feedback-synthesizer,
+                                  information-architect
+    engineering/             (14) frontend-developer, backend-engineer, test-engineer,
+                                  refactor-engineer, performance-engineer, security-reviewer,
+                                  dependency-auditor, component-auditor, seam-auditor,
+                                  test-truth-auditor, audit-synthesizer, red-teamer,
+                                  caption-auditor, monster-taxonomy-verifier
+    design/                  (2)  ui-designer, brand-guardian
+    marketing/               (1)  launch-copywriter
+    growth/                  (4)  launch-strategist, content-strategist, community-manager,
+                                  support-triage-lead
+    research/                (4)  ux-researcher, competitive-analyst, trend-researcher,
+                                  user-interview-synthesizer
+    treatment/               (7)  repo-researcher, repo-translator, docs-architect,
+                                  metadata-curator, coverage-auditor, deployment-verifier,
+                                  release-engineer
   schemas/                 ← Packet and handoff formats.
     task-packet.md           What work needs doing
     handoff.md               What one role passes to the next
     review-verdict.md        Accept, reject, or block
+    specialist.md            Specialist registry, gate, and consult record formats
   policy/                  ← System law.
     routing-rules.md         Which role handles what
     tool-permissions.md      What each role may and must not do
     escalation-rules.md      When to escalate instead of guess
     done-definition.md       What "done" actually means
+    specialist-tier.md       Law for model-backed specialist roles (registry, gate, probes)
   workflows/               ← Predefined role sequences.
     ship-feature.md          Feature from shaping to review
     fix-bug.md               Bug from report to regression defense
     launch-update.md         Copy from shipped truth to messaging
+    full-treatment.md        Repo polish + publish, integrated with shipcheck
 ```
 
 ## Quick start
 
 1. Copy this pack into your repo's `.claude/` directory
-2. Read `handbook.md` (under 400 words)
+2. Read `handbook.md` (a five-minute read)
 3. Fill the four `context/` files for your project
 4. Create your first packet using `schemas/task-packet.md`
 5. Route it through the smallest chain that covers the work

package/starter-pack/handbook.md

@@ -8,10 +8,10 @@ Each role has a contract: what it owns, what it must produce, when to escalate.
 
 ## What Role OS provides
 
-1. **Role Spine** — eight specialist role contracts with hard boundaries
-2. **Workflows** — canonical problem shapes: feature, integration, identity, full treatment
-3. **Schemas** — structured packet, handoff, and verdict formats
-4. **Policy** — routing, permissions, escalation, and done definition
+1. **Role Spine** — 39 specialist role contracts in the pack, each with hard boundaries (the runtime catalog routes 61 roles in total)
+2. **Workflows** — canonical problem shapes: ship-feature, fix-bug, launch-update, full-treatment
+3. **Schemas** — structured packet, handoff, verdict, and specialist formats
+4. **Policy** — routing, permissions, escalation, done definition, and specialist-tier law
 5. **Context templates** — product brief, repo map, priorities, brand rules
 
 ## What Role OS does not own

package/starter-pack/policy/routing-rules.md

@@ -197,3 +197,45 @@ Use the smallest number of roles needed to complete the task correctly.
 - Mental model mapping
 - Unmet needs ranking
 - Sample-aware confidence assessment
+
+## Route to Component Auditor
+- Deep audit of a bounded code component (assigned parcel with owned paths)
+- Per-file findings with quoted evidence, severity, and confidence
+- Truthful per-component understanding, not surface scanning
+- Not for tests (Test Truth Auditor) or cross-component interfaces (Seam Auditor)
+
+## Route to Seam Auditor
+- Interface inspection between components (boundary clusters)
+- Caller-assumption vs callee-contract verification
+- Content ↔ code drift detection (schemas/docs vs implementation)
+- Dependency-direction assessment of the import graph
+
+## Route to Test Truth Auditor
+- Test suite truthfulness assessment (proves correctness vs merely exists)
+- Ceremonial-test and test-theater detection
+- Untested-but-risky flow identification
+- Mock fidelity and integration-gap analysis
+
+## Route to Audit Synthesizer
+- Synthesis of completed component/seam/test audit parcels into one repo verdict
+- Ranked action plan (P0-P3) grouped by root cause
+- Cross-cutting finding identification and parcel-contradiction adjudication
+- Only after all audit parcels complete — never audits code directly
+
+## Route to Red-Teamer
+- Adversarial stress-testing of validators, caption rules, and pipeline contracts
+- Independent validation of canon-checking critics
+- Pre-freeze attack passes on training datasets and prompt libraries
+- Catch-rate measurement with named, categorized attack vectors
+
+## Route to Caption Auditor
+- Static caption compliance audit against the research-backed caption rules
+- Training-manifest pre-freeze verification
+- Post-rule-change dataset re-verification
+- Periodic drift checks against frozen manifests
+
+## Route to Monster Taxonomy Verifier
+- Creature/monster canon entry audit for LoRA-trainable schema fields
+- Monster-dataset separability assessment (apart from human-character data)
+- Anatomy/species/scale field coverage verification
+- Pre-assembly checks before a Monster LoRA dataset is built

package/starter-pack/policy/tool-permissions.md

@@ -151,3 +151,24 @@ May read canon entry files, schema files, reference plates, and approved-baselin
 May cross-reference canon text against declared schema.
 Must not modify canon, schema, or reference plates.
 Must not invent missing fields — surface gaps for the canon owner.
+
+## Component Auditor
+May read every file in its assigned parcel's owned paths, plus the manifest and repo context.
+May run read-only inspection commands (grep, line counts) within the parcel.
+Must not read forbidden paths outside the parcel or modify any code.
+Must not fix findings — surface them with quoted evidence for owners.
+
+## Seam Auditor
+May read files on both sides of its assigned boundary clusters, the component graph, shared utilities, and content files (schemas, policies) that should match code.
+Must not modify code, schemas, or content files.
+Must not audit single-component internals — stay at the boundaries; surface findings for owners.
+
+## Test Truth Auditor
+May read test files, corresponding implementation files (read-only reference), and run the test suite to observe results.
+Must not modify tests or implementation code.
+Must not add tests — recommend them; writing tests belongs to Test Engineer.
+
+## Audit Synthesizer
+May read all completed audit parcel outputs (component, seam, test) and the audit manifest.
+Must not audit code directly or generate new findings beyond cross-parcel synthesis.
+Must not modify code; the output is the verdict and the ranked action plan only.

package/starter-pack/workflows/full-treatment.md

@@ -2,6 +2,11 @@
 
 Every tool repo gets the full treatment before it's "whole." This is the complete 7-phase protocol — not a pointer to an external file.
 
+> **Adapting this workflow:** this protocol was written for the MCP Tool Shop org. Steps
+> marked **[org-internal]** reference that org's private infrastructure (brand repo,
+> repo-knowledge database, translation tooling). Substitute your own equivalents or skip
+> those steps — the phase structure and role owners are the portable part.
+
 ## Gate: Shipcheck runs first
 
 Full treatment does not start until shipcheck passes. Shipcheck is the 31-item quality gate (hard gates A-D block release).
@@ -14,20 +19,23 @@ No v1.0.0 bump without passing hard gates A-D.
 
 a) Clone repo, verify Pages source is "GitHub Actions", enable if not. Check for existing site/ and pages.yml.
 b) Note whether root package.json has "private": true (controls npm badge/link decisions).
-c) Push logo to brand repo: `mcp-tool-shop-org/brand/logos/<slug>/readme.png`, run `brand manifest`, commit+push. Min 530x530px.
-d) Update README: brand logo URL (`https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/<slug>/readme.png`), width="400", centered.
+c) **[org-internal]** Push logo to your brand repo (e.g. `<org>/brand/logos/<slug>/readme.png`), regenerate the manifest, commit+push. Min 530x530px.
+d) Update README: brand logo raw URL (e.g. `https://raw.githubusercontent.com/<org>/brand/main/logos/<slug>/readme.png`), width="400", centered.
 e) Badges (after logo, centered): CI status, Codecov coverage, MIT license, Landing Page. Only if published: npm/PyPI version badges.
 f) If logo contains product name, remove redundant `<h1>`.
 g) Update footer: `Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>`
-h) README is now final — hand the user the translation command(s).
+h) README is now final — run the translation step.
 
-Translation command (user runs in PowerShell, NOT Claude):
+Translation step **[org-internal]**: translations run on a local model (e.g. TranslateGemma
+via Ollama — zero API cost, ~2-4 min/README) using your translation tooling:
 ```
-node F:/AI/polyglot-mcp/scripts/translate-all.mjs F:/AI/<repo>/README.md
+node <path-to-translation-tooling>/translate-all.mjs <path-to-repo>/README.md
 ```
 Monorepos: chain with semicolons. Large monorepos: batch into groups of 5-7.
 
-WARNING: NEVER run translations from Claude — wastes Claude points. User runs locally (TranslateGemma 12B, Ollama, zero API cost, ~2-4 min/README).
+Translations must land BEFORE `npm publish` and BEFORE the GitHub release is tagged —
+release tags are immutable, and a tag cut before translations leaves stale locale READMEs
+on that tag forever. If you have no translation tooling, skip this step.
 
 ### Role owners
 - **Repo Researcher** — verify repo state, Pages config, package.json
@@ -98,8 +106,8 @@ g) Build and verify: `cd site && npm run build` — check dist/index.html + dist
 
 a) Set GitHub metadata:
 ```
-gh repo edit mcp-tool-shop-org/<repo> --description "<from package.json>" --homepage "https://mcp-tool-shop-org.github.io/<repo-name>/"
-gh repo edit mcp-tool-shop-org/<repo> --add-topic <tags>
+gh repo edit <org>/<repo> --description "<from package.json>" --homepage "https://<org>.github.io/<repo-name>/"
+gh repo edit <org>/<repo> --add-topic <tags>
 ```
 b) Code coverage: add coverage dep, coverage CI step (one matrix entry), codecov upload, badge in README
 c) Verify site builds, .gitignore complete, logo renders at brand URL
@@ -109,13 +117,15 @@ d) Review README for typos, broken links, stale content
 - **Metadata Curator** — GitHub metadata, badges, manifest
 - **Coverage Auditor** — test coverage assessment, CI integration
 
-## Phase 5 — Repo Knowledge DB entry
+## Phase 5 — Repo Knowledge DB entry **[org-internal]**
 
-Every treated repo gets a proper entry in the repo-knowledge database. This is NOT optional.
+Every treated repo gets a proper entry in the repo-knowledge database. This is NOT optional
+inside the org; consumers without a repo-knowledge deployment substitute their own
+catalog/inventory system or skip.
 
 a) Sync the repo if not already in the DB:
 ```
-rk sync --owners mcp-tool-shop-org
+rk sync --owners <org>
 ```
 
 b) Add required notes using MCP tools or CLI:
@@ -151,13 +161,13 @@ Push to main. Verify landing page + handbook render.
 
 ## Phase 7 — Post-deploy verification
 
-- Landing page renders at `https://mcp-tool-shop-org.github.io/<repo-name>/`
+- Landing page renders at `https://<org>.github.io/<repo-name>/`
 - Handbook renders at `.../handbook/`
 - Pagefind search works in handbook
 - Translations are complete (check ja for degenerate output)
 - Coverage badge shows real data
-- `rk show <slug>` returns complete knowledge entry
-- Repo-knowledge DB has thesis, architecture, and relationships
+- **[org-internal]** `rk show <slug>` returns complete knowledge entry
+- **[org-internal]** Repo-knowledge DB has thesis, architecture, and relationships
 
 ### Role owners
 - **Deployment Verifier** — landing page, handbook, package, badges, translations
@@ -171,6 +181,7 @@ Push to main. Verify landing page + handbook render.
 - Add extra Astro pages beyond index.astro unless requested
 - Skip the init CLI and scaffold manually
 - Add npm badges for private/unpublished repos
-- Skip the repo-knowledge DB entry — it's part of the treatment now
-- Run translations from Claude
+- Skip the repo-knowledge DB entry (org-internal) — it's part of the treatment
+- Tag a release or publish before translations land — release tags are immutable
 - Reference "memory/" paths without absolute paths — protocols must be self-contained
+- Hardcode machine-specific paths in this workflow — it ships to other people's repos