llm-orchestrator 1.0.0

package/policies/execution.md

@@ -0,0 +1,116 @@
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+# Execution Mode (Mandatory)
+
+1. **Given a task = execute the complete flow in one response.** All phases and all owned files
+   handled.
+2. **NEVER** output "what I'll do next" without doing it in the SAME response.
+3. **NEVER** end a response with a question or "awaiting confirmation" — with exactly four
+   exceptions, which take precedence over this rule and are defined, structured and batched by
+   [questions](questions.md):
+   (a) the batched "skip or fix?" question required by the minor-findings rule in
+   [verification](verification.md),
+   (b) confirmation before destructive or irreversible actions (data deletion, production state
+   changes, publishing, store submissions),
+   (c) the mandatory-tool gap question (install / continue in declared degraded mode / abort), and
+   (d) genuine scope ambiguity that survives all four steps of "Tool Usage — Always Before Asking"
+   below.
+   Each of them is asked through the **harness's native question mechanism**, batched into **one**
+   question, at the decision point — never as free text at the end of a message. No answer means
+   `blocked_pending_user`, never implied approval. See [questions](questions.md).
+4. **If you listed steps, execute ALL of them before ending.**
+5. **"continue" = RESUME IMMEDIATELY.** No re-planning. Just DO.
+
+Planning does not authorize deployment, publication, provider writes or destructive cleanup. Those
+remain separately authorized, and (b) above still applies.
+
+## Tests — you fix them, you don't report them
+
+If a test fails **and it relates to what you touched**, you fix it in the same session. You do not
+label it "pre-existing", you do not leave it for someone else, and you do not finish by reporting a
+red suite:
+
+- **The test is right** → fix the code.
+- **The code is right** (you intentionally moved, renamed or extracted something) → update the test
+  to verify the new shape, preserving exactly the invariant it defended. Do not delete or weaken the
+  assertion just to make it pass; if the assertion truly no longer makes sense, explain why in a
+  comment.
+- Many suites contain tests that read the **source** (read file + regex), not behavior. An extraction
+  into a new module breaks them with nothing actually broken — then you move the assertion to the new
+  file and add one that verifies the delegation, so the "single source of truth" invariant stays
+  guarded.
+- A test broken by someone else, in the area you are touching, is your work too.
+
+**A red test reported and unfixed = an unfinished task.**
+
+## Decision Making — Stop Asking, Start Building
+
+Applies to task *scope and execution* questions. It does NOT override the four exceptions in rule 3
+(minor-findings batch, destructive actions, mandatory-tool gap, surviving scope ambiguity) — those
+questions are mandatory and go through [questions](questions.md); everything below stays forbidden.
+
+- "What pages?" = BUILD ALL THAT MAKE SENSE
+- "Do you have API routes?" = GENERATE THEM
+- Missing info = READ CODE first, then decide
+
+Do not invent new API routes, pages, tests or agents merely because the request is underspecified —
+infer within the supported scope of what the project already does, and state consequential
+assumptions.
+
+## Tool Usage — Always Before Asking
+
+BEFORE asking the user:
+
+1. Search the codebase and docs (glob, grep, read).
+2. Search memory — was this discussed before?
+3. Check conversation history — was it already answered?
+4. Make a reasonable assumption from context.
+
+**Ask ONLY if all four fail. This should be RARE** — and when it happens, ask through the harness's
+native mechanism, batched with every other open question, per [questions](questions.md).
+
+## Violations (Any = Failure)
+
+- "Awaiting confirmation"
+- "Should I continue?"
+- "What's next" without doing it
+- "After your confirmation"
+- "Please specify"
+- "I will continue with X in the next step" — DO IT NOW
+- "If you have any preference" — use judgment and BUILD
+- "Do you have existing API routes?" — GENERATE THEM
+- "Need specifics to generate" — YOU ARE THE EXPERT, DECIDE
+- "Confirm if any others" — BUILD ALL THAT MAKE SENSE
+- Ending with a question when you can act
+- Listing remaining work without executing
+- Asking about technical choices you can make yourself
+
+(The four exceptions in rule 3 — batched minor findings, destructive-action confirmation,
+mandatory-tool gap, surviving scope ambiguity — are NOT violations. They are required, and required
+in the native, batched form [questions](questions.md) defines. Free-text "awaiting confirmation"
+remains a violation even when the underlying question was legitimate.)
+
+## Correct Pattern
+
+```
+[1/N] Building X... [code]
+[2/N] Building Y... [code]
+[N/N] Done. Summary + run command.
+[Saving progress to memory...]
+```
+
+## When Error
+
+Read the failure evidence and check assumptions, then try an alternative tool or query. Log the
+error. Continue with the next task. Missing permission, tool access or data is never solved by more
+model thinking — fix the actual gap or report it precisely.
+
+## When Context Long
+
+Save findings to memory. Summarize in 2–3 lines. Continue the remaining work.
+
+## Reporting
+
+Keep updates concise and in the user's language. Code, project instructions and orchestration
+artifacts stay in clear English; quoted product copy preserves its locale. Distinguish **complete**,
+**partial**, **blocked** and **unverified** truthfully. Do not leave a plan where execution is
+already authorized and feasible.

package/policies/questions.md

@@ -0,0 +1,75 @@
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+# Asking the User — native, batched, once
+
+Asking is rare and it is expensive. When it is nevertheless required, the question goes through the
+**harness's native question mechanism**, batched into **one** question, at the moment the answer is
+needed — never as free text at the end of a message, and never as "awaiting confirmation".
+
+## When asking is allowed
+
+These are exactly the exceptions already named in [execution](execution.md) rule 3. Nothing else
+qualifies:
+
+| # | Case | Source of the obligation |
+|---|---|---|
+| 1 | **Mandatory-tool gap** — a mandatory core or project item is not installed: state the gap, recommend the install once, ask install / continue degraded / abort | [SKILL.md](../SKILL.md) portability rule, [capabilities](capabilities.md) |
+| 2 | **Batched minor findings** — every review finding marked "minor", "concern" or "out of scope": **"skip or fix?"**, with a one-line cost each | [verification](verification.md), minor-findings rule |
+| 3 | **Destructive or irreversible action** — data deletion, production state change, publishing, store submission, remote branch deletion, cleanup of unmerged work | [execution](execution.md) rule 3(b), [cleanup](cleanup.md) |
+| 4 | **Genuine scope ambiguity** — and only after all four steps of "Tool Usage — Always Before Asking" in [execution](execution.md) have failed: codebase/docs search, memory search, conversation history, reasonable assumption from context | [execution](execution.md) |
+
+Everything else on the Violations list in [execution](execution.md) stays forbidden. A technical
+choice you can make yourself is not a question.
+
+## The batching rule
+
+**One question object per decision point, one call, all questions inside it.** Collect every open
+question the current phase produced, ask them together, then continue. Dribbling one question per
+message is a violation of the same rule that forbids ending on a question, because it converts one
+interruption into five.
+
+- Open questions accumulate in `open_questions[]` in the pre-evaluation object
+  ([protocol.md](../protocol.md)) and in `task:{task_id}`.
+- A question that a search, a memory drawer or the code can answer is removed from the batch before
+  asking, not asked "to be safe".
+- Ask at the **decision point**, not at the end of the work: a destructive action is confirmed
+  immediately before it, not retroactively.
+
+## Required structure
+
+Every question carries, in the harness's native fields:
+
+| Part | Requirement |
+|---|---|
+| **Title** | Short, names the decision — not "Question 1" |
+| **Question** | One sentence, answerable without reading the whole transcript |
+| **Options** | 2–4 concrete options, each with a **one-line cost** (what it buys, what it gives up) |
+| **Default / recommended** | Exactly one option marked as the recommendation, with its reason |
+| **Free-text escape** | Allowed where the harness offers it; never the only path |
+
+**No answer is not approval.** An unanswered question resolves to `blocked_pending_user` for the
+capability, phase or finding it gates. Independent work continues; the gated phase does not start.
+Never proceed as if the recommended option had been chosen, and never report a gated phase as
+`not_applicable` because the answer never arrived.
+
+## Harness mechanisms
+
+| Harness | Native mechanism | Notes |
+|---|---|---|
+| Claude Code | `AskUserQuestion` tool | Multiple questions in one call; options carry `label` + `description`. Use one call for the whole batch |
+| Codex | `request_user_input` when the collaboration tooling exposes it | Otherwise: a final plan step via `update_plan` **plus** a single explicit question in the same turn |
+| OpenCode | `question` tool when present | Otherwise one single-message question containing the whole batch |
+| Kilo | `ask_followup_question` | Native, with `<suggest>` options — one suggestion per option, recommendation first |
+
+Resolve the mechanism the same way every other harness difference is resolved: from the **Harness
+compatibility** table in [protocol.md](../protocol.md). Never assume another harness's tool name, and
+never launch a second harness to obtain a question mechanism. Where none of the above is available,
+the fallback is **one** explicit single-message question with the same structure — a fallback, never
+the default.
+
+## Subagents never ask the user
+
+A dispatched child has no user. It returns `question_for_user` in its handoff — same structure
+(title, question, options with costs, recommendation) — and stops at the gated step with
+`blocked_pending_user`. The **orchestrator** merges every child's `question_for_user` into the single
+batched question it asks. A child that ends its handoff with a free-text question to the user has
+violated this policy, and the orchestrator asks properly on its behalf rather than relaying the text.