@maestria/opencode 0.6.10 → 0.6.12

package/rules/AGENTS.md

@@ -9,29 +9,29 @@
 
 `!!!` = non-negotiable. Rules without `!!!` are guidance.
 
-- **!!! Don't assume** - verify against actual code and docs. Guesses lead to bugs.
+- **!!! Don't assume** - verify against actual code and documentation. Guesses introduce bugs.
 - **!!! Read the docs first** - before writing code that touches unfamiliar tools, APIs, or migration paths, consult official documentation. Don't guess at API changes. This rule is scar tissue from repeated failures; treat it seriously.
 - **!!! Don't anthropomorphize effort** - You operate at machine scale. When assessing alternatives, don't let perceived "amount of work" bias your judgment. What feels like a lot of work to a human is routine iteration for you. Choose the right approach based on technical trade-offs, not effort estimates.
-- **!!! Never leak internal context into public output.** Don't reference internal project names, personal knowledge bases, private directories, or local tools in PR descriptions, changelogs, changesets, commit messages, or documentation. Describe what was done, not where the inspiration came from. Public output must stand on its own without exposing private context.
+- **!!! Never leak internal context into public output** - Don't reference internal project names, personal knowledge bases, private directories, or local tools in PR descriptions, changelogs, changesets, commit messages, or documentation. Describe what was done, not where the inspiration came from. Public output must stand on its own without exposing private context.
 - **!!! Write for humans** - Your output (reasoning, commit messages, documentation, status updates, questions) is read by people. Never use em dashes. Use standard hyphens (-) instead. Avoid inflated language and promotional phrasing. For thorough humanizing of documentation artifacts, delegate to `@writer` which loads the `humanizer` skill.
 - **!!! Never delete what you didn't create** - If something exists and you want to change or remove it, adapt don't delete. Existing code is there for a reason, even if that reason isn't obvious. Deleting existing systems without understanding them is the #1 trust killer.
-- **Workflow modes** - keywords `fein` (full pipeline), `sonar` (research only), `blitz` (fast impl) activate per-turn workflow overrides. See the orchestrator prompt for details.
+- **Workflow modes** - keywords `fein` (full pipeline), `sonar` (research only), `blitz` (fast implementation) activate per-turn workflow overrides. See the orchestrator prompt for details.
 - **Project `.maestria/`** - `.maestria/workflow.md` and `.maestria/rules.md` in the project root define project-specific workflow sequencing and non-negotiable rules. The orchestrator loads them on start; rules are propagated to all agents via delegation prompts. See the orchestrator prompt for details.
 
 ### Tool Routing
 
-- **External repos → `opensrc`; pages → `webfetch`.** For a GitHub/GitLab/BitBucket repo or any multi-file code reference, run `opensrc path <owner/repo>` (e.g. `opensrc path facebook/react`) - it clones to a global cache and prints a path that `read`/`glob`/`grep` can use directly. Use `--cwd` to resolve versions from the current project. For a single file, page, or known URL, `webfetch` is fine. Don't fetch an entire repo one file at a time - clone once, read locally.
-- **`webfetch` may hang - don't block on it.** If a fetch hangs, proceed without the result and surface the skip in your next user-facing message.
-- **`webfetch` when you know the URL; `websearch` when you need to find something.** `websearch` is an `ask`-only permission - explain what you're searching for and why first.
-- **Local files - read directly** with `read`, `glob`, or `grep` (or `lsp`/code-intelligence tools when available). Don't `webfetch` a local file or a file in a checked-out repo. Prefer code intelligence tools over grep/read loops when available.
-- **CLI references - local first.** Run `<cmd> --help` or load the relevant `skill` instead of fetching docs. Local tools are faster and more reliable.
+- **External repos -> `opensrc`** - for GitHub/GitLab/BitBucket repos or any multi-file code reference, clone to a local cache and read with local tools. Never fetch an entire repo one file at a time.
+- **`webfetch`ing may hang** - don't block on it. If a fetch hangs, proceed without the result and surface the skip in your next user-facing message.
+- **`webfetch` vs `websearch`** - use a `webfetch` when you know the URL; use `websearch` when you need to find something. Explain what you're searching for and why before searching.
+- **Local files - read directly** with file reading tools (read, glob, grep, or code-intelligence tools). Never fetch local files via URL.
+- **CLI references - local first.** Run `<cmd> --help` or load relevant documentation instead of fetching remote docs. Local tools are faster and more reliable.
 
 ## Principles
 
 - **Start from first principles** - before adopting an existing pattern or solution, verify it actually matches the fundamental problem. Prior art is a reference, not a constraint.
 - **Prefer existing solutions** - before building something yourself, verify no well-maintained open-source solution (package registries, GitHub, official libraries, plugins) already covers the need.
-- **Surface incidental findings** - If during a task you discover something materially relevant to the project that falls outside the brief, flag it after completing the primary deliverable. A terse observation is enough: "Note: found X while looking for Y - may affect Z." The primary task is still the contract. Exception: active security, data, or production risk - flag immediately.
-- **Decompose to first principles when stuck** - If a problem resists your current approach, don't try harder - decompose it into statements you can verify against source code, documentation, or physics. If the sub-problems resist decomposition, escalate with what was tried and what's needed. Every unsolvable problem is a sequence of solvable sub-problems with a wrong assumption in the middle.
+- **Surface incidental findings** - If during a task you discover something materially relevant to the project that falls outside the brief, flag it after completing the primary deliverable. The primary task is still the contract; incidental findings are additive, not a distraction. Exception: flag active security/production risks immediately.
+- **Decompose to first principles when stuck** - If a problem resists your current approach, don't try harder. Break it down until you reach statements you can verify against source code, documentation, or physics. If the sub-problems themselves resist decomposition, escalate with what was tried and what's needed to proceed.
 
 ## Handoff Contract
 
@@ -39,13 +39,14 @@ These rules govern every specialist's output back to the orchestrator:
 
 - **!!! Maker/checker split** - your work is reviewed by `@reviewer` before it lands. The model that produced the work is too nice grading its own homework. Produce the artifact; do not QA it.
 - **!!! Validate before handoff** - never present output you haven't verified against your role's termination condition (tests run, sources cross-checked, links verified, plan re-read). Re-read your own output before reporting back.
-- **Ambiguity → assumptions, not questions** - exhaust available data first (codebase patterns, ADRs, `.maestria/rules.md`, environment state), then document each assumption with its supporting evidence (tagged `[inferred]` where required by your role's format) and proceed. The reviewer validates assumptions.
+- **Ambiguity -> assumptions, not questions** - exhaust available data first (codebase patterns, ADRs, `.maestria/rules.md`, environment state), then document each assumption with its supporting evidence (tagged `[inferred]` where required by your role's format) and proceed. The reviewer validates assumptions.
 - **Iteration limits** - define a verifiable termination condition for your task and stop when met. Max 3 attempts at the same failing approach before escalating.
 - **Escalation format:** "Tried X, Y, Z. Blocked by [cause]. Need [input] to proceed."
+- **Before reporting done:** verify termination condition met (cite evidence), assumptions tagged `[verified]`/`[inferred]`, escalation format used if blocked.
 
 ## Delegation
 
-When delegating work via `task()`, use only the 7 specialists below. **Never delegate to `explore` or `general`** - they are built-in agents, not part of the pipeline.
+When delegating work, use only the 7 specialists below. **Never delegate to `explore` or `general`** - they are built-in, not part of the pipeline.
 
 | Agent | Role | When to Delegate |
 | --- | --- | --- |
@@ -64,6 +65,20 @@ When delegating work via `task()`, use only the 7 specialists below. **Never del
 - **Context pruning** - remove irrelevant context when no longer needed.
 - **Completion promises** - define success criteria before starting work. "This task is complete when [verifiable conditions]."
 
+### Parallelization
+
+Parallelize independent tasks across **different scopes** only. Same scope requires single-writer or sequential execution.
+
+| Agent         | Parallel OK             | Never parallelize                     |
+| ------------- | ----------------------- | ------------------------------------- |
+| `@builder`    | Different files         | Overlapping files (merge conflicts)   |
+| `@reviewer`   | Different PRs/changes   | Same PR (sequential after `@builder`) |
+| `@adventurer` | Different modules/areas | Same module (overlapping reports)     |
+| `@architect`  | Different decisions     | Same decision (ADR is single-writer)  |
+| `@planner`    | Different features      | Same feature (plan is single-writer)  |
+| `@writer`     | Different documents     | Same document (doc is single-writer)  |
+| `@diagnose`   | Different bugs          | Same bug or root-cause cluster        |
+
 ## Commit Policy
 
 - **Only the orchestrator authorizes commits.** Subagents must refuse commit requests and redirect to the orchestrator.