role-os 1.0.0

package/starter-pack/agents/treatment/repo-researcher.md

@@ -0,0 +1,40 @@
+# Repo Researcher
+
+## Mission
+Map the live truth of a repository — structure, entrypoints, seams, build paths, and runtime shape — so downstream roles work from verified fact, not stale assumptions.
+
+## Use When
+- A full treatment needs current repo state
+- A packet references files, modules, or paths that need verification
+- Dependency checks require live repo inspection
+- Architecture understanding is missing or outdated
+
+## Do Not Use When
+- Repo structure is already verified and recent
+- The task is purely product/design with no repo dependency
+- Someone already mapped the repo in this session
+
+## Expected Inputs
+- Repo URL or local path
+- Prior repo-map if one exists
+- Specific questions about structure or seams
+
+## Required Output
+- Verified directory structure (key paths only)
+- Entrypoints and runtime shape
+- Build/test/run commands (verified working)
+- Key seams and architectural boundaries
+- Missing or unexpected findings
+- Confidence level per finding
+
+## Quality Bar
+- Every path and command verified live, not assumed
+- Distinguish proven from assumed
+- Flag stale prior knowledge explicitly
+- Do not map exhaustively — map what matters
+
+## Escalation Triggers
+- Repo is inaccessible or in broken state
+- Build/test commands fail
+- Architecture contradicts documented assumptions
+- Critical files referenced by other roles do not exist

package/starter-pack/agents/treatment/repo-translator.md

@@ -0,0 +1,38 @@
+# Repo Translator
+
+## Mission
+Translate documentation across languages and audiences faithfully, preserving technical accuracy and product voice without invention.
+
+## Use When
+- README or docs need translation to other languages
+- Documentation needs adaptation for a different audience (developer vs user vs operator)
+- Treatment Phase 1 hands off translation work
+- Cross-audience documentation gaps exist
+
+## Do Not Use When
+- Source content is not yet finalized
+- Translation would require inventing missing product claims
+- The task is copywriting (use Launch Copywriter instead)
+
+## Expected Inputs
+- Finalized source document(s)
+- Target languages or audiences
+- Brand rules and terminology constraints
+- Translation tooling instructions (e.g., polyglot-mcp)
+
+## Required Output
+- Translated files in the correct format and location
+- Notes on terms that required judgment calls
+- Flagged passages where meaning was ambiguous
+- Verification that translations completed without degenerate output
+
+## Quality Bar
+- Technical terms preserved correctly
+- Product voice maintained across languages
+- No invented claims or expanded scope
+- Degenerate output (garbled, truncated, wrong language) caught and flagged
+
+## Escalation Triggers
+- Source content is ambiguous enough to produce different meanings
+- Translation tooling produces degenerate output
+- Brand terminology has no clear equivalent in target language

package/starter-pack/context/brand-rules.md

@@ -0,0 +1,52 @@
+# Brand Rules
+
+<!-- What this file is for:
+     The identity law for this product. Roles read this to ensure
+     every surface matches what this product actually is — not what
+     a fork ancestor, sibling, or genre default would suggest.
+
+     What good input looks like:
+     Concrete guidance a developer or designer can apply without
+     asking follow-up questions. "Industrial, worn, functional"
+     is better than "cool and modern."
+
+     What not to put here:
+     Marketing copy, aspirational brand positioning, or visual
+     design specs. This is identity law, not a mood board.
+-->
+
+## Tone
+<!-- How should this product sound? Not personality adjectives —
+     operational guidance.
+     Example: "Direct, mechanical, no filler. Error messages state
+     what failed and what to do. Never apologize." -->
+
+## Domain Language
+<!-- What vocabulary does this product use? List the canonical terms.
+     Example: "credits (not coins/gold), sectors (not zones/worlds),
+     crew (not party/team), haul (not quest/mission)." -->
+
+## Forbidden Metaphors
+<!-- What imagery, terminology, or framing must never appear?
+     Be specific — vague bans are unenforceable.
+     Example: "No maritime language: waves, sails, anchors, harbors,
+     wake, berth, compass rose. No ocean-themed motion verbs." -->
+
+## Truth Constraints
+<!-- What claims must this product never make about itself?
+     Example: "Never claim AI-generated content is human-written.
+     Never imply capabilities that don't exist yet." -->
+
+## Contamination Risks
+<!-- If this product was forked from, inspired by, or shares code
+     with another product, name the specific drift risks.
+     Example: "Forked from Portlight. Maritime ASCII art, wave
+     animations, anchor icons, and silver currency language are
+     contamination — not heritage." -->
+
+## Approved Visual Register
+<!-- Optional. If the product has visual surfaces, what is the
+     correct visual register?
+     Example: "Industrial, worn, functional. Hull schematics not
+     sailboats. Cargo manifests not treasure maps. Scanner sweep
+     not wave animation." -->

package/starter-pack/context/current-priorities.md

@@ -0,0 +1,33 @@
+# Current Priorities
+
+<!-- What this file is for:
+     What's happening now in this project. Roles read this to avoid
+     conflicting with active work and to understand recent context.
+
+     What good input looks like:
+     Short, current, honest. Update this when priorities shift.
+
+     What not to put here:
+     Long-term roadmap, completed work history, or feature wishlists.
+     This is the current state, not the backlog.
+-->
+
+## Active Work
+<!-- What is being worked on right now? 1-3 items max.
+     If nothing is active, say so. -->
+
+## Next Up
+<!-- What comes immediately after the current work? -->
+
+## Blocked
+<!-- What is waiting on something? State what it's waiting on.
+     If nothing is blocked, say so. -->
+
+## Recently Completed
+<!-- What just shipped or merged? Useful for launch copy,
+     integration context, and avoiding duplicate work. -->
+
+## Banned Detours
+<!-- What should NOT be started right now, even if it seems useful?
+     This prevents well-intentioned scope drift.
+     Example: "Do not refactor the auth system until v2 ships." -->

package/starter-pack/context/product-brief.md

@@ -0,0 +1,47 @@
+# Product Brief
+
+<!-- What this file is for:
+     The single source of truth for what this product is, who it's for,
+     and what it must not become. Every role reads this before starting work.
+
+     What good input looks like:
+     Specific, testable statements. "A CLI tool that validates JSON schemas"
+     not "a developer productivity platform."
+
+     What not to put here:
+     Roadmap items, implementation details, or marketing copy.
+     This is product truth, not product aspiration.
+-->
+
+## Product
+<!-- One sentence. What is this thing? -->
+
+## Thesis
+<!-- Why does this exist? What bet are you making? What is true about this
+     product that would be false about a generic alternative? -->
+
+## Target User
+<!-- Who is this for? Be specific enough that you could find them.
+     "Developers using MCP clients" not "technical users." -->
+
+## Core Value
+<!-- What does it do that nothing else does well enough?
+     State the mechanical value, not the emotional value. -->
+
+## Non-Goals
+<!-- What are you explicitly not building? These prevent scope drift.
+     List at least 3 things someone might reasonably expect but you reject. -->
+
+## Current Stage
+<!-- concept | prototype | alpha | beta | shipped | mature -->
+
+## Key Constraints
+<!-- Tech stack, budget, compatibility requirements, platform limits.
+     These are facts, not preferences. -->
+
+## Fiction/Identity Rules
+<!-- Optional but valuable for forked or inherited projects.
+     If this product has a parent, ancestor, or sibling whose identity
+     could contaminate this product's surfaces, state the boundary here.
+     Example: "This is a space-industrial game, not a maritime game.
+     No waves, sails, harbors, or nautical framing." -->

package/starter-pack/context/repo-map.md

@@ -0,0 +1,45 @@
+# Repo Map
+
+<!-- What this file is for:
+     Technical truth about the repository. Roles read this to understand
+     where code lives, how to build/test, and where the risky seams are.
+
+     What good input looks like:
+     Concrete paths, commands, and architecture notes. Not aspirational
+     architecture diagrams — describe what exists now.
+
+     What not to put here:
+     Product decisions, feature plans, or design philosophy.
+     This is repo truth, not product truth.
+-->
+
+## Repository
+<!-- URL, local path, default branch, current version -->
+
+## Language / Stack
+<!-- Primary language, framework, runtime, build system -->
+
+## Directory Structure
+<!-- Key directories and what they contain. Focus on where a new
+     contributor would need to look, not exhaustive tree listing. -->
+
+## Conventions
+<!-- Naming patterns, formatting, testing approach, state management
+     philosophy. How does this codebase prefer to do things? -->
+
+## Build / Run
+<!-- Exact commands to build, test, and run. A new contributor should
+     be able to copy-paste these. -->
+
+## Key Files
+<!-- The 5-10 most important files. Entry points, core logic, config,
+     state models. Where does behavior actually live? -->
+
+## Dependencies
+<!-- Notable dependencies and why they exist. Not a full package list —
+     just the ones that shape how the code works. -->
+
+## Risky Seams
+<!-- Where are the architectural boundaries that are easy to get wrong?
+     Legacy/new system boundaries, serialization gaps, state that lives
+     in two places, import paths that cross concerns. -->

package/starter-pack/examples/feature-packet.md

@@ -0,0 +1,39 @@
+# Example: Feature Packet
+
+**Problem shape:** Building a new user-facing capability that needs product shaping, design, implementation, testing, and review.
+
+**When to use this shape:** The feature touches product intent (what to show, what to defer), has a UI or output surface, needs implementation across 1+ files, and benefits from a quality gate before merge.
+
+---
+
+## What a feature packet teaches
+
+### 1. Product shaping under pressure
+The Product Strategist decides what information is primary vs noise, rules on open questions, and sets the information hierarchy. This prevents downstream roles from re-arguing product decisions.
+
+**Key pattern:** Product defines a clear "this is a status surface, not a command surface" ruling. That single frame prevents every other role from inventing a different purpose.
+
+### 2. Contamination/fidelity guard
+If the project has a fork ancestor, legacy codebase, or inherited design language, the packet must include a contamination constraint. Every role checks for residue. The critic rejects work that is functional but fiction-wrong.
+
+**Key pattern:** Name the exact files, imports, and terms that are contaminated. "No legacy language" is vague. "Never import from legacy_models.py; never use old_display()" is testable.
+
+### 3. Real escalation
+Backend surfaced a missing engine field instead of faking it. Frontend surfaced a session wiring gap instead of hiding it behind a fallback. Both were legitimate escalations that improved the final output.
+
+**Key pattern:** Escalation happens at the role that discovers the gap, not at review. The escalation includes what's missing, why it matters, and a proposed shim or scope reduction.
+
+### 4. Review against contract
+The critic judged against the done definition, not against "does it look good." Items were marked MET, UNMET, or CONDITIONAL with evidence. The verdict was accept-with-notes — honest about what worked and what remained external.
+
+**Key pattern:** The critic checks each done-definition item individually. A clean accept requires all items met. Accept-with-notes requires binding follow-up items. Reject requires corrections before re-review.
+
+---
+
+## Typical chain
+Orchestrator → Product Strategist → UI Designer → Backend Engineer → Frontend Developer → Test Engineer → Critic Reviewer
+
+## When to shorten
+- Skip UI Designer if there's no user-facing surface to design
+- Skip Backend if all data already exists
+- Skip Product Strategist if scope is already locked by a prior packet

package/starter-pack/examples/identity-packet.md

@@ -0,0 +1,39 @@
+# Example: Identity Packet
+
+**Problem shape:** Repairing inherited or drifted fiction, branding, terminology, or visual language across existing code — without turning into a broad redesign.
+
+**When to use this shape:** The product's visible surfaces don't match its actual identity. A fork ancestor's language is still present. Terminology from a different domain leaked in. Visual motifs belong to a different product.
+
+---
+
+## What an identity packet teaches
+
+### 1. Replacement doctrine, not just removal
+Removing contaminated terms without defining replacements creates bland output. Product Strategist must define what the correct register is — not just what's banned, but what replaces it and why.
+
+**Key pattern:** Build a replacement table with contaminated term, replacement, and rationale. "No legacy language" becomes "specific replacement per term, not blanket removal." Every banned term has a specific replacement.
+
+### 2. No redesign drift
+The strongest discipline in an identity packet is doing only the purge. Roles will be tempted to "improve" layout, hierarchy, or features while they're in the file. Reject that.
+
+**Key pattern:** The done definition includes "no unrelated redesign was performed." The critic checks this explicitly. A screen that was purged AND redesigned gets sent back.
+
+### 3. Severity ranking
+Not all contamination is equally damaging. Product Strategist ranks contamination by visibility and impact. Hero visuals (splash screens, headers) are more damaging than internal code comments.
+
+**Key pattern:** Priority order guides Frontend's implementation sequence. If time is constrained, the most visible contamination is fixed first.
+
+### 4. Durable contamination defense
+Cleaning files is necessary but insufficient. Without regression tests, the contamination returns. The test engineer's job is to produce tests that outlive the packet — permanent CI checks, not one-time audits.
+
+**Key pattern:** Banned-term scans, banned-symbol scans, required-replacement assertions, and import-source checks. These tests run on every CI pass and fail if contamination is reintroduced by any contributor.
+
+---
+
+## Typical chain
+Orchestrator → Product Strategist → UI Designer → Frontend Developer → Test Engineer → Critic Reviewer
+
+## When to shorten
+- Skip UI Designer if the contamination is purely textual (labels, terms) with obvious replacements
+- Skip Backend if no contamination is in data-generating code
+- Add Backend if contaminated strings are generated from data models rather than hardcoded in views

package/starter-pack/examples/integration-packet.md

@@ -0,0 +1,39 @@
+# Example: Integration Packet
+
+**Problem shape:** Wiring two systems together across an architectural seam — making state, data, or control flow reach a place it currently can't.
+
+**When to use this shape:** A feature is blocked because System A can't access System B's state. Or a save/load path doesn't include new state. Or a session layer doesn't expose data that a screen or tool needs.
+
+---
+
+## What an integration packet teaches
+
+### 1. Dependency verification first
+Before any design work, verify every upstream assumption against actual repo truth. "The session exposes this data" might be false — check the actual code, not the docs.
+
+**Key pattern:** Build a dependency table with file paths, line numbers, and verified/unverified status. Catch false assumptions at Step 1, not Step 5.
+
+### 2. Bridge/seam resolution
+The bridge should be clean and typed — a new attribute, a serialization pair, a wiring function. Not a hybrid where the system "sometimes reads from A and sometimes from B."
+
+**Key pattern:** Backend proposes the exact attribute name, import alias (if naming collisions exist), initialization point, and serialization format. Frontend receives a concrete contract, not a vague "data will be available."
+
+### 3. Anti-fallback testing
+The most dangerous failure mode is silent fallback — the app appears to work but quietly uses legacy/placeholder data instead of the real source. Tests must assert the live path is real, not just present.
+
+**Key pattern:** Write tests that assert `state is not None` after initialization, assert the state type is correct (not legacy), and assert the data content matches what was stored. A test that passes when the feature is broken is worse than no test.
+
+### 4. Breaking change management
+Integration work often changes return types, tuple sizes, or function signatures. Every caller must be updated. The blast radius must be documented before implementation.
+
+**Key pattern:** Grep for all callers of the changed function. Categorize them by update pattern. Document which are mechanical (add `_ignored` to unpacking) vs which need inspection.
+
+---
+
+## Typical chain
+Orchestrator → Backend Engineer → Frontend Developer → Test Engineer → Critic Reviewer
+
+## When to shorten
+- Skip Frontend if the wiring is purely backend (no screen or tool changes)
+- Skip Product Strategist if there are no user-visible behavior choices
+- Add Product Strategist if the integration reveals ambiguity about what state should be canonical

package/starter-pack/handbook.md

@@ -0,0 +1,67 @@
+# Role OS — Adoption Handbook
+
+## What Role OS does
+
+Role OS routes scoped work through role contracts, structured packets, review, and escalation — so features, integrations, identity repairs, and full repo treatments ship without drift, false completion, or vibes-based progress claims.
+
+Each role has a contract: what it owns, what it must produce, when to escalate. Work moves through a chain of roles. A critic reviews against the contract, not against wishes. The system protects truth, not speed.
+
+## 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
+5. **Context templates** — product brief, repo map, priorities, brand rules
+
+## What Role OS does not own
+
+- **Claude project memory** — where it exists, Claude project memory is the canonical continuity layer. Role OS integrates with it, does not duplicate it.
+- **Full treatment protocol** — the canonical 7-phase protocol lives in Claude project memory (`memory/full-treatment.md`). Role OS routes and reviews treatments, it does not redefine them.
+- **Shipcheck** — the 31-item quality gate that runs before full treatment. Canonical reference: `memory/shipcheck.md`.
+
+## Use it for
+
+- **Features** that need product shaping, implementation, testing, and review
+- **Integrations** that wire systems together across architectural seams
+- **Identity/polish work** that repairs branding, fiction, or terminology drift
+- **Full treatment** — routed through Role OS using the canonical protocol
+- Any scoped work where you want honest decomposition, clear handoffs, and truthful review
+
+## Don't use it for
+
+- Single-line fixes, typos, or obvious bugs
+- Exploratory research or spikes with no defined output
+- Work where the entire scope fits in one person's head in 5 minutes
+- Emergency hotfixes that need to ship before a review chain completes
+
+## Packet flow
+
+1. **Create a packet** — define the outcome, scope, non-goals, constraints, and done definition
+2. **Verify dependencies** — confirm every upstream assumption against repo truth
+3. **Route to a chain** — pick the smallest set of roles needed (2-7 roles, not always all)
+4. **Each role produces a handoff** — structured output that reduces ambiguity for the next role
+5. **Critic reviews** — accepts, rejects, or sends back with notes, judged against contract and done definition
+6. **Record the verdict** — evidence of what was accepted, what was flagged, what follows
+
+## Full treatment
+
+Shipcheck runs first (`npx @mcptoolshop/shipcheck audit` must exit 0). Then the canonical 7-phase treatment protocol executes. Role OS adds role contracts, handoffs, and review gates to each phase — it does not replace the protocol.
+
+See `workflows/full-treatment.md` for the integration reference.
+
+## Review and escalation
+
+The critic reviewer is not ceremonial. They reject work that is vague, contaminated, or incomplete — even if it's otherwise functional. "Good but wrong" is a valid rejection.
+
+Any role can escalate when missing information would change the work materially. Escalation is expected, not failure. Hiding gaps is the actual failure.
+
+## First run
+
+1. Fill `context/` files — product brief, repo map, priorities, brand rules
+2. Create your first packet
+3. Route it through the smallest chain that covers the work
+4. Produce handoffs (light format for routine, full format for complex)
+5. Review and record the verdict
+
+You will learn the system by using it once, not by studying it.

package/starter-pack/policy/done-definition.md

@@ -0,0 +1,15 @@
+# Done Definition
+
+A role is done when:
+1. It completed the assigned scope.
+2. It produced the required output shape.
+3. It surfaced risks and assumptions honestly.
+4. It identified the correct next owner.
+5. Its output is reviewable without extra interpretation.
+
+Work is not done when:
+- It is still vague
+- It depends on hidden assumptions
+- It skipped verification
+- It solved a different problem than the packet requested
+- It carries cross-project residue (imagery, terminology, UI motifs, or mental models from a fork ancestor or sibling product that do not belong to this product's fiction)

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

@@ -0,0 +1,20 @@
+# Escalation Rules
+
+Escalate instead of guessing when the missing information would change the work materially.
+
+## Mandatory Escalation Cases
+- Missing API contract
+- Missing design direction
+- Conflicting product goals
+- Unknown repo conventions
+- Dependency on unavailable files or tools
+- Quality bar cannot be met within scope
+- Requested outcome contradicts context or policy
+
+## Allowed Assumptions
+Small implementation details that do not change user-visible behavior or system contract.
+
+## Forbidden Behavior
+- Pretending ambiguity does not exist
+- Filling missing product direction with generic defaults
+- Marking work complete when key dependencies are unresolved