llm-orchestrator 1.0.0

package/policies/state.md

@@ -0,0 +1,85 @@
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+# Task State and Memory (MEMPALACE — Mandatory)
+
+MemPalace is a **mandatory** core tool, not a preference. Skipping it makes the work invalid: state
+lives in drawers, contexts are disposable, and every clean-session dispatch depends on the drawer
+references existing.
+
+**AT SESSION START**: `mempalace_search("current project status")`,
+`mempalace_search("user preferences")`, `mempalace_search(topic)`.
+
+**DURING WORK**: `mempalace_add_drawer(title, content, room)` — save findings, decisions and results.
+Save partial results when the context grows long, and after any non-obvious finding.
+
+**AT SESSION END**: `mempalace_add_drawer("session summary", summary, "sessions")`,
+`mempalace_add_drawer("task progress", remaining_todos, "tasks")`.
+
+**CONTEXT MANAGEMENT**: long context → save to memory → continue shorter. Resume ("continue") → read
+from memory. New topic → search memory first.
+
+## Output drawers
+
+| Drawer | Purpose |
+|---|---|
+| `task:{task_id}` | TaskFlow object, classification, status |
+| `flow:{task_id}` | Phase definitions, agent assignments, gates, `plan_shards`, dispatch contract |
+| `gate:{task_id}:{phase}` | Gate criteria, status, evidence, `not_applicable` reason |
+| `evidence:{type}:{task_id}` | Agent findings, `file:line` refs, open questions, source revision |
+| `hypothesis:{task_id}` | The single falsifiable hypothesis for bugs and incidents |
+| `ownership:{task_id}` | File ownership for builders |
+| `regression:{task_id}` | Regression test files, RED/GREEN evidence, run command |
+| `review:{task_id}` | Code reviewer verdict |
+| `runbook:{task_id}` | Complete timeline, decisions, gaps |
+| `verification:{task_id}` | Verification results per stage |
+| `cleanup:{task_id}` | `cleanup_state`, removed paths, branch, commit, sessions stopped, exit status |
+| `permission_recovery:{task_id}:{phase}:{role}` | Blocked permission, source, profile, `restart_count`, next action |
+
+Drawer names are literal and shared: the same strings appear in [dispatch](dispatch.md),
+[cleanup](cleanup.md), [protocol.md](../protocol.md) and the generated command prompts. Never invent
+a variant spelling.
+
+## Flow flags (inside `flow:{task_id}`)
+
+These are states, not drawers, and they carry these exact names:
+
+| Flag | Set when | Cleared / terminal |
+|---|---|---|
+| `permission_recovery_pending` | A delegated session reported a required access denial | One recovery launch per `task_id + phase + role`; a second denial is terminal `permission_blocked` |
+| `permission_blocked` | The second effective denial | Terminal — only a human can approve a non-restricted session |
+| `subagent_stream_recovery_pending` | A child returned a runtime-declared resumable streaming failure | Cleared on a merged handoff; terminal `subagent_resume_unavailable` |
+| `subagent_resume_unavailable` | The child id is not resumable and no phase contract exists to restart from | Terminal |
+| `cleanup_state` | Every flow that created a branch or worktree | `complete`, `blocked_dirty`, `am_stale_ui` — see [cleanup](cleanup.md) |
+| `restart_count` | Per phase/role, initialised to `0` before dispatch | Incremented by the orchestrator immediately before a recovery launch |
+| `resume_count` | Per resumable child, initialised to `0` | At most three resume attempts |
+| `open_questions` | A question must go to the user | Cleared when the batched native question is answered; unanswered items stay `blocked_pending_user` — see [questions](questions.md) |
+| `inventory_revision` | Every shard routing decision | Bumped on a model-not-found, rejected effort or quota change; the remaining shards are re-routed |
+
+## What a drawer holds
+
+Scope, source revision, owners, phase and gate status, evidence paths, model/tool inventory
+observations, refusal and degraded-mode decisions, requested and effective models, checks performed,
+limitations and the next action.
+
+**Never**: credentials, raw private logs, private reasoning transcripts, or full conversation
+history. Keep handoffs ≤50 lines.
+
+Checkpoint at meaningful boundaries, every 6–8 tool calls, before context pressure, or at ~70% of
+the session budget. Do not make paid keep-alive calls to hold a session open.
+
+On continue, read the existing state and the current diff, and resume from completed-chain evidence
+rather than restarting planning. Invalidate only the facts whose scope actually changed. Status is
+read-only. Cancellation records the stopped owned workers and preserves changes.
+
+## Fallback when MemPalace is genuinely unavailable
+
+MemPalace is mandatory, so an absence is handled by the portability rule in `SKILL.md`: state the gap
+first, recommend installation once with the exact command, and only after an explicit user refusal
+continue in **declared degraded mode** — every plan, handoff and final report carries a `degraded:
+mempalace` line.
+
+In that declared degraded mode, write the same drawers as files in an **authorized artifact store
+outside the repository**, namespaced by project and task, with the same field contract and the same
+prohibitions: no credentials, no raw private logs, no reasoning transcripts, no full conversation
+history. Never write permanent memory into the repository merely because a workflow suggested it, and
+never claim persistence succeeded when the adapter failed — report the gap and use the authorized
+equivalent.

package/policies/verification.md

@@ -0,0 +1,72 @@
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+# Verification
+
+Evidence before assertions, always. `verification-before-completion` runs before any completion
+claim.
+
+## Gate evidence rules
+
+- **G3** Test RED — the failing test must have been *observed* failing for the exact failure or
+  requirement. A test that was written but never run does not satisfy G3.
+- **G4** Build GREEN — requires **fresh** GREEN evidence collected locally: tests pass, lint clean,
+  build succeeds, with exit status recorded. **A builder's report never substitutes for local diff
+  and test evidence.**
+- **G5** Review PASS — a **read-only review after integration**, by an independent agent that did not
+  inherit the implementer's conversation history. No ownership conflicts, hypothesis or requirements
+  addressed, full suite GREEN.
+- **G6** Verification Complete — domain smoke checks for the affected surfaces, run for real, with
+  their output recorded in `verification:{task_id}`.
+
+Select checks from the project instructions, the task acceptance criteria and the changed behavior.
+Run real checks, inspect exit status, and report skipped or unverified separately from passed. Use
+full suites when the project contract requires them; otherwise meaningful scoped checks suffice.
+Expand testing for new changes or unresolved failures, not as ritual repetition.
+
+For executable features and bugs, establish a failing behavioral check before the fix, then GREEN.
+Refactors preserve behavior and coverage. Documentation, configuration and instruction changes take
+relevant consistency, schema or scenario checks rather than artificial implementation-mirroring
+tests, and mark G3 `not_applicable` with that reason.
+
+Distinguish infrastructure failure from code failure and from reasoning failure. A mocked or
+provider-local check cannot establish live lifecycle behavior; say so rather than implying it did.
+
+## Source-reading tests
+
+Tests that read the source rather than behavior break on a legitimate extraction with nothing
+actually broken. **Move the assertion to the new authority and add one that verifies the
+delegation**, so the original invariant stays guarded. Never delete or weaken an assertion to reach
+green.
+
+## Minor findings, concerns and out-of-scope calls
+
+- A review finding marked "minor" or "concern" is **NEVER** silently skipped or parked. Ask the user
+  explicitly: **"skip or fix?"** — with a one-line cost of each option.
+- Anything that looks out of scope for the current task gets explicit user confirmation before being
+  treated as out of scope. "Parked with a ruling" without the user's yes is not allowed.
+- These questions are **batched** (one list, one native question call), not dribbled one at a time,
+  and they use the harness's native question mechanism — see [questions](questions.md).
+- This rule takes precedence over the "never end with a question" rule in
+  [execution](execution.md) — it is one of that rule's four exceptions.
+
+## Zero-tolerance for warnings
+
+Any warning, deprecation notice, info-level complaint, or error encountered **ANYWHERE** gets fixed,
+not stepped over: terminal and tool output, language-runtime deprecations, container logs, browser
+console, test runners, build output, linters — any context. If it cannot be fixed in the current
+task, it goes on the ledger or todo list explicitly, with an owner, never silently ignored.
+
+**Deprecations are bugs, not warnings.** A deprecation printed by code you wrote *or merely ran past*
+is a defect in the file it points at, and it gets fixed in the same change. Today's deprecation is
+the next release's fatal error, and a runtime split across versions can already make it hard on one
+process while it is a notice on another. Verify against the interpreter or runtime that production
+uses, not the one your shell defaults to.
+
+## Independent review
+
+Independent review is required whenever a risk floor in [routing](routing.md) — core or
+project-tightened — says so. **It is never cut, at any quota level: cut the implementer, never the
+reviewer.** The absence of an independent reviewer leaves that acceptance **unverified**; self-review
+is not a substitute and must never be described as independent.
+
+Record concrete findings and resolve scoped defects. Do not change unrelated user work. Report actual
+evidence rather than claiming completion from the fact that a tool was invoked.

package/protocol.md

@@ -0,0 +1,162 @@
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+# Orchestration Protocol
+
+**Single entry point. Every request → pre-evaluation → optimal flow → dispatch → gates → verify.
+No direct execution without planning.**
+
+## Entry and intent
+
+Load the applicable project instructions, the current task authorization and the installed package.
+Natural-language requests and native commands use the same protocol. A bridge cannot claim
+successful injection unless the runtime actually loaded the skill. A missing package produces the
+gap statement and the single installation recommendation described in `SKILL.md`, and an honest
+native/manual fallback only after explicit refusal.
+
+Commands express intent, not permission:
+
+| Intent | Purpose |
+|---|---|
+| `task "request"` | Universal entry — classify, plan, execute authorized work, verify, report |
+| `task-plan "request"` | Read-only: show the optimal flow without executing. No builders, no installs, no provider writes |
+| `task-status [id]` | Read existing task state: phase, agents, gates. Never resumes execution, never probes models by inference |
+| `task-cancel [id]` | Stop only agents/processes owned by the task; preserve changes and resumable evidence. Cancellation is not cleanup authorization |
+| `task-verify [id]` | Run the applicable authorized checks and report evidence. Cleanup is a separate authorized operation |
+| `incident-start` | Alias for an `INCIDENT` task |
+| `incident-evidence` | Alias for the `INCIDENT` evidence phase |
+| `incident-fix` | Alias for the `INCIDENT` fix phase |
+| `incident-verify` | Alias for `INCIDENT` verification |
+| `incident-close` | Alias for `INCIDENT` close (persist runbook + regression refs, then cleanup) |
+
+The orchestrator generates the `task_id` before dispatching anything, writes `task:{task_id}` and
+`flow:{task_id}`, and returns the `task_id` in its response so status, cancellation and verification
+can target it.
+
+## Pre-Evaluation (MANDATORY for every request, auto, <30s)
+
+No dispatch, edit or shell command may precede this object.
+
+```json
+{
+  "raw_request": "user exact words",
+  "task_type": "INCIDENT|FEATURE|BUG_FIX|REFACTOR|INVESTIGATION|DEPLOY|CONFIG|REVIEW|RESEARCH",
+  "domain": "<project domain from the bindings section>|FRONTEND|BACKEND|DB|INFRA|UNKNOWN",
+  "complexity": "SIMPLE|MODERATE|COMPLEX|CRITICAL",
+  "urgency": "LOW|MEDIUM|HIGH|CRITICAL",
+  "requires_evidence": true,
+  "requires_code_change": true,
+  "requires_deploy": false,
+  "estimated_agents": 3,
+  "required_mcps": ["mempalace", "sequentialthinking", "context7", "exa"],
+  "required_skills": ["using-superpowers", "caveman", "search", "verification-before-completion"],
+  "required_workflows": ["workflows/bug-fix.md"],
+  "required_cli_tools": ["rtk"],
+  "available_tools": [],
+  "used_mcps": [],
+  "permission_profile": "ORCHESTRATOR",
+  "rtk_preflight": "command -v rtk && rtk --version",
+  "fallback_plan": "sequential builders if the harness worktree manager is unavailable",
+  "open_questions": [],
+  "degraded": []
+}
+```
+
+- `available_tools` is filled from live discovery (installed / loaded / callable / denied / unknown),
+  never from memory or from a config file's existence.
+- `used_mcps` is filled by each dispatched agent on return. Silent omission is a gate failure.
+- `open_questions` accumulates every question that must go to the user — mandatory-tool gap, batched
+  minor findings, destructive confirmation, genuine scope ambiguity. They are asked **once, together,
+  through the harness's native question mechanism**; see [questions](policies/questions.md). An
+  unanswered question resolves to `blocked_pending_user`, never to implied approval.
+- `degraded` lists every mandatory item missing after an explicit user refusal. A non-empty
+  `degraded` array must be echoed as a `degraded:` line in every plan, handoff and final report.
+
+### Capability check (part of pre-evaluation)
+
+- Which agent roles exist and are relevant?
+- Which skills, workflows, MCPs and CLI tools does this task type require?
+- Are the required MCPs actually loaded and callable?
+- Any conflicts with existing worktrees or in-flight flows?
+- Does every selected agent have its required permission profile (`RO`, `RW`, `ORCHESTRATOR`)?
+- Does the RTK preflight pass in each delegated session?
+
+### Flow construction
+
+Build a TaskFlow object with phases, `plan_shards`, parallel groups, dependencies, gates, risks and
+per-shard `max_iterations`. Do not dispatch until every shard has scope, owner, outputs, acceptance
+checks, `restart_count: 0` and its own `routing` block. The PlanShard schema lives in
+[dispatch](policies/dispatch.md).
+
+**Model and thinking selection happens per shard, at dispatch time, against the live inventory — not
+once per task.** Every PlanShard carries `routing` with `pair`, `tier`, `thinking_level`,
+`model_requested`, `effort_requested`, `model_effective`, `effort_effective`, `review_floor`,
+`independent_review`, `selection_reason`, `inventory_revision`, `price_source` and
+`est_usd_per_task`. A shard without a filled `routing` block fails G0. When the inventory changes
+mid-flow (model-not-found, rejected effort, quota change), selection is re-run for the **remaining**
+shards only. See [dispatch](policies/dispatch.md) and [routing](policies/routing.md).
+
+## Task classification and flows
+
+| Type | Triggers | Flow | Core agent roles |
+|---|---|---|---|
+| **INCIDENT** | production error, 5xx, stuck state, webhook failure, alert | Evidence → Hypothesis → Fix → Verify → Close | production-telemetry-collector ×N + route-data-flow-tracer → adversarial-skeptic → builders → code-reviewer |
+| **FEATURE** | "build", "add", "create", "implement" | Plan → TDD → Build → Test → Review → Verify | planner → test-engineer → backend-fixer / frontend-fixer → code-reviewer |
+| **BUG_FIX** | "fix", "repair", "broken" | Reproduce → Evidence → Hypothesis → Regression → Fix → Review | investigation → test-engineer → builders → code-reviewer |
+| **REFACTOR** | "refactor", "clean up", "extract", "simplify" | Analyze → Coverage → Incremental → Review | code-simplifier → test-engineer → builders → code-reviewer |
+| **INVESTIGATION** | "why", "analyze", "how does", "debug" | Evidence → Synthesis → Challenge → Report | evidence collectors ×N → synthesizer → adversarial-skeptic |
+| **DEPLOY** | "deploy", "release", "ship" | Pre-checks → Deploy → Smoke → Soak | production-telemetry-collector → test-engineer |
+| **CONFIG** | "configure", "migrate", "set up" | Plan → Change → Validate → Review | backend-fixer → db-migration-author → code-reviewer |
+| **REVIEW** | "review", "audit", "check" | Analyze → Report | code-reviewer → adversarial-skeptic |
+| **RESEARCH** | "research", "compare", "find out", time-sensitive facts | Source → Extract → Corroborate → Document | research collectors ×N → synthesizer → adversarial-skeptic |
+
+Model and thinking assignments for every phase come from the flow matrix in
+[routing](policies/routing.md). Agent role names above are the generic roster; the project's
+bindings section maps them onto the roles that actually exist in the consuming project.
+
+## Universal gates
+
+G0 Plan Approved → G1 Evidence/Requirements Complete → G2 Hypothesis/Design Valid → G3 Test RED →
+G4 Build GREEN → G5 Review PASS → G6 Verification Complete
+
+| Gate | Criteria |
+|---|---|
+| **G0** Plan Approved | Flow built, agents available, resources allocated, ownership defined, every shard has scope/owner/outputs/acceptance and a filled `routing` block |
+| **G1** Evidence / Requirements Complete | All required inputs gathered; evidence artifacts written and indexed by scope and revision |
+| **G2** Hypothesis / Design Valid | A single falsifiable hypothesis (bugs, incidents) or an approved design (features, refactors) |
+| **G3** Test RED | A failing test exists for the exact failure or requirement, and it has been observed failing |
+| **G4** Build GREEN | All tests pass, lint clean, build succeeds — on fresh local evidence, not a builder's report |
+| **G5** Review PASS | No ownership conflicts, hypothesis/requirements addressed, full suite GREEN, independent reviewer where a risk floor applies |
+| **G6** Verification Complete | Domain smoke checks pass for the affected surfaces |
+
+Each gate resolves to `passed`, `failed`, `unverified` or `not_applicable`, always with evidence or a
+reason, recorded in `gate:{task_id}:{phase}`. **`not_applicable` requires a written reason** — it is
+never a default and never a way to skip a gate that is merely inconvenient. Documentation and
+research tasks do not fabricate a RED test; they mark G3 `not_applicable` with that reason. Missing
+named tooling changes the bindings, not the truth of the acceptance criteria. Independent review
+required by a risk floor is preserved even under quota pressure.
+
+## Harness compatibility
+
+The protocol is harness-neutral; only the mechanisms differ.
+
+| Mechanism | Codex | Claude Code | OpenCode | Kilo |
+|---|---|---|---|---|
+| Command / prompt location | `~/.codex/prompts/*.md` (`$1 $2` positional or `$ARGUMENTS`) | `.claude/commands/*.md` (`$ARGUMENTS`) | `.opencode/command/*.md`, `.opencode/commands/*.md` | `.kilo/command/*.md`, `.kilo/commands/*.md` |
+| Agent definition | `AGENTS.md` + spawned agent prompts | `.claude/agents/*.md` (frontmatter: `name`, `description`, `tools`, `model`) | `.opencode/agent/*.md` (frontmatter: `description`, `mode`, `permission`) | `.kilo/agent/*.md` |
+| Dispatch primitive | `spawn_agent` (use `fork_turns="none"`) | Agent tool | `task` tool | `task` tool / `agent_manager` |
+| Plan primitive | `update_plan` | plan mode / todo list | native plan/todo | native plan/todo |
+| Worktree mechanism | git worktree (manual) | git worktree (manual) | git worktree (manual) | Agent Manager worktrees under `.kilo/worktrees/` |
+| Skills root | `.agents/skills/*/SKILL.md` | `.claude/skills/*/SKILL.md`; `CLAUDE.md` imports with `@AGENTS.md` | `~/.config/opencode/skills` | `~/.kilo/skills` and `.kilo/skills` |
+| Sequential Thinking permission key | MCP configured in `~/.codex/config.toml` | MCP server entry | `sequentialthinking_sequentialthinking` | `sequentialthinking_sequentialthinking` |
+
+Resolve your harness here before dispatching. Do not import another harness's permission syntax,
+agent roster or worktree layout, and never launch a second harness to obtain a capability.
+
+## Workflow selection
+
+After classification, load `workflows/<type>.md` for the selected lowercase type, and nothing else.
+Read installed Superpowers workflows when applicable. Application commands are discovered from the
+project's bindings section — they are never bundled in this package.
+
+---
+
+**Orchestrator = brain. Agents = hands. Every task gets the right hands, in the right order.**

package/registries/agent-roles.json

@@ -0,0 +1 @@
+{"_attribution":"llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving","version":1,"permission_profiles":{"RO":{"description":"Read-only. Investigation, evidence collection, review, telemetry.","required_access":["read","grep","glob","bash_readonly"],"rules":["Never edits files.","Bash limited to read-only/inspection commands (no writes, no migrations, no deploys).","Reports findings back to the dispatcher; does not apply fixes."]},"RW":{"description":"Read-write within an assigned bounded shard.","required_access":["read","grep","glob","edit","write","bash"],"rules":["Edits are scoped to the files/directories named in its dispatch contract.","Runs project verification for its own shard before reporting done.","Does not merge, push, or deploy unless explicitly the dispatch contract's target."]},"ORCHESTRATOR":{"description":"Plans, dispatches, and integrates; owns the overall session state.","required_access":["read","grep","glob","edit","write","bash","agent_dispatch"],"rules":["Never bypasses a mandatory capability without declaring the gap first.","Owns fan-out sizing, shard boundaries, and integration/merge order.","Runs final verification before reporting completion to the user."]}},"roles":[{"id":"orchestrator","description":"Plans work, resolves capabilities, dispatches bounded shards, integrates results.","capabilities":["orchestration.bootstrap","memory.recall","memory.checkpoint","workflow.selection","delegation.bounded"],"skills":["using-superpowers","brainstorming","dispatching-parallel-agents","subagent-driven-development"],"mcps":["sequential-thinking","mempalace"],"best_for":"Any nontrivial task needing more than one shard or a risk-floor review seat.","permission_profile":"ORCHESTRATOR","default_tier":"S T3"},{"id":"production-telemetry-collector","description":"Collects production logs/metrics/traces before an incident hypothesis is formed.","capabilities":["incident.telemetry_first"],"skills":["incident-orchestration","incident-evidence"],"mcps":[],"best_for":"Incident evidence gathering; never forms a fix on its own.","permission_profile":"RO","default_tier":"W T0-T1"},{"id":"route-data-flow-tracer","description":"Traces a request/data path across layers (frontend, API, DB, provider) read-only.","capabilities":["code.locate"],"skills":[],"mcps":["serena"],"best_for":"Symptoms that cross architectural layers.","permission_profile":"RO","default_tier":"W T0-T1"},{"id":"explore","description":"Read-only breadth search across a codebase: where something is defined, what calls it, which files are involved.","capabilities":["code.locate","tool.discovery"],"skills":[],"mcps":[],"best_for":"Broad read-only location work before a decision; never edits.","permission_profile":"RO","default_tier":"W T0-T1"},{"id":"db-concurrency-specialist","description":"Reviews transactional/locking correctness and concurrency-sensitive schema/code.","capabilities":["concurrency.review","database.schema_provenance"],"skills":[],"mcps":["db-client"],"best_for":"Race conditions, stale claims, lock ordering, transactional boundaries.","permission_profile":"RO","default_tier":"X T3","review_floor":"X T4"},{"id":"frontend-specialist","description":"Implements frontend changes that touch shared state, realtime or a native bridge, respecting shipped-client compatibility.","capabilities":["ui.design_system","test.behavioral"],"skills":["frontend-design","design-system"],"mcps":["playwright"],"best_for":"Complex frontend state, realtime surfaces and native-bridge implementation work.","permission_profile":"RW","default_tier":"S T3"},{"id":"provider-webhook-specialist","description":"Implements and reviews payment/webhook provider integrations (Stripe, Apple, Google).","capabilities":["billing.provider_evidence","push.provider_evidence","review.independent"],"skills":["stripe-best-practices"],"mcps":["billing-provider-api","push-provider-api"],"best_for":"Webhook signature/idempotency, provider state reconciliation, refund delivery.","permission_profile":"RW","default_tier":"X T2","review_floor":"X T4"},{"id":"adversarial-skeptic","description":"Independently challenges a conclusion, diagnosis, or diff before it ships.","capabilities":["review.adversarial","review.independent"],"skills":[],"mcps":[],"best_for":"Money, auth, migration, and frozen-build-shaped review seats.","permission_profile":"RO","default_tier":"S T3","review_floor":"X T4"},{"id":"test-engineer","description":"Writes and maintains behavioral/regression tests.","capabilities":["test.behavioral","workflow.tdd"],"skills":["test-driven-development"],"mcps":[],"best_for":"Coverage gaps, regression tests for bug fixes, refactor safety nets.","permission_profile":"RW","default_tier":"S T2"},{"id":"db-migration-author","description":"Sole authority for authoring SQL schema migrations.","capabilities":["config.migration_author","database.migration_checks","database.schema_provenance"],"skills":[],"mcps":["db-client"],"best_for":"Any new migration file; never hand-write one outside this role.","permission_profile":"RW","default_tier":"S T3","review_floor":"X T4"},{"id":"backend-fixer","description":"Implements backend bug fixes following systematic-debugging evidence.","capabilities":["workflow.debug","test.behavioral"],"skills":["systematic-debugging"],"mcps":[],"best_for":"Backend bug fixes with a validated hypothesis.","permission_profile":"RW","default_tier":"S T2"},{"id":"frontend-fixer","description":"Implements frontend bug fixes following systematic-debugging evidence.","capabilities":["workflow.debug","test.behavioral","ui.design_system"],"skills":["systematic-debugging"],"mcps":["playwright"],"best_for":"Frontend/UI bug fixes with a validated hypothesis.","permission_profile":"RW","default_tier":"S T2"},{"id":"code-simplifier","description":"Simplifies and clarifies recently changed code without changing behavior.","capabilities":["refactor.preservation","code.semantic_edit"],"skills":[],"mcps":["serena"],"best_for":"Post-implementation cleanup passes.","permission_profile":"RW","default_tier":"S T2"},{"id":"code-reviewer","description":"Performs the review pass at the task's review risk floor.","capabilities":["review.independent","workflow.review"],"skills":["requesting-code-review","receiving-code-review"],"mcps":[],"best_for":"The review seat on every review-gated task.","permission_profile":"RO","default_tier":"S T2","review_floor":"S T3"},{"id":"general","description":"General-purpose bounded worker for tasks that fit no specialist role.","capabilities":["workflow.selection","delegation.bounded"],"skills":[],"mcps":[],"best_for":"Bounded work with no specialist owner; escalate rather than widen scope.","permission_profile":"RW","default_tier":"S T2"}]}

package/registries/capabilities.json

@@ -0,0 +1,58 @@
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": 1,
+  "capabilities": [
+    { "id": "orchestration.bootstrap", "description": "Load the orchestration entrypoint/skill before planning or executing any work" },
+    { "id": "memory.recall", "description": "Recall prior session/task memory before planning" },
+    { "id": "memory.checkpoint", "description": "Write a memory checkpoint at session end or after a non-obvious finding" },
+    { "id": "skill.check", "description": "Check for an applicable skill before responding or acting" },
+    { "id": "tool.discovery", "description": "Search for an existing tool/capability before declaring one absent" },
+    { "id": "user.native_question", "description": "Ask the user through the harness's native question mechanism, batched into one question, never as free text at the end of a message" },
+    { "id": "incident.telemetry_first", "description": "Collect production telemetry before forming an incident hypothesis" },
+    { "id": "incident.protocol_order", "description": "Run the incident lifecycle commands in order: start, evidence, fix, verify, close" },
+    { "id": "workflow.brainstorm", "description": "Brainstorm and challenge a design before entering plan mode" },
+    { "id": "workflow.systematic_debugging", "description": "Reproduce and diagnose with a systematic-debugging discipline before fixing" },
+    { "id": "review.adversarial", "description": "Challenge a conclusion or diff with an independent adversarial pass" },
+    { "id": "refactor.coverage_first", "description": "Confirm behavioral coverage exists before the first refactor edit" },
+    { "id": "config.migration_author", "description": "Author schema/config migrations through a dedicated migration authority, never hand-written" },
+    { "id": "ui.design_system", "description": "Apply the project design system and styling review to new or changed UI" },
+    { "id": "traceability.cypilot", "description": "Maintain artifact/code traceability for PR-shaped or spec-shaped work" },
+    { "id": "code.semantic_edit", "description": "Use symbol-aware semantic editing for large or cross-file code changes" },
+    { "id": "code.locate", "description": "Locate code read-only (definitions, call sites, cross-file references) before editing" },
+    { "id": "communication.concise", "description": "Concise, complete execution communication" },
+    { "id": "workflow.selection", "description": "Select and load only applicable workflows" },
+    { "id": "workflow.design", "description": "Design a behavior change before implementation" },
+    { "id": "workflow.plan", "description": "Create an executable implementation plan" },
+    { "id": "workflow.tdd", "description": "Use a test-first cycle for executable behavior changes" },
+    { "id": "workflow.debug", "description": "Collect evidence and test hypotheses before a bug fix" },
+    { "id": "workflow.review", "description": "Perform relevant review before accepting changes" },
+    { "id": "verification.checks", "description": "Run and preserve relevant acceptance checks" },
+    { "id": "reasoning.checkpoints", "description": "Record concise decisions, assumptions, and evidence for nontrivial work" },
+    { "id": "shell.rtk", "description": "Run supported shell commands through RTK while preserving exit status" },
+    { "id": "research.retrieve", "description": "Retrieve current or external factual sources" },
+    { "id": "research.provenance", "description": "Record source provenance for factual claims" },
+    { "id": "research.validation", "description": "Validate source quality and factual claims" },
+    { "id": "docs.current", "description": "Retrieve versioned library or platform documentation when uncertain" },
+    { "id": "test.behavioral", "description": "Execute behavioral or regression tests" },
+    { "id": "refactor.preservation", "description": "Check preserved behavior for a refactor" },
+    { "id": "browser.inspect", "description": "Inspect rendered web behavior" },
+    { "id": "browser.interact", "description": "Interact with a rendered web route" },
+    { "id": "browser.capture", "description": "Capture viewport evidence for rendered web behavior" },
+    { "id": "mobile.platform_evidence", "description": "Collect platform-specific native build or device evidence" },
+    { "id": "billing.provider_evidence", "description": "Inspect authorized provider state for billing claims" },
+    { "id": "push.provider_evidence", "description": "Inspect authorized push-provider delivery or state" },
+    { "id": "database.schema_provenance", "description": "Trace schema and migration provenance" },
+    { "id": "database.migration_checks", "description": "Run relevant migration checks" },
+    { "id": "concurrency.review", "description": "Review concurrency and transaction correctness" },
+    { "id": "forge.remote", "description": "Perform an explicitly requested forge remote operation" },
+    { "id": "review.independent", "description": "Obtain independent review at the task risk floor" },
+    { "id": "harness.docs", "description": "Retrieve harness-specific versioned documentation" },
+    { "id": "schema.validation", "description": "Validate a versioned contract schema" },
+    { "id": "deployment.authorized_target", "description": "Use authorized deployment-target access" },
+    { "id": "deployment.precheck", "description": "Run deployment prechecks" },
+    { "id": "deployment.smoke", "description": "Run post-deployment smoke evidence" },
+    { "id": "deployment.rollback", "description": "Record an authorized rollback procedure" },
+    { "id": "delegation.bounded", "description": "Delegate bounded shards with ownership and verification" }
+  ]
+}

package/registries/core-profile.json

@@ -0,0 +1,183 @@
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "version": 2,
+  "profile": "portable-default",
+  "requirements": [
+    {
+      "id": "orchestration.bootstrap",
+      "level": "mandatory",
+      "order": 1,
+      "scope": "core",
+      "reason": "The orchestration entrypoint/skill must be loaded before any planning or execution, on every task.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["using-superpowers"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "memory.recall",
+      "level": "mandatory",
+      "order": 2,
+      "scope": "core",
+      "reason": "Session/task memory must be recalled before planning so prior findings are not rediscovered.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["mempalace"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "memory.checkpoint",
+      "level": "mandatory",
+      "order": 3,
+      "scope": "core",
+      "reason": "A memory checkpoint is required at session end and after any non-obvious finding.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["mempalace"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "reasoning.checkpoints",
+      "level": "mandatory",
+      "order": 4,
+      "scope": "phase",
+      "reason": "Nontrivial planning, diagnosis, and tradeoffs need concise recorded evidence checkpoints.",
+      "applies_when": { "nontrivial": true },
+      "acceptance": ["decision-evidence-checkpoint"],
+      "preferred_implementations": ["sequential-thinking"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true,
+      "manual_fallback": true,
+      "manual_implementation": "manual-decision-checkpoints"
+    },
+    {
+      "id": "communication.concise",
+      "level": "mandatory",
+      "order": 5,
+      "scope": "core",
+      "reason": "The portable core communicates concise, complete contracts.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["caveman"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "shell.rtk",
+      "level": "mandatory",
+      "order": 6,
+      "scope": "phase",
+      "reason": "Shell phases use the configured output reduction wrapper without changing command semantics.",
+      "applies_when": { "requires_shell": true },
+      "acceptance": ["command-exit-status"],
+      "preferred_implementations": ["rtk"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "docs.current",
+      "level": "mandatory",
+      "order": 7,
+      "scope": "phase",
+      "reason": "Any code, fix, update, or correctness/completeness review needs current versioned documentation, even for familiar libraries.",
+      "applies_when": { "any_task_signals": ["code-change", "version-sensitive", "uncertain-library", "uncertain-platform"] },
+      "acceptance": ["versioned-source"],
+      "preferred_implementations": ["context7"],
+      "allowed_alternatives": ["native-web"],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "research.retrieve",
+      "level": "mandatory",
+      "order": 8,
+      "scope": "core",
+      "reason": "External/current facts, library or vendor behavior not in local docs, research-type tasks, and any claim about versions/prices/APIs need retrieved current sources, not recalled ones.",
+      "applies_when": { "any_task_types": ["research"], "any_task_signals": ["external-facts", "current-facts", "version-sensitive", "uncertain-library", "uncertain-platform", "source-claims"] },
+      "acceptance": ["source-provenance"],
+      "preferred_implementations": ["exa-search"],
+      "allowed_alternatives": ["native-web"],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "verification.checks",
+      "level": "mandatory",
+      "order": 9,
+      "scope": "phase",
+      "reason": "Every completion claim needs a verification-before-completion pass.",
+      "applies_when": { "any_phases": ["verification"] },
+      "acceptance": ["verification-output"],
+      "preferred_implementations": ["verification-before-completion"],
+      "allowed_alternatives": ["superpowers-workflows", "project-test-runner"],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "skill.check",
+      "level": "mandatory",
+      "order": 10,
+      "scope": "core",
+      "reason": "Before any action, including a clarifying question, check whether an applicable skill already covers it.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["skill-discovery"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "tool.discovery",
+      "level": "mandatory",
+      "order": 11,
+      "scope": "core",
+      "reason": "Search before asserting a tool or MCP is unavailable.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["tool-search"],
+      "allowed_alternatives": [],
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true
+    },
+    {
+      "id": "user.native_question",
+      "level": "mandatory",
+      "order": 12,
+      "scope": "core",
+      "reason": "Any question to the user goes through the harness's native question mechanism, batched into one question, at the decision point — never free text at the end of a message. Present in every harness; the fallback is a single explicit message with the same structure.",
+      "applies_when": { "always": true },
+      "acceptance": [],
+      "preferred_implementations": ["harness-native-question"],
+      "allowed_alternatives": ["single-explicit-message"],
+      "harness_mechanisms": {
+        "claude": "AskUserQuestion",
+        "codex": "request_user_input, else update_plan + one explicit question",
+        "opencode": "question",
+        "kilo": "ask_followup_question"
+      },
+      "gap_declared_first": true,
+      "degraded_mode_after_refusal": true,
+      "manual_fallback": true,
+      "manual_implementation": "single-explicit-message"
+    },
+    {
+      "id": "workflow.selection",
+      "level": "required",
+      "scope": "core",
+      "reason": "Applicable workflow disciplines must be selected before task work.",
+      "applies_when": { "any_task_types": ["feature", "bug", "investigation", "incident", "refactor", "review", "deployment", "research", "documentation", "config", "harness"] },
+      "acceptance": [],
+      "preferred_implementations": ["superpowers-workflows"],
+      "allowed_alternatives": ["native-workflow-selection"]
+    }
+  ]
+}