role-os 1.0.0

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

@@ -0,0 +1,199 @@
+# Routing Rules
+
+Use the smallest number of roles needed to complete the task correctly.
+
+## Route to Orchestrator
+- Multi-step work
+- Cross-functional work
+- Ambiguous ownership
+- Need for sequencing or decomposition
+
+## Route to Product Strategist
+- Problem framing
+- Scope definition
+- Prioritization
+- Feature shaping
+- Tradeoff decisions
+
+## Route to UI Designer
+- Information hierarchy
+- User flow
+- Interaction design
+- Screen structure
+- Visual direction within existing brand
+
+## Route to Frontend Developer
+- UI implementation
+- Client state
+- Components
+- Interaction wiring
+- Frontend integration
+
+## Route to Backend Engineer
+- APIs
+- Services
+- Data flow
+- Persistence
+- Contracts
+- Server logic
+
+## Route to Test Engineer
+- Test plans
+- Regression defense
+- Edge cases
+- Verification coverage
+
+## Route to Launch Copywriter
+- Release notes
+- Launch messaging
+- Positioning
+- Conversion copy
+
+## Route to Critic Reviewer
+- Final acceptance
+- Contract validation
+- Quality gate
+- Truthful rejection
+
+## Route to Repo Researcher
+- Repo structure mapping
+- Entrypoint and seam discovery
+- Build/test command verification
+- Dependency verification against live repo truth
+
+## Route to Repo Translator
+- README or docs translation to other languages
+- Cross-audience documentation adaptation
+- Translation verification and degenerate output detection
+
+## Route to Docs Architect
+- Handbook or docs site creation
+- Documentation restructuring
+- Starlight docs setup
+- Information architecture for searchable docs
+
+## Route to Metadata Curator
+- Package manifest audit
+- GitHub repo metadata (description, topics, homepage)
+- Badge verification
+- Registry metadata alignment
+
+## Route to Coverage Auditor
+- Test coverage assessment
+- False confidence detection
+- Missing defense identification
+- CI coverage integration
+
+## Route to Deployment Verifier
+- Post-deploy verification
+- Landing page, handbook, and package live checks
+- Badge resolution verification
+- Translation spot-checks
+
+## Route to Release Engineer
+- Version bump and tagging
+- Changelog updates
+- Package build and publish readiness
+- Staging and release execution
+
+## Route to Brand Guardian
+- Identity contamination audit
+- Terminology and tone consistency
+- Fork/ancestor residue detection
+- Replacement doctrine enforcement
+
+## Route to Feedback Synthesizer
+- User signal clustering and theme extraction
+- Issue backlog analysis
+- Complaint-to-action translation
+- Post-launch signal interpretation
+
+## Route to Roadmap Prioritizer
+- Work sequencing by leverage and dependency
+- Backlog ordering
+- Dependency mapping between work items
+- "Stop doing this" recommendations
+
+## Route to Spec Writer
+- Turning approved scope into execution-grade specs
+- Acceptance criteria authoring
+- Edge case enumeration
+- Non-functional requirements definition
+
+## Route to Information Architect
+- Navigation and hierarchy design
+- Content organization and findability
+- Cross-surface consistency
+- Naming and labeling recommendations
+
+## Route to Refactor Engineer
+- Structure cleanup without behavior change
+- Duplication elimination
+- Module boundary clarification
+- Complexity reduction
+
+## Route to Performance Engineer
+- Measured performance optimization
+- Regression identification with profiling
+- Hot path analysis
+- Performance budget enforcement
+
+## Route to Dependency Auditor
+- Dependency health assessment
+- Vulnerability scanning and triage
+- Supply-chain risk evaluation
+- Stale package identification
+
+## Route to Security Reviewer
+- Code security review (injection, auth, secrets)
+- Threat model verification
+- OWASP pattern detection
+- Security claim validation
+
+## Route to Launch Strategist
+- Launch planning and sequencing
+- Proof packaging for launch claims
+- Channel selection and timing
+- Success criteria definition
+
+## Route to Content Strategist
+- Long-form content planning
+- Technical article and case study angles
+- Docs-to-marketing bridge
+- Content calendar development
+
+## Route to Community Manager
+- Issue and discussion triage
+- Community response drafting
+- Contribution guidance
+- Community health assessment
+
+## Route to Support Triage Lead
+- Support request classification
+- Bug vs user error distinction
+- Priority assignment
+- Recurring pattern analysis
+
+## Route to UX Researcher
+- User flow friction analysis
+- Heuristic evaluation
+- Usability issue identification
+- Evidence-based design input
+
+## Route to Competitive Analyst
+- Competitive landscape mapping
+- Differentiation assessment
+- Positioning gap identification
+- Honest disadvantage acknowledgment
+
+## Route to Trend Researcher
+- Technology and market trend analysis
+- Ecosystem signal assessment
+- Risk and opportunity identification
+- Adoption timing recommendations
+
+## Route to User Interview Synthesizer
+- Interview theme extraction
+- Mental model mapping
+- Unmet needs ranking
+- Sample-aware confidence assessment

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

@@ -0,0 +1,134 @@
+# Tool Permissions
+
+Each role should use the minimum tools needed.
+
+## Orchestrator
+May read all task packets, handoffs, policies, and context.
+Must not perform specialist work unless explicitly acting as fallback.
+
+## Product Strategist
+May read context, plans, briefs, feedback, metrics.
+Must not write implementation code.
+
+## UI Designer
+May read product brief, repo map, brand rules, UI files.
+May propose component structure.
+Must not invent backend behavior.
+
+## Frontend Developer
+May edit UI/client files.
+Must not redefine product scope or backend contracts without escalation.
+
+## Backend Engineer
+May edit server/data files.
+Must not silently change public contracts without surfacing impact.
+
+## Test Engineer
+May add or revise tests and verification notes.
+Must not declare product direction.
+
+## Launch Copywriter
+May write copy and messaging artifacts.
+Must not invent product capabilities.
+
+## Critic Reviewer
+May read all outputs and reject them.
+Must not rewrite the work except for small clarifying examples.
+
+## Repo Researcher
+May read all repo files, run build/test commands, inspect structure.
+Must not modify code or make product decisions.
+
+## Repo Translator
+May read finalized docs and write translated versions.
+Must not modify source content or invent claims not in the original.
+
+## Docs Architect
+May read product brief, README, repo map, and existing docs.
+May create and edit documentation files and site configuration.
+Must not make product decisions or change application code.
+
+## Metadata Curator
+May read and update package manifests, repo metadata, and badge URLs.
+Must not change application behavior or make product scope decisions.
+
+## Coverage Auditor
+May read test files, coverage output, and CI configuration.
+Must not write application code or declare product priorities.
+
+## Deployment Verifier
+May read deployed URLs, package registries, and badge endpoints.
+Must not modify deployed artifacts or make rollback decisions without escalation.
+
+## Release Engineer
+May update version numbers, changelogs, tags, and packaging.
+Must not bypass shipcheck gates or publish without confirmation.
+
+## Brand Guardian
+May read all user-facing surfaces and brand rules.
+May propose replacement terms and flag contamination.
+Must not invent new brand identity or override existing brand rules.
+
+## Feedback Synthesizer
+May read issues, reviews, support threads, and usage data.
+Must not make product decisions or commit code.
+
+## Roadmap Prioritizer
+May read priorities, backlogs, dependency information, and feedback syntheses.
+Must not implement features or override product leadership decisions.
+
+## Spec Writer
+May read product strategy output and write specification documents.
+Must not implement the spec or make product scope decisions.
+
+## Information Architect
+May read content inventories, site structures, and navigation.
+Must not create content or make visual design decisions.
+
+## Refactor Engineer
+May edit code to improve structure.
+Must not change user-visible behavior without explicit approval.
+
+## Performance Engineer
+May profile, measure, and optimize code.
+Must not optimize without measurement evidence.
+
+## Dependency Auditor
+May read manifests, lockfiles, and audit output.
+Must not update dependencies without noting compatibility risk.
+
+## Security Reviewer
+May read all source code and configuration.
+Must not modify code (report findings for others to fix).
+
+## Launch Strategist
+May read shipped evidence, product briefs, and channel information.
+Must not invent product claims or commit code.
+
+## Content Strategist
+May read shipped work, product briefs, and existing content.
+Must not create final copy (hand off to Launch Copywriter for that).
+
+## Community Manager
+May read and draft responses to issues and discussions.
+Must not make product commitments or close valid reports without evidence.
+
+## Support Triage Lead
+May read support requests and classify them.
+Must not fix bugs directly or make product direction decisions.
+
+## UX Researcher
+May read user-facing flows, feedback, and interaction patterns.
+Must not redesign (hand off findings to UI Designer).
+
+## Competitive Analyst
+May research public competitor information.
+Must not access private or proprietary competitor data.
+
+## Trend Researcher
+May research public ecosystem and market signals.
+Must not recommend trend adoption without cost assessment.
+
+## User Interview Synthesizer
+May read interview transcripts and notes.
+Must not project desired outcomes onto user words.

package/starter-pack/schemas/handoff.md

@@ -0,0 +1,52 @@
+# Handoff
+
+Use the **full format** for cross-functional features (4+ roles), integration work with compatibility risks, or any packet where the next role genuinely needs all fields. Use the **light format** for routine packets (2-3 roles, narrow scope, low risk).
+
+## Light Format (routine packets)
+```
+## [Role Name]
+**Ruling/Output:** [1-3 sentences]
+**Files:** [list if applicable]
+**Risk:** [1 sentence or "none"]
+```
+
+## Full Format
+
+## Handoff ID
+{{handoff_id}}
+
+## From Role
+{{from_role}}
+
+## To Role
+{{to_role}}
+
+## Task ID
+{{task_id}}
+
+## Status
+ready | blocked | needs-clarification | completed-with-risks
+
+## Summary
+What was done?
+
+## Artifacts
+Files changed, outputs created, tests added, docs produced.
+
+## Decisions Made
+Concrete decisions, not process narration.
+
+## Assumptions
+What was assumed?
+
+## Risks
+What could go wrong next?
+
+## Open Questions
+What still needs resolution?
+
+## Recommended Next Step
+Exactly what the receiving role should do next.
+
+## Evidence
+Verification steps, test results, screenshots, notes.

package/starter-pack/schemas/review-verdict.md

@@ -0,0 +1,26 @@
+# Review Verdict
+
+## Reviewer
+{{role_name}}
+
+## Task ID
+{{task_id}}
+
+## Verdict
+accept | accept-with-notes | reject | blocked
+
+## Why
+Short explanation tied to contract and output quality.
+
+## Contract Check
+- Scope respected?
+- Output shape complete?
+- Quality bar met?
+- Risks surfaced honestly?
+- Ready for next stage?
+
+## Required Corrections
+Only for reject or accept-with-notes.
+
+## Next Owner
+Who should act next?

package/starter-pack/schemas/task-packet.md

@@ -0,0 +1,44 @@
+# Task Packet
+
+## Task ID
+{{task_id}}
+
+## Title
+{{title}}
+
+## Requested Outcome
+What should exist or be true when this is done?
+
+## User Intent
+Why does this matter?
+
+## Scope
+What is in bounds?
+
+## Non-Goals
+What is explicitly out of bounds?
+
+## Inputs
+Files, docs, context, links, prior handoffs.
+
+**Verification requirement:** All referenced files, classes, and modules must be verified as live and relevant to the current product before the packet is finalized. If a file belongs to a fork ancestor or deprecated system, it must not appear as an input unless the task is explicitly about removing or migrating it.
+
+## Constraints
+Tech, product, legal, timeline, quality, compatibility.
+
+## Deliverable Type
+Plan | Design | Code | Test | Copy | Review
+
+## Assigned Role
+{{role_name}}
+
+## Upstream Dependencies
+What must already be true before this role should proceed?
+
+**Verification requirement:** Each dependency must be confirmed against repo truth (file exists, interface is accessible, state is reachable), not assumed from documentation or memory. If a dependency cannot be verified, mark it as `unverified` and flag for Orchestrator review before decomposition proceeds.
+
+## Done Definition
+How do we know this role completed successfully?
+
+## Open Questions
+Unknowns that may block execution.

package/starter-pack/workflows/fix-bug.md

@@ -0,0 +1,18 @@
+# Fix Bug
+
+## Sequence
+1. **Orchestrator** routes the bug report.
+2. **Product Strategist** clarifies expected correct behavior (only if needed).
+3. **Backend Engineer** or **Frontend Developer** fixes the issue (routed by domain).
+4. **Test Engineer** adds regression defense.
+5. **Critic Reviewer** verifies the fix resolves the reported issue.
+
+## Skip Rules
+- Skip Product Strategist if the correct behavior is already obvious.
+- Only one of Backend/Frontend is typically needed per bug.
+
+## Handoff Format
+Each step produces a handoff per `schemas/handoff.md`.
+
+## Done
+The workflow is done when the Critic Reviewer confirms the fix matches the reported problem and regression tests exist.

package/starter-pack/workflows/launch-update.md

@@ -0,0 +1,15 @@
+# Launch Update
+
+## Sequence
+1. **Orchestrator** confirms what is truly shipped and ready.
+2. **Launch Copywriter** drafts user-facing copy grounded in implementation truth.
+3. **Critic Reviewer** checks claims against implementation reality.
+
+## Skip Rules
+- None. All three steps are required.
+
+## Handoff Format
+Each step produces a handoff per `schemas/handoff.md`.
+
+## Done
+The workflow is done when the Critic Reviewer accepts the copy as truthful and grounded.

package/starter-pack/workflows/ship-feature.md

@@ -0,0 +1,22 @@
+# Ship Feature
+
+## Sequence
+1. **Orchestrator** receives the task and decomposes it.
+2. **Product Strategist** clarifies scope and success criteria.
+3. **UI Designer** shapes the interaction (if UI work is involved).
+4. **Backend Engineer** executes backend work (if needed).
+5. **Frontend Developer** implements user-facing behavior.
+6. **Test Engineer** verifies the result.
+7. **Critic Reviewer** accepts or rejects.
+8. **Launch Copywriter** writes release language (after acceptance).
+
+## Skip Rules
+- Skip UI Designer if the task is backend-only.
+- Skip Backend Engineer if no server changes are needed.
+- Skip Launch Copywriter if no external communication is required.
+
+## Handoff Format
+Each step produces a handoff per `schemas/handoff.md` before the next role begins.
+
+## Done
+The workflow is done when the Critic Reviewer issues an `accept` verdict and all downstream artifacts are complete.