@monoes/monomindcli 2.10.5 → 2.10.6

package/dist/src/orgrt/role-skills/product-manager.md

@@ -0,0 +1,26 @@
+# Product Manager — Best Practices
+
+## Focus
+Owns the "why" and "what" of a product: turning strategy into a prioritized roadmap, aligning stakeholders, and ensuring what ships actually solves a validated problem.
+
+## Best practices
+- Use a "Now / Next / Later" roadmap instead of fixed dates: Now is high-confidence current-cycle work, Next is the upcoming cycle's priorities, Later is validated problems not yet scheduled. Label confidence explicitly so "Later" isn't mistaken for a commitment.
+- Prioritize with an explicit framework (RICE: Reach × Impact × Confidence ÷ Effort, or MoSCoW) rather than gut feel — it gives stakeholders an auditable reason for the ranking.
+- Map stakeholders by influence vs. interest and tailor communication accordingly — not everyone needs the same depth of update.
+- When declining a request, don't just say no — show what's being prioritized instead and why it ranks higher, so the trade-off is visible.
+- Frame roadmap items as bets tied to outcomes/strategic themes, not as guaranteed deliverables — this sets the right expectation for a learning process.
+- Write requirements as verifiable outcomes ("reduce signup drop-off by X%") not just feature descriptions, so success is measurable after ship.
+- Revisit the roadmap on a fixed cadence (monthly/quarterly) and actively move items between horizons rather than letting it go stale.
+
+## Common pitfalls
+- Treating the roadmap as a fixed contract instead of a living, confidence-labeled plan — this destroys trust the first time priorities shift.
+- Prioritizing by whoever asked loudest or most recently instead of a consistent scoring method.
+- Shipping features without a clear success metric defined up front, so nobody can tell afterward if it worked.
+- Saying "no" without explaining the trade-off, which reads as dismissive and erodes stakeholder buy-in.
+- Conflating output (features shipped) with outcome (problems solved) when reporting progress.
+
+## Tools & techniques
+- RICE / MoSCoW / Value-vs-Effort scoring for backlog and roadmap prioritization.
+- Stakeholder influence/interest mapping to calibrate communication cadence and depth.
+- Now/Next/Later roadmap format with explicit confidence labels (Committed / Directional / Exploratory).
+- Outcome-based requirement writing: state the metric that defines success before scoping the solution.

package/dist/src/orgrt/role-skills/production-validator.md

@@ -0,0 +1,27 @@
+# Production Validator — Best Practices
+
+## Focus
+Confirms an application is fully implemented and deployment-ready — no mocks, stubs, or fakes remaining, and real integrations (database, APIs, infra) actually work under load.
+
+## Best practices
+- Scan for leftover mock/fake/stub patterns and "not implemented" placeholders in production code paths before sign-off
+- Test against real dependencies (actual database, actual cache, actual third-party test-mode APIs), not in-memory or mocked substitutes
+- Validate environment configuration explicitly — missing required env vars should fail loudly at startup, not surface as a runtime mystery later
+- Confirm health-check endpoints report the real status of dependencies (database connected, cache connected, external API reachable), not a hardcoded "healthy"
+- Test graceful shutdown and failure scenarios (dependency outage, timeout) — not just the success path under normal conditions
+- Measure actual performance under realistic and peak load, not just functional correctness at low volume
+- Verify security controls are live in this environment (HTTPS enforced, auth required on protected routes) rather than assuming config from another environment carried over
+
+## Common pitfalls
+- Treating "tests pass" as equivalent to "production ready" when the tests themselves run against mocks
+- Missing TODO/FIXME markers or console.log statements left in code paths that will run in production
+- Validating the deployment config exists without confirming the app actually behaves correctly when it's used
+- Load-testing with a trivial request count that doesn't reveal real bottlenecks (connection pool exhaustion, N+1 queries)
+- Skipping failure-mode testing — a system only proven under the happy path will surprise everyone the first time a dependency degrades
+
+## Tools & techniques
+- Pattern scans for mock/fake/stub markers, TODO/FIXME, and stray console statements in non-test source paths
+- Integration test suites run against real database/cache/SMTP/payment-sandbox connections instead of in-memory substitutes
+- Load and concurrency testing (sustained request rate, concurrent burst) with explicit SLA thresholds (response time, success rate)
+- Environment-variable validation at startup that fails fast on missing required config
+- Health-check endpoints that actively probe each dependency rather than returning a static "ok"

package/dist/src/orgrt/role-skills/project-shepherd.md

@@ -0,0 +1,25 @@
+# Project Shepherd — Best Practices
+
+## Focus
+Guides a creative/production project day-to-day through its lifecycle — less about big scheduling decisions, more about unblocking people, keeping momentum, and making sure nothing silently stalls.
+
+## Best practices
+- Check for stalled work daily, not weekly — a task with no movement for 2+ days is a signal, not noise.
+- Unblock before escalating: try to resolve a blocker directly (find the missing asset, the missing answer) before routing it upward.
+- Keep handoffs explicit — when work passes between people or disciplines, confirm both sides know the task moved and what "done" means for the receiver.
+- Surface risk early and small rather than late and large — a two-line flag today beats a crisis explanation next week.
+- Protect focus time for contributors — batch status questions instead of interrupting continuously.
+- Maintain lightweight, current status (not exhaustive documentation) that anyone can scan in under a minute.
+- Close the loop — when a blocker is resolved or a task completes, confirm it and update the tracker immediately, don't let it linger as "probably done."
+
+## Common pitfalls
+- Confusing activity with progress — busy channels and long threads are not the same as tasks moving to done.
+- Escalating too early (before attempting a direct unblock) or too late (after the deadline has already been missed).
+- Letting the tracker drift from reality because updates are treated as optional overhead.
+- Being the single point of context — if only the shepherd knows why a decision was made, that's a gap to close, not a convenience.
+
+## Tools & techniques
+- Daily stall-check: scan all in-progress items for missing updates or owner responses.
+- Blocker triage checklist: is this missing info, missing access, missing decision, or missing capacity? Each has a different fix.
+- Lightweight status format: what shipped, what's blocked, what's next — updated same-day, not end-of-week.
+- Dependency mapping for cross-team handoffs so a shepherd can see who's waiting on whom at a glance.

package/dist/src/orgrt/role-skills/proposal-strategist.md

@@ -0,0 +1,26 @@
+# Proposal Strategist — Best Practices
+
+## Focus
+Shapes and writes competitive proposals and RFP responses — turning a pile of requirements into a persuasive, differentiated case for why this vendor is the only logical choice.
+
+## Best practices
+- Make a disciplined go/no-go call before investing effort — chasing every RFP dilutes win rate and burns proposal-team capacity on unwinnable deals.
+- Develop win themes immediately after go/no-go, not at the end — they should drive the executive summary, solution narrative, proof points, and pricing, not be bolted on last.
+- Choose 3-5 win themes max, each tied directly to what the evaluator actually cares about — themes should explain why your approach is the obvious choice, not just list capabilities.
+- Read the RFP thoroughly before drafting; meeting every mandatory requirement explicitly is a gating factor before persuasion even matters.
+- Lead the executive summary with the buyer's goals and priorities, then your solution, then a quantified outcome — put at least one hard number in the opening.
+- Tailor every response to the specific buyer's situation — generic boilerplate proposals are now actively penalized by buyers who expect demonstrated understanding of their context.
+- Make differentiation explicit and comparative, not implicit — state directly what sets you apart from likely alternatives.
+- Keep the executive summary tight (roughly 3-5% of total response length) — buyers and evaluators skim; the summary has to stand alone.
+
+## Common pitfalls
+- Treating the proposal as a documentation exercise (answer every question literally) instead of a persuasion exercise built around win themes.
+- Reusing generic boilerplate content that doesn't reference the buyer's specific situation, industry, or stated priorities.
+- Missing or glossing over mandatory requirements, which can disqualify an otherwise strong proposal outright.
+- Burying differentiation in feature lists instead of stating clearly and confidently why this solution wins against the likely alternatives.
+
+## Tools & techniques
+- Win-theme worksheet completed right after go/no-go, referenced throughout drafting to keep the narrative consistent.
+- Requirements traceability matrix to confirm every mandatory item is explicitly addressed.
+- Executive summary structure: buyer goal → solution → quantified outcome → win themes, in that order.
+- Proposal content library (case studies, proof points, boilerplate) tagged by industry/use case for fast, relevant reuse — not indiscriminate copy-paste.

package/dist/src/orgrt/role-skills/prosecutor.md

@@ -0,0 +1,25 @@
+# Prosecutor — Best Practices
+
+## Focus
+Builds and presents the case against a party, bearing the full burden of proving the claim beyond a reasonable doubt (or the applicable standard) while staying within ethical limits — the prosecutor's job is to seek a just outcome, not merely to win.
+
+## Best practices
+- Build the case around a single convincing narrative: identify the story that ties every piece of evidence to the alleged wrongdoing, then support each beat with admissible evidence.
+- Know your burden precisely and don't overstate it — never imply the defense must prove innocence; the burden never shifts.
+- Disclose exculpatory or mitigating evidence proactively, even when it weakens the case — suppression is both unethical and strategically self-defeating on appeal.
+- Pressure-test your own case before presenting it: identify the weakest links, alternative explanations, and chain-of-custody or credibility gaps an opponent will exploit.
+- Charge/argue only what the evidence actually supports — do not overcharge or overstate confidence to gain negotiating leverage.
+- Anticipate defense theories and prepare rebuttals in advance rather than reacting live.
+- Use precise, evidence-grounded language in closing — avoid rhetorical appeals that misstate the standard of proof.
+
+## Common pitfalls
+- Treating "vigorous" as synonymous with "misleading" — implying the defense has something to prove.
+- Withholding or downplaying inconvenient facts instead of confronting them head-on.
+- Relying on a single strong piece of evidence while leaving the surrounding narrative thin.
+- Failing to distinguish between what is provable and what is merely plausible.
+
+## Tools & techniques
+- Evidence-to-element mapping: for each required element of the claim, list the specific evidence that supports it — flag any element with a gap.
+- Steelmanning the opposition: draft the strongest plausible defense argument before finalizing your own case theory.
+- Chain-of-reasoning audits: verify every inference in the narrative is supported by cited evidence, not assumption.
+- Standard-of-proof checks: before asserting guilt/liability, explicitly confirm the evidence clears the applicable threshold, not just "more likely than not" when a higher bar applies.

package/dist/src/orgrt/role-skills/queen-coordinator.md

@@ -0,0 +1,25 @@
+# Queen Coordinator — Best Practices
+
+## Focus
+Same shape as a lead coordinator — decompose, delegate, hold authoritative state, decide when done — but scoped to a single bounded session with workers that report directly up to it and nowhere else.
+
+## Best practices
+- Own the single source of truth for the session: what's in-progress, blocked, done, and reconciled. Worker reports are inputs to that state, not the state itself.
+- Decompose the session's objective into subtasks with one accountable worker and explicit acceptance criteria each before dispatching anything.
+- Route by capability — match each subtask to the worker actually suited for it rather than whichever worker is idle.
+- Apply the session's approval policy before accepting a deliverable; block anything that fails acceptance criteria with specific, actionable feedback rather than accepting to keep moving.
+- Detect drift early and re-scope immediately — a worker diverging from the session goal costs more the longer it's left uncorrected.
+- Close the session explicitly: reconcile all final worker state into one authoritative record before declaring done, not just when the last worker happens to report in.
+
+## Common pitfalls
+- Treating "queen" as implying capabilities the session doesn't actually have — no background timers, no session succession, no automatic redistribution based on inferred worker load. If something must outlive the session, persist it before returning; nothing carries it forward automatically.
+- Rubber-stamping the last worker report instead of reconciling all reports into consistent authoritative state.
+- Letting two workers silently take overlapping scope because delegation wasn't explicit about boundaries.
+- Describing the session as achieving "consensus" or being "fault tolerant" when it was actually one coordinator making decisions — nothing tolerated a fault, no vote was tallied.
+- Scoping the session too broadly, so "queen" coordination is really trying to run a whole hierarchical org through one session instead of one bounded unit of work.
+
+## Tools & techniques
+- Dispatch independent worker tasks in a single batch — that's the only source of real concurrency; the queen doesn't grant parallelism by existing, the dispatch mechanism does.
+- Keep session state (roster, task assignments, acceptance status) in one inspectable place so reconciliation is a read, not a reconstruction.
+- Use an explicit vote/threshold mechanism (not the queen's own judgment) for any decision that genuinely needs multiple workers to agree — don't conflate "queen decides" with "workers voted."
+- Route synthesis-across-workers to a knowledge-consolidation step distinct from task routing — deciding who does what and reconciling what they collectively learned are different jobs, even in one session.

package/dist/src/orgrt/role-skills/quorum-manager.md

@@ -0,0 +1,25 @@
+# Quorum Manager — Best Practices
+
+## Focus
+Runs vote tallies over participating agents' votes and decides whether a proposal has met an explicit threshold — this is vote counting, not distributed consensus with leader election or fault tolerance.
+
+## Best practices
+- Establish the participant set before tallying anything — the denominator for any threshold is the current roster; state it explicitly rather than inferring it from however many votes happened to arrive.
+- Name the threshold strategy explicitly for every decision: majority (floor(n/2)+1), supermajority (floor(2n/3)+1), unanimous (n), or a caller-supplied custom threshold — don't leave it implicit.
+- Treat each vote as a boolean from one identified roster member; don't accept an unweighted "sentiment" in place of an actual cast vote.
+- Flag the same voter casting opposite votes across two still-pending proposals of the same type — that's a genuine double-vote signal worth surfacing, even in a single-process tally.
+- Write the decision through a tamper-evident audit path (signed record) so it can be independently re-verified later, not just trusted at decision time.
+- Report the raw split (e.g. "4 of 6 approved") alongside the required threshold — the number alone without the threshold it was measured against is not a decision record.
+
+## Common pitfalls
+- Describing a vote tally as "consensus" or "fault-tolerant" when it's a threshold count in a single process — no leader election, no log replication, no Byzantine tolerance actually happened.
+- Extrapolating a decision from partial participation — if votes are missing, report the decision as blocked on incomplete participation rather than assuming the missing votes would have gone a particular way.
+- Silently changing the participant roster mid-tally (an agent joins or leaves) without re-stating the new denominator.
+- Using "gossip" or "CRDT" language for what's actually a synchronous vote collection with no network-partition tolerance — name the mechanism that exists, not one that sounds more sophisticated.
+- Skipping the audit write on low-stakes decisions — a decision without a recorded trail can't be disputed or verified later even if it turns out to matter.
+
+## Tools & techniques
+- Check the current roster immediately before tallying, not from a cached count that may be stale.
+- Compute the required-votes threshold from the chosen strategy programmatically rather than eyeballing it — off-by-one errors in majority/supermajority math are easy to make by hand.
+- Record decisions with an HMAC-signed or similarly tamper-evident record so `verify` can later detect any alteration.
+- Keep a duplicate-vote check scoped to same-type pending proposals — broader duplicate detection tends to produce false positives across unrelated decisions.

package/dist/src/orgrt/role-skills/raft-manager.md

@@ -0,0 +1,25 @@
+# Raft Manager — Best Practices
+
+## Focus
+Maintains a single authoritative, replicated log across participants via leader election and log replication — consensus under crash/omission faults, not malicious ones.
+
+## Best practices
+- Keep the three subproblems separate in reasoning and implementation: leader election, log replication, and safety. Raft's whole value is that each is tractable in isolation — don't blur them together.
+- Use randomized election timeouts so followers don't all become candidates simultaneously; without randomization, split votes recur and elections stall.
+- Only mark a log entry committed once it's replicated to a majority of servers — never apply an entry to the state machine before that majority is confirmed.
+- Give every client operation an idempotency key (e.g. a sequence number) so re-execution from the log after a leader change or retry can't double-apply it.
+- Persist term number and vote state to stable storage before responding to any RPC — a node that forgets its term or vote across a restart can violate safety.
+- Never let a leader with a stale term keep acting as leader; step down immediately on discovering a higher term from any peer.
+
+## Common pitfalls
+- Conflating consensus, coordination, and replication — consensus is agreeing on a single ordered log; coordination (e.g. distributed locks) is a use case built on top of it; replication just copies data without ordering guarantees on its own. Building one where the problem actually needs another is a common design error.
+- Relying on wall-clock time without accounting for clock issues — NTP slews or a backward time jump can break election-timeout assumptions and cause spurious elections or missed heartbeats.
+- Treating "leader elected" as "state agreed" — a new leader must still catch followers up to the latest committed entry before the cluster is actually consistent.
+- Skipping snapshotting/log compaction on long-running clusters, letting the replicated log grow unbounded and making new-node catch-up impractically slow.
+- Applying an Raft-replicated decision as though it also tolerates malicious participants — Raft assumes honest-but-possibly-crashed nodes; it gives no protection against a node that lies.
+
+## Tools & techniques
+- Verify committed status by checking replication count against cluster majority explicitly, not by trusting the leader's local view alone.
+- Attach a monotonic operation id to every client request so re-application from the log is detectable and skippable.
+- Test explicitly for split-brain scenarios (partitioned leader still receiving client writes) — the term/quorum mechanism should make the partitioned leader's writes unable to commit, verify that it actually does.
+- Log every term change and leader transition; when debugging a consistency issue, the term/log-index history is almost always where the answer is.

package/dist/src/orgrt/role-skills/reality-checker.md

@@ -0,0 +1,27 @@
+# Reality Checker — Best Practices
+
+## Focus
+Independently verifies that a reported outcome matches ground truth — catching agents or teammates that report success without having actually confirmed it.
+
+## Best practices
+- Re-run the actual verification yourself (the test, the build, the query) rather than trusting a summary of results someone else produced
+- Treat any claim of "zero issues," a perfect score, or "production ready" on a first pass as a signal to dig deeper, not as good news to accept
+- Check ground-truth sources directly — logs, database state, live output — instead of relying on an agent's self-report of what it did
+- Quote the original requirement/spec next to the observed outcome; "seems fine" isn't a comparison, it's a guess
+- When something can't be verified (no evidence, no access, ambiguous result), say so explicitly rather than assuming success by default
+- Distinguish "the code exists" from "the code runs correctly" from "the code was actually exercised by this test" — all three are different claims
+- Flag discrepancies between what was claimed and what was found immediately and specifically, with the exact mismatch named
+
+## Common pitfalls
+- Accepting a status report at face value because it's detailed and confident-sounding — confidence isn't evidence
+- Checking that something *could* work (code review only) instead of confirming it *did* work (execution/observation)
+- Letting time pressure shortcut verification — "probably fine" reports are exactly what this role exists to catch
+- Verifying the happy path someone already tested and skipping the parts most likely to have been skipped by the original claim
+- Softening a "this doesn't match what was reported" finding into ambiguous language that lets the discrepancy slide
+
+## Tools & techniques
+- Direct re-execution of tests/builds/queries rather than trusting logs or summaries produced by the party being checked
+- Ground-truth inspection: database rows, actual file contents, live network calls — not the description of what those should contain
+- Spec-vs-observed comparison tables that force an explicit match/mismatch verdict per requirement
+- Independent tooling separate from what the original implementer used, to avoid inheriting the same blind spot
+- A default-skeptical stance: unverified claims are treated as unconfirmed, not as true until disproven

package/dist/src/orgrt/role-skills/recruitment.md

@@ -0,0 +1,25 @@
+# Recruitment — Best Practices
+
+## Focus
+Sources, screens, and moves candidates through a hiring pipeline — for technical or general roles — balancing speed, candidate experience, and signal quality.
+
+## Best practices
+- Write the role spec (must-haves vs nice-to-haves, leveling, success criteria) before sourcing starts — vague requirements produce vague pipelines.
+- Prioritize referrals and warm channels alongside outbound — referred candidates convert faster and with better signal than cold outreach alone.
+- Be explicit and fast with candidates: tell them what stage they're at, what's next, and when they'll hear back — silence is the top driver of candidate drop-off.
+- Screen for evidence, not credentials alone — real projects, specific examples, and work samples beat pedigree as a signal.
+- Keep interview stages few and purposeful — each stage should test something the previous one didn't, not repeat it.
+- Debrief immediately after each interview while detail is fresh, using structured notes tied to the role's actual requirements.
+- Track pipeline conversion by stage (applied -> screened -> interviewed -> offer -> accepted) to find where candidates are actually being lost.
+
+## Common pitfalls
+- Sourcing in volume without a clear spec, producing a pipeline that "sounds right" but doesn't map to what the role needs.
+- Letting candidates go silent between stages — slow or vague follow-up loses strong candidates to faster processes elsewhere.
+- Over-indexing on credentials/pedigree instead of concrete evidence of the actual skill needed.
+- Treating every interview stage as pass/fail on "vibes" instead of structured, comparable signal.
+
+## Tools & techniques
+- Structured interview scorecards tied to specific role requirements, filled out immediately post-interview.
+- Funnel/conversion tracking by stage to diagnose where the pipeline leaks.
+- Sourcing channel mix: referrals, community platforms (GitHub, technical forums), and targeted outbound — not one channel alone.
+- Fast feedback loops (same-day or next-day updates to candidates) as a default SLA, not an exception.

package/dist/src/orgrt/role-skills/release-manager.md

@@ -0,0 +1,26 @@
+# Release Manager — Best Practices
+
+## Focus
+Coordinate version bumps, changelogs, and deployment across one or more packages so releases are predictable, tested, and reversible.
+
+## Best practices
+- Follow semantic versioning strictly: major for breaking changes, minor for backward-compatible features, patch for fixes — and document the reasoning when it's ambiguous.
+- Keep a real changelog updated per release, not generated after the fact from vague memory — write it as you go.
+- In a monorepo, coordinate version bumps across dependent packages together; a consumer package must never ship pinned to a version of its dependency that doesn't exist yet.
+- Run the full validation pipeline (install, test, lint, build) before cutting a release branch, and again before tagging.
+- Stage releases (dev → staging → prod, or canary → full) rather than big-bang deploys to production.
+- Always have a documented rollback path before you ship — know exactly how to revert before you need to.
+- Communicate release contents and breaking changes clearly to consumers ahead of the release, not buried in a commit message.
+
+## Common pitfalls
+- Bumping only the top-level package version while leaving inconsistent internal dependency versions across a monorepo.
+- Treating "tests passed once" as sufficient — re-validate on the actual release branch/commit, not an earlier one.
+- Skipping the changelog because "the PR titles say it all" — PR titles aren't written for end users.
+- No rollback plan, discovered only after a bad release is already affecting users.
+- Releasing on a Friday afternoon with no one available to respond if it breaks.
+
+## Tools & techniques
+- Semantic versioning + conventional commits to auto-derive version bumps and changelog entries.
+- `npm version`/`npm publish` (or workspace-aware equivalents) for consistent, scriptable version bumps.
+- Release branches with a required validation gate (tests, lint, build) before merge to main/tag.
+- Tagged releases with generated release notes (`gh release create`) so every version is traceable to its diff.

package/dist/src/orgrt/role-skills/repo-architect.md

@@ -0,0 +1,25 @@
+# Repo Architect — Best Practices
+
+## Focus
+Design and maintain repository structure — directory layout, package boundaries, templates, and cross-repo conventions — so the codebase stays navigable and scalable as it grows.
+
+## Best practices
+- Keep a consistent directory convention across packages (e.g. `src/`, `tests/`, `docs/`) so any contributor can navigate a new package by pattern-matching an existing one.
+- Define clear package boundaries with explicit dependency direction — avoid circular dependencies between packages.
+- Standardize config files (lint, tsconfig, CI workflow) via shared base configs rather than copy-pasted per-package variants that drift.
+- Use issue/PR templates so every contribution starts with the right structure instead of ad hoc reports.
+- Document architectural decisions (why this package boundary, why this dependency direction) in one discoverable place, updated as decisions change.
+- When proposing a restructure, provide a migration path (codemod, phased move) — never just declare the new layout and leave existing code broken.
+- Keep root-level clutter minimal; anything not essential at the repo root belongs in a named subdirectory.
+
+## Common pitfalls
+- Proposing sweeping restructures without checking what currently depends on the paths being moved.
+- Creating "flexible" structure with no real convention, so every package ends up organized differently anyway.
+- Introducing a new package without updating the shared templates/workflows, so it silently diverges from day one.
+- Letting cross-repo templates drift out of sync because updates only get pushed to one repo.
+
+## Tools & techniques
+- Dependency graphs (import graph, package dependency graph) to verify no circular or layer-violating dependencies before approving a structure change.
+- Shared/base config files with per-package overrides, not full duplication.
+- A documented monorepo package pattern (role, dependencies, what it provides) so new packages fit an established shape.
+- `.github/ISSUE_TEMPLATE` and `PULL_REQUEST_TEMPLATE.md` kept in sync across related repos.

package/dist/src/orgrt/role-skills/researcher.md

@@ -0,0 +1,27 @@
+# Researcher — Best Practices
+
+## Focus
+Investigates a codebase, technology, or question thoroughly and synthesizes findings into evidence-backed, actionable recommendations for other roles to act on.
+
+## Best practices
+- Start broad, then narrow — get the lay of the land before diving into specific files or sources.
+- Read enough of a file/source to understand context, not just the first match; snippets out of context mislead.
+- Cross-reference multiple sources (code, docs, commit history, issue trackers) before drawing a conclusion.
+- Distinguish clearly between verified fact, inference, and open question in the output.
+- Trace dependencies and relationships (who calls this, what does it import) not just isolated definitions.
+- Synthesize into a structured summary with concrete recommendations — raw findings dumped without synthesis aren't useful to downstream agents.
+- Note gaps and unknowns explicitly rather than silently filling them with assumption.
+- Cite specific file paths / line numbers / sources so claims are independently checkable.
+
+## Common pitfalls
+- Stopping at the first plausible answer instead of verifying it against a second source.
+- Presenting speculation as fact, especially about "why" something was built a certain way.
+- Producing an unstructured wall of findings instead of a synthesized, prioritized summary.
+- Re-deriving something already documented instead of checking existing docs/ADRs first.
+- Ignoring negative results (what *wasn't* found) which are often as informative as positive ones.
+
+## Tools & techniques
+- Prefer structured code-graph/search tools over raw grep when available — they return context (callers, imports), not just text matches.
+- Use git log/blame to understand *why* code evolved the way it did, not just its current state.
+- Keep a running scratch list of open questions, and explicitly resolve or flag each before finishing.
+- When evaluating technology choices, compare against the project's actual constraints, not generic "best practice" claims.

package/dist/src/orgrt/role-skills/resource-allocator.md

@@ -0,0 +1,28 @@
+# Resource Allocator — Best Practices
+
+## Focus
+Plans and adjusts compute/agent capacity ahead of demand — predicting resource needs from workload patterns and allocating (or scaling) accordingly, rather than reacting after saturation.
+
+## Best practices
+- Analyze workload patterns (temporal, seasonal, growth trend) before allocating, rather than provisioning to a single peak-load snapshot.
+- Scale gradually with a rollout plan, not an instant jump to the predicted target — abrupt reallocation risks destabilizing running work.
+- Set a confidence threshold on predictions (e.g. only act on forecasts with >85% validated accuracy) and fall back to reactive scaling below it.
+- Optimize for multiple objectives explicitly (latency, utilization, cost, fairness) rather than a single metric that ignores trade-offs.
+- Build in headroom for volatility, not just the expected/average case — allocate based on p90+ demand, not the mean.
+- Monitor allocation efficiency after the fact (utilization rate, waste percentage) and feed it back into the next planning cycle.
+- Isolate resource pools per workload class (bulkhead pattern) so one saturated pool can't starve the others.
+- Prefer under-provisioning with fast reactive scale-up over static over-provisioning, when the workload's growth is unpredictable.
+
+## Common pitfalls
+- Allocating to the historical peak without accounting for growth trend, so the plan is already stale by the time it's applied.
+- Optimizing a single objective (e.g. minimize cost) while ignoring the resulting latency or reliability regression.
+- No rollback/rollout plan — a bad allocation decision is applied all at once instead of incrementally and reversibly.
+- Ignoring correlation between resources (e.g. CPU and memory pressure moving together) and allocating each independently.
+- Trusting a predictive model's output without validating its accuracy against held-out data first.
+
+## Tools & techniques
+- Time-series forecasting (trend + seasonality decomposition) over historical utilization to project near-term demand.
+- Multi-objective optimization (e.g. Pareto-front analysis) when latency, cost, and utilization pull in different directions.
+- Bulkhead + circuit-breaker patterns for resource pool isolation and fault containment.
+- Percentile-based capacity planning (provision for p90/p95 demand, not average) to absorb normal volatility without waste.
+- Allocation KPIs — utilization rate, waste percentage, prediction accuracy, scaling response time — tracked per cycle to validate the forecasting model over time.

package/dist/src/orgrt/role-skills/reviewer.md

@@ -0,0 +1,27 @@
+# Code Reviewer — Best Practices
+
+## Focus
+Reviews code for correctness, security, maintainability, and performance — teaching through feedback, not gatekeeping style preferences.
+
+## Best practices
+- Verify functionality first: does it meet requirements, handle edge cases, and cover error scenarios?
+- Check security explicitly: input validation, output encoding, auth/authz checks, injection risks (SQL, XSS), secret handling.
+- Look for performance red flags: N+1 queries, unnecessary loops/allocations, missing caching, unbounded operations.
+- Assess maintainability: naming clarity, SOLID/DRY/KISS adherence, testability, dependency injection over hardwired globals.
+- Be specific and cite line numbers/examples — "SQL injection risk on line 42" not "security issue."
+- Explain the *why* behind every requested change, and suggest rather than dictate ("consider X because Y").
+- Prioritize findings by severity (blocker / suggestion / nit) so authors know what's must-fix vs. optional.
+- Acknowledge good patterns and clever solutions, not just problems.
+
+## Common pitfalls
+- Nitpicking style that a linter should catch, while missing an actual security or correctness bug.
+- Vague feedback ("this looks off") that gives the author nothing actionable.
+- Reviewing in scattered rounds instead of delivering complete feedback in one pass.
+- Blocking on personal preference rather than an objective correctness/security/maintainability concern.
+- Skipping the "why" and just prescribing a fix, which teaches nothing and invites pushback.
+
+## Tools & techniques
+- Run automated lint/test/security-scan tools first; spend human judgment on what tools can't catch.
+- Use a checklist (functionality, security, performance, quality, maintainability) to stay consistent across reviews.
+- Keep individual reviews scoped (~400 lines or less) — large diffs get rubber-stamped, not reviewed.
+- Trace suspicious data flows end-to-end (user input → storage → output) rather than reviewing lines in isolation.

package/dist/src/orgrt/role-skills/safe-executor.md

@@ -0,0 +1,27 @@
+# Safe Executor — Best Practices
+
+## Focus
+Runs untrusted or agent-generated code without letting it touch the host, adjacent workloads, or secrets — the last line of defense when code execution itself is the feature.
+
+## Best practices
+- Never run untrusted code with shared-kernel containers (plain Docker/runc) as the only isolation — the minimum acceptable boundary is a microVM (Firecracker/Kata) or a syscall-intercepting sandbox (gVisor)
+- Enforce hard resource limits on every execution: wall-clock timeout, CPU, memory ceiling, and process/thread count cap — a runaway process should die, not degrade the host
+- Deny network access by default; grant only the specific egress a task actually needs, and never expose the host's internal network or metadata endpoints
+- Isolate the filesystem per execution — no access to host files, other executions' artifacts, or secrets; mount only what the task explicitly needs, read-only where possible
+- Never interpolate untrusted input directly into a shell command string — use exec-family calls with argument arrays, not `sh -c` string concatenation
+- Treat the sandbox boundary as the trust boundary: validate what comes back out (stdout, files, return values) just as carefully as what goes in
+- Destroy and recreate the execution environment between runs — don't reuse a "cleaned" sandbox for the next job
+
+## Common pitfalls
+- Assuming a container is a security boundary when it shares the host kernel — container escape techniques target exactly this gap
+- Building command strings via string concatenation/interpolation, opening the door to shell injection even when input was "validated" upstream
+- Setting generous timeouts/limits "to be safe" that in practice let a malicious or buggy process consume the host for minutes
+- Granting outbound network access broadly ("just in case the code needs an API") instead of scoping it to the specific need
+- Logging or returning raw stack traces/environment details from inside the sandbox, leaking host configuration to the executed code's output
+
+## Tools & techniques
+- MicroVM isolation (Firecracker, Kata Containers) or gVisor as the baseline for untrusted execution; plain containers only for code you already trust
+- WebAssembly runtimes for deterministic, memory-safe execution when the workload fits (no native syscalls needed)
+- cgroups/rlimits (or the sandbox platform's equivalent) for CPU, memory, and process-count enforcement
+- Network policy/egress allowlisting at the sandbox network namespace level, not just application-level checks
+- Ephemeral, single-use sandbox instances torn down after each execution rather than long-lived reusable ones

package/dist/src/orgrt/role-skills/sales-coach.md

@@ -0,0 +1,26 @@
+# Sales Coach — Best Practices
+
+## Focus
+Improves rep performance through structured, ongoing coaching — call reviews, skill-building, and habit reinforcement — rather than one-off feedback or deal rescue.
+
+## Best practices
+- Run a consistent weekly loop: review a call against a rubric, identify one or two coachable moments, co-create a fix with the rep, schedule the follow-up review.
+- Coach one or two specific skills per session, not a laundry list of everything that went wrong — focus compounds, noise dilutes.
+- Separate coaching time from pipeline/deal-review time; mixing the two turns coaching into deal interrogation and reps disengage.
+- Adapt coaching style to the rep's skill level and confidence (situational coaching) rather than applying one method to everyone.
+- Coach in the moment where possible — right after a call, during a live pipeline review, or shadowing a customer conversation — not weeks later from memory.
+- Build and maintain an objection-handling library from real call reviews: track recurring objections, document how top performers respond, and standardize the response.
+- Use a defined framework (e.g., GROW: Goal, Reality, Options, Will) to structure 1:1 coaching conversations so they produce a concrete next action, not just discussion.
+- Track whether coaching is actually changing behavior on subsequent calls — coaching that doesn't show up in later performance isn't working.
+
+## Common pitfalls
+- Giving generic "good job, keep it up" feedback instead of specific, actionable, skill-level observations tied to what happened on the call.
+- Trying to fix everything at once in a single session, overwhelming the rep and producing no lasting change.
+- Coaching only underperformers while ignoring mid-tier reps who have the most room for incremental, high-leverage improvement.
+- Treating coaching as a compliance checkbox (logged but not followed up) instead of a loop with accountability for the next call.
+
+## Tools & techniques
+- Call scorecards/rubrics aligned to the team's sales methodology (MEDDIC, SPIN, etc.) for objective, repeatable review.
+- Conversation intelligence tools to surface coachable moments (talk ratio, objection handling, question quality) at scale.
+- GROW model (or similar) as the structural skeleton for every 1:1 coaching conversation.
+- Objection library maintained and updated from real call transcripts, shared across the team.

package/dist/src/orgrt/role-skills/sales-engineer.md

@@ -0,0 +1,26 @@
+# Sales Engineer — Best Practices
+
+## Focus
+Bridges product capability and customer need during the technical sales cycle — running discovery, demos, and POCs that prove a solution actually solves the buyer's problem, not just that it has features.
+
+## Best practices
+- Know the customer as well as the product: their stack, pain points, industry constraints, and competitive alternatives before the first technical conversation.
+- Treat discovery as collaborative diagnosis, not a checklist — dig into why a requirement exists before proposing how to meet it.
+- Tailor every demo to the specific pain points surfaced in discovery; never run the generic canned demo.
+- Front-load the outcome in demos — show the payoff first, then the mechanism. Keep each section under ~3 minutes so attention doesn't drift.
+- Scope POCs tightly: agree success criteria, timeline, and required resources with the champion in writing before starting.
+- Build and reuse a library of objection responses and reference architectures instead of improvising technical answers live.
+- Loop in engineering/product early on anything that looks like a gap — don't let the customer discover it during the POC.
+- Debrief every lost or stalled technical evaluation to capture what broke down (fit, timing, competitor differentiation) and feed it back into the playbook.
+
+## Common pitfalls
+- Demoing every feature instead of the 2-3 that map to the customer's stated problem — this dilutes the pitch and signals no preparation.
+- Answering technical questions with unqualified promises instead of "let me confirm and follow up," creating delivery risk downstream.
+- Skipping written success criteria on a POC, which lets a stalled evaluation drag on indefinitely with no forcing function.
+- Treating the SE role as purely technical support instead of a co-owner of the deal outcome — disengaging once the "cool demo" is done.
+
+## Tools & techniques
+- Discovery-to-demo mapping: every demo section should trace back to a specific pain point named by the customer.
+- POC scorecards with explicit pass/fail criteria agreed upfront, reviewed jointly at the end.
+- Objection library: a maintained doc of common technical objections and vetted responses, updated after each competitive loss.
+- Reference architecture diagrams tailored per vertical/use case for fast credibility in technical conversations.

package/dist/src/orgrt/role-skills/scout-explorer.md

@@ -0,0 +1,25 @@
+# Scout Explorer — Best Practices
+
+## Focus
+Explores unfamiliar territory — a codebase, a dependency tree, an unknown system — and reports back concrete, actionable findings without acting on them itself.
+
+## Best practices
+- Scope the reconnaissance target explicitly before starting (codebase, docs, dependencies, performance) so the search doesn't wander without a stopping point.
+- Report discoveries as they're confirmed, not batched at the very end — a critical finding sitting unreported until task completion defeats the point of scouting.
+- Distinguish verified findings from suspicions — say plainly when something looks like an issue but hasn't been confirmed, rather than reporting a guess as fact.
+- Prioritize findings by actual severity/impact, not by order discovered — a critical security issue found last still gets reported first.
+- Give findings a precise location (file:line, module, dependency name) so whoever acts on the report doesn't have to re-derive it.
+- Cover breadth first when the territory is unknown, then go deep only on the areas that matter — a scout that goes deep immediately on the first thing it finds may miss the bigger picture.
+
+## Common pitfalls
+- Modifying what's discovered instead of just reporting it — a scout's job ends at the finding, not the fix.
+- Duplicating another scout's coverage because exploration boundaries weren't agreed on first.
+- Reporting a raw dump of everything observed instead of triaged, actionable intelligence — volume isn't the same as usefulness.
+- Treating "explored 85% of the codebase" as meaningful without saying what the other 15% was or why it wasn't covered.
+- Alerting on a threat without also giving a concrete, specific mitigation — "there's a vulnerability" without a location and fix path isn't actionable.
+
+## Tools & techniques
+- Use codebase-graph/search tools before manual grep-style exploration when one is available — it's faster and gives file+line precision immediately.
+- Keep a running map of what's been covered vs. not, so coverage can be reported honestly rather than estimated.
+- Classify each finding by category (threat, opportunity, information) and severity so the report can be triaged at a glance.
+- Report the negative result too — "explored X, found nothing notable" is still useful information and prevents redundant re-exploration.

package/dist/src/orgrt/role-skills/security-architect.md

@@ -0,0 +1,27 @@
+# Security Architect — Best Practices
+
+## Focus
+Designs security into systems before they're built — threat models, trust boundaries, zero-trust architecture, and authn/authz patterns — so vulnerabilities never get a chance to ship.
+
+## Best practices
+- Threat-model every new component with STRIDE (or equivalent) before implementation, not after — identify trust boundaries, data classification, and attack surface up front
+- Default to deny: least-privilege access control, allowlists over blocklists, explicit grants over implicit trust
+- Design defense-in-depth — no single control (a WAF, an auth check) should be the only thing standing between an attacker and sensitive data
+- Prefer well-tested libraries and platform primitives (OAuth 2.0/OIDC, KMS-backed encryption) over custom cryptography or homegrown auth
+- Treat secrets as first-class architecture concerns: centralized secrets management, rotation policy, and zero secrets in code, logs, or config
+- Build security requirements into the SDLC as testable acceptance criteria, not a review-gate afterthought
+- Document trust boundaries explicitly in every design doc — where does untrusted input enter, and what validates it there
+
+## Common pitfalls
+- Bolting security on after the architecture is finalized instead of shaping the architecture around it
+- Designing auth/authz systems from scratch when a proven standard (OIDC, RBAC/ABAC libraries) would do
+- Treating "internal network" or "behind the VPN" as a substitute for authentication and authorization
+- Over-engineering security for the actual risk profile — a zero-trust mesh for an internal admin tool nobody attacks is wasted effort
+- Leaving error messages, stack traces, or verbose logs that leak internal architecture to unauthenticated callers
+
+## Tools & techniques
+- STRIDE / DREAD threat modeling frameworks for structured risk analysis
+- Architecture Decision Records (ADRs) to capture *why* a security control was chosen, so it isn't silently removed later
+- SAST/DAST/SCA tooling wired into CI (Semgrep, Trivy, Gitleaks) as a safety net for the architecture's assumptions
+- Security headers and CSP as the last line of defense for web surfaces (X-Frame-Options, Strict-Transport-Security, Content-Security-Policy)
+- Reference architecture patterns: OAuth 2.0/OIDC for identity, mTLS or service mesh for service-to-service trust, envelope encryption for data at rest

package/dist/src/orgrt/role-skills/security-auditor.md

@@ -0,0 +1,27 @@
+# Security Auditor — Best Practices
+
+## Focus
+Independently assesses existing code and systems for exploitable vulnerabilities, evidences findings with severity and remediation, and verifies fixes actually close the gap.
+
+## Best practices
+- Review against a known checklist (OWASP Top 10, CWE Top 25) rather than ad hoc impressions — repeatability matters more than intuition
+- Classify every finding by severity and exploitability (Critical/High/Medium/Low/Informational) with concrete impact, not vague risk language
+- Pair every vulnerability with a specific, actionable remediation — a finding without a fix is just anxiety
+- Verify authentication and authorization on every endpoint explicitly; assume nothing is protected until proven otherwise
+- Test input validation and output encoding at every trust boundary — injection (SQLi, XSS, SSRF) findings recur because these are checked inconsistently
+- Confirm fixes with re-testing, not by trusting the developer's description of the fix
+- Scope the audit boundary explicitly (what's in, what's out) before starting — undefined scope produces both false confidence and missed coverage
+
+## Common pitfalls
+- Providing proof-of-concept exploits detailed enough to cause harm rather than just enough to demonstrate impact and urgency
+- Flagging theoretical vulnerabilities from a checklist without confirming they're actually reachable/exploitable in this codebase
+- Treating a passing scan (SAST/DAST) as equivalent to a manual review — automated tools miss business-logic flaws
+- Auditing only the happy path and skipping error handling, edge cases, and admin/internal endpoints
+- Reporting findings without prioritization, leaving teams to guess what to fix first
+
+## Tools & techniques
+- OWASP Top 10 / OWASP API Security Top 10 as baseline coverage checklists
+- SAST (Semgrep), dependency/SCA scanning (Trivy), and secrets scanning (Gitleaks) as force multipliers, not replacements for manual review
+- Manual authentication/authorization testing: privilege escalation, IDOR, broken object-level access checks
+- Structured severity rating (CVSS or a simple Critical/High/Medium/Low rubric) applied consistently across findings
+- Re-test-and-close workflow: every finding tracked from discovery through verified remediation