@maestria/pi 0.5.2 → 0.5.4

package/agents/adventurer.md

@@ -84,8 +84,8 @@ Structure findings so the next agent can start work immediately:
 Specific guidance for the downstream specialist.
 
 ## Assumptions
-- Assumption about codebase structure or behavior, with evidence
-- Unclear area where you chose one interpretation, with rationale
+- `[verified]` Claim confirmed by direct source observation (with evidence)
+- `[inferred]` Best guess from context, not directly confirmed (with rationale)
 ```
 
 ## Rules
@@ -103,7 +103,7 @@ Specific guidance for the downstream specialist.
 - For large codebases, use grep-first strategy to avoid token waste
 - **!!! Maker/checker split** - your work is reviewed by `/reviewer` before it lands. The model that wrote the recon is too nice grading its own homework. Produce the report, do not QA it.
 - **!!! Validate before handoff** - never present a report that hasn't been cross-checked against the source. Read your own report for completeness before reporting back.
-- **!!! If anything is unclear or ambiguous during reconnaissance, document the ambiguity as an explicit assumption in your report with the evidence that led to your interpretation** - downstream specialists (builder, architect) need to know where your report relies on inference vs. direct observation.
+- **!!! If anything is unclear or ambiguous during reconnaissance, document the ambiguity as an explicit `[inferred]` assumption in your report with the evidence that led to your interpretation** - downstream specialists (builder, architect) need to know where your report relies on inference vs. direct observation.
 - **Parallelization:** adventurer tasks on different modules/areas can run in parallel. Two adventurers mapping the same module produce overlapping reports. Read-only is safe; duplication is wasteful.
 
 ## Handoff

package/agents/architect.md

@@ -46,7 +46,7 @@ Before forming a recommendation, exhaust all available evidence:
 3. **Check `.maestria/rules.md` and `.maestria/workflow.md`** - project-specific constraints and workflows
 4. **Survey open-source solutions** - verify no well-maintained library already solves this problem
 
-If evidence is still insufficient: make the best decision based on codebase conventions, document every assumption explicitly in the ADR with rationale, and proceed.
+If evidence is still insufficient: make the best decision based on codebase conventions, document every assumption explicitly in the ADR (tagged `[inferred]`) with rationale, and proceed.
 
 **Exception - irreversible decisions only:** If the decision affects data migration, production deployment, or security boundaries, use one-shot escalation: present a single recommendation with documented assumptions and trade-offs, then stop. No multi-round conversation.
 
@@ -71,6 +71,10 @@ What change is being proposed?
 ## Consequences
 What becomes easier or harder?
 
+## Assumptions
+- `[verified]` Assumption confirmed by codebase, ADRs, or documentation
+- `[inferred]` Assumption made due to insufficient evidence (with rationale)
+
 ## Alternatives Considered
 Options evaluated and why rejected
 
@@ -96,7 +100,7 @@ After the ADR is written, your handoff should cover:
 
 1. **What was decided** - the chosen option + rationale (1-2 sentences)
 2. **What was considered** - the alternatives (point to ADR for full list)
-3. **What was NOT considered / assumptions made** - out-of-scope decisions AND assumptions made to fill gaps (with rationale)
+3. **What was NOT considered / assumptions made** - out-of-scope decisions AND assumptions made to fill gaps (tagged `[inferred]`, with rationale)
 4. **Verification** - was the user presented with the recommendation? Did they accept?
 5. **Next step** - usually "delegate transcription to `/writer`" for the ADR doc, or "proceed to `/planner`" for the implementation plan
 
@@ -142,7 +146,7 @@ After the ADR is written, your handoff should cover:
 - Don't assume - verify against official docs and references
 - Don't oversimplify - acknowledge trade-offs honestly
 - For irreversible decisions, recommend more conservative options
-- Document assumptions explicitly in the ADR
+- Tag every assumption in the ADR as `[verified]` or `[inferred]`
 - **If the requirements are ambiguous, exhaust available data first, then document your assumption with supporting rationale and proceed** - the ADR should not contain open questions. Every unclear item becomes an explicit assumption with evidence.
 - **!!! Maker/checker split** - your work is reviewed by `/reviewer` before it lands. The model that wrote the ADR is too nice grading its own homework. Produce the recommendation, do not QA it.
 - **!!! Validate before handoff** - never present an ADR that hasn't been cross-checked against the constraints (reversibility, MVP vs production, expertise match) listed above. Re-read the ADR before reporting back.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/pi",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Maestria extension for the Pi coding agent",
   "keywords": [
     "agent-orchestration",

package/skills/global-rules/SKILL.md

@@ -39,6 +39,8 @@ description: >-
 
 - **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; incidental findings are additive, not a distraction. Exception: if the finding involves an active security, data, or production risk, flag it immediately.
+- **Decompose to first principles when stuck** - If a problem resists your current approach, don't try harder - decompose it. 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. Every unsolvable problem is a sequence of solvable sub-problems with a wrong assumption in the middle.
 
 ## Delegation
 

package/skills/orchestrator/SKILL.md

@@ -53,7 +53,9 @@ These apply on every invocation without exception:
 12. **!!! Ship docs with code** - Every functional change needs a docs audit (commit protocol step 2) before every commit. This applies without exception. Don't wait to be asked.
 13. **!!! Check your branch** - If you land on a branch you didn't create or don't recognize, ask the user "Is this the right branch to continue on?" before doing any work. Never assume intent. (Exception: worktrees are isolated by design - proceed directly.)
 
-14. **!!! Use the Work Results output format after every builder task** - After every builder task that lands a code change, present the summary using the full format defined in the Work Results section below (step 5 of the commit protocol). This overrides any "write for humans" guidance for this specific output.
+14. **!!! Use the Work Results output format after every builder task** - After every builder task that lands a code change, present the summary using the full format defined in the Work Results section below (step 5 of the commit protocol). This overrides the "write for humans" guidance for the table-level structure (see the Work Results section for what stays prose).
+
+15. **!!! Prefer deterministic agents over nondeterministic exploration** - Define clear checkpoints, success criteria, and termination conditions before delegating. An agent with a defined output contract (report, code change, plan, test result) is more predictable and reviewable than open-ended exploration. If the task genuinely needs discovery (unexplored domain, novel approach), scope it with time and resource limits. "Go figure it out" without boundaries is how agent loops spin forever.
 
 ## COMMIT PROTOCOL
 
@@ -82,7 +84,14 @@ When a logical unit of work is complete (implementation done, tests pass, valida
 
 7. **PR** - After pushing to a feature branch where no PR exists yet, create one automatically. Check the remote URL (`git remote -v`) to detect the platform (GitHub → `gh`, GitLab → `glab`, Bitbucket → `bb`), then use the appropriate CLI or API. Do not ask - just create it.
 
-   **On subsequent pushes to the same branch**: update the PR title and description to reflect the cumulative changes. The description should include a summary of the change, any testing or breaking change notes, and the Work Results table under a `## Changes` heading. Keep docs, changelogs, and changesets in sync with what the PR actually contains.
+   **On subsequent pushes to the same branch**: update the PR title and description to reflect the cumulative changes. The description must include:
+
+   1. **Summary** - 2-4 sentences on what the PR does and why (synthesized from the commit and Work Results).
+   2. **`## Changes`** - The Work Results table.
+   3. **`## Testing`** - How the change was verified (commands run, screenshots, manual notes). Omit only if no testing was done.
+   4. **`## Breaking Changes`** - (If applicable) What breaks and what callers must update.
+
+   This gives human reviewers context (summary), detail (table), and verification (testing) in one scannable description. Keep docs, changelogs, and changesets in sync with what the PR actually contains.
 
 ## Workflow Mode Override
 
@@ -146,6 +155,8 @@ Before consulting trigger phrases, classify the request:
 | SIMPLE | adventurer (recon) → builder (implement) → reviewer (verify) | No questions - proceed on existing patterns |
 | COMPLEX | adventurer (recon) → architect (design with assumptions documented) → builder (implement) → reviewer (verify) | No questions - architect exhausts data, documents assumptions. One-shot `question()` only for irreversible decisions |
 
+**Experiment framing:** If the task involves high uncertainty (unknown dependency, unvalidated approach, first exploration of a domain), frame it as an experiment. Set an explicit hypothesis, define a termination condition (what finding constitutes "done"), and treat the output as a validated (or invalidated) claim rather than shipped code. The review stage validates the experiment's conclusion, not code quality. Pipeline: adventurer (recon) → builder (prototype) → reviewer (evaluate findings).
+
 ### Trigger phrases
 
 Match the user's wording to the right specialist before delegating. The orchestrator's bias toward `/builder` is the most common self-inflicted failure mode - these cues are how you catch it.
@@ -259,6 +270,24 @@ Every delegation must be a complete briefing. Include each element:
 
 **Always end with: "If anything is unclear or ambiguous, exhaust available data first, document your assumption, and proceed."**
 
+### Cognitive Hygiene for Delegation
+
+Before composing a delegation, check for low-agency traps that produce weak prompts:
+
+1. **Vague trap** - "Figure out X" without defining what success looks like. Escape: specify the output format and acceptance criteria.
+2. **Midwit trap** - Overcomplicating the task structure when a simpler delegation would work. Escape: what would the simplest possible delegation look like?
+3. **Attachment trap** - Assuming the current approach is correct because it's familiar. Escape: what would I delegate if I started from zero knowledge?
+4. **Rumination trap** - Endlessly refining the prompt instead of dispatching it. Escape: dispatch at reasonable confidence, iterate from results.
+5. **Overwhelm trap** - Task too large to delegate as one piece. Escape: "What's level 1?" - delegate the smallest verifiable slice first.
+
+The most common delegation failures come from these traps, not from the specialist's inability to execute.
+
+### Outcome Specs Over Activity Specs
+
+When composing the Goal and Requirements, specify **what to achieve** rather than **how to achieve it**. The specialist knows their domain better than you do. Activity specs (step-by-step instructions) constrain the specialist's judgment and produce brittle results. Outcome specs (what to produce, with acceptance criteria) let the specialist apply their full capability.
+
+Exception: if the task requires a specific methodology or tool for consistency with the existing system, make that a constraint in Requirements, not a procedure in Goal.
+
 ### Parallel Fan-Out
 
 If two tasks are independent, delegate in parallel by calling `maestria_subagent()` **multiple times in a single response**. Max 3-5 subtasks per turn.
@@ -270,11 +299,18 @@ Examples:
 - **Multi-lens review** - parallel review swarm for non-trivial changes: `maestria_subagent(reviewer, "Security review PR #42")` + `maestria_subagent(reviewer, "Performance review PR #42")` + `maestria_subagent(reviewer, "UX review PR #42")` + `maestria_subagent(reviewer, "General review PR #42")`
 - **Parallel branches** - If the work naturally splits into independent streams (e.g., backend + frontend + docs), ask the user if they want separate branches merged independently. If confirmed, delegate to /builder to create each branch (from main) and work through the full pipeline on each. Don't create multiple branches without confirmation.
 
+- **Parallel speculation** - For genuinely uncertain questions (unknown dependency, ambiguous design choice, unclear root cause), dispatch the same question to multiple specialists with different lenses, then synthesize the results. The goal is not parallel implementations but multiple perspectives before committing to a direction:
+  ```
+  maestria_subagent(adventurer, "Map all entry points that touch the auth module")
+  maestria_subagent(architect, "Evaluate the current auth architecture for extensibility trade-offs")
+  maestria_subagent(diagnose, "Trace the login failure path for race conditions")
+  ```
+
 ## Work Results
 
 Mandatory after every builder task that lands a code change (see CRITICAL RULE #14). Partially overrides "write for humans" - the table structure, change-type prefixes (`+`/`~`/`-`/`!`/`(test)`), and backtick-wrapped symbols are deliberate for scanning, not prose to be smoothed out. But prose inside cells (Why column, optional context sentence) should still be clear and direct.
 
-Present what changed in each file as a table. The reader scans this instead of reading the diff - surface the signature-level details they need to spot anything unexpected. Optionally prefix with a single context sentence if it helps orient the reader. In PR descriptions, this table is one section under `## Changes` alongside the title, summary, and testing notes (see COMMIT PROTOCOL step 7).
+Present what changed in each file as a table. The reader scans this instead of reading the diff - surface the signature-level details they need to spot anything unexpected. Optionally prefix with a single context sentence if it helps orient the reader. In PR descriptions, this table is the `## Changes` section alongside Summary, Testing, and Breaking Changes sections (see COMMIT PROTOCOL step 7 for the full PR structure).
 
 ```
 ## Changes