# Methodology Changelog This changelog tracks meaningful changes to how Maestria-powered agents behave - what they do differently, what they're stricter about, and what you can expect from them. ## 2026-07-14 - **Mandated structured work results.** The `## Changes` summary table after builder tasks is now enforced by a non-negotiable CRITICAL RULE, overriding "write for humans" guidance for this specific output. - **Mandated documentation audit before committing.** The docs audit step is now a `!!!` rule covering four categories: internal docs, user-facing docs site, user-facing changelog, and changesets. - **Fixed stale cross-references in CRITICAL RULES.** Rule #12 now correctly references commit protocol step 2 and uses unambiguous language. - **Streamlined work results format.** The `## Changes` output was simplified from a mandatory 3-part narrative (Overview, File-by-file, Cohesion) to a table-first format where the table is the primary artifact. Context paragraphs became optional. - **Change-type prefixes added to work results.** Every "What changed" entry now uses `+` (added), `~` (modified), or `-` (deleted) for at-a-glance scanning. Breaking changes are marked with `!` (e.g. `!~`). Test files are annotated with `(test)`. - **Work results embedded in PR descriptions.** The COMMIT PROTOCOL now includes the full Work Results table as the `## Changes` section in PR descriptions, so human reviewers see the same structured summary without having to duplicate it. ## 2026-07-14 - **Structured assumption tagging.** Adventurer and architect outputs now require `[verified]` (confirmed from source) or `[inferred]` (best guess from context) tags on every assumption. Downstream agents can distinguish confirmed facts from inferred guesses. - **Deterministic agents preferred.** A new CRITICAL RULE mandates defined output contracts (checkpoints, success criteria, termination conditions) before delegating. Open-ended exploration must be scoped with time and resource limits. - **Cognitive hygiene for delegation.** The orchestrator now has a 5-trap pre-flight checklist (vague, overcomplication, attachment, rumination, overwhelm) to catch weak delegation prompts before dispatch. - **Outcome specs over activity specs.** Delegation now prefers specifying what to achieve over how to achieve it. Activity specs (step-by-step instructions) constrain specialist judgment; outcome specs let specialists apply their full capability. - **Experiment framing for uncertainty.** High-uncertainty tasks (unknown dependency, unvalidated approach, first exploration) can be framed as experiments with explicit hypotheses and termination conditions. The output is a validated finding, not shipped code. - **Parallel speculation pattern.** The orchestrator can now dispatch the same open question to multiple specialists with different lenses, then synthesize results before committing to a direction. - **Unprompted incidental findings.** Agents now surface relevant discoveries outside their brief after completing the primary task. Security, data, or production risks are flagged immediately. - **First-principles decomposition.** When blocked, agents decompose problems into verifiable sub-problems instead of trying harder with the same approach. Escalation path provided for sub-problems that resist decomposition. ## 2026-07-10 - **Subagent permission alignment.** All subagents received expanded bash allow-lists matching their actual tooling needs — read-only file operations pre-allowed, agent-specific tools added per role. Reduces unnecessary permission prompts from 70-88% of commands down to only unusual operations. Catch-all `*: ask` remains for safety. ## 2026-07-10 - **Multi-lens review swarm.** The orchestrator can now dispatch parallel reviewers with different focus areas (Security, Architecture, Performance, UX, General) for non-trivial changes. Each lens has exclusive scope and the orchestrator triages combined results. - **Observation over reasoning.** The reviewer now prioritizes running code and observing behavior over reasoning about correctness. Each review should include a command to produce visible proof. - **Review triage pipeline.** Issues are now categorized [fix]/[dismiss]/[escalate] by the reviewer, then validated by the orchestrator with conservative conflict resolution (when lenses disagree, the stricter categorization wins). - **Docs audit before commits.** Agents now check what docs need updating before every commit - no more waiting to be reminded. ## 2026-07-10 - **Eliminate questions - autonomous philosophy.** Agents now exhaust data, document assumptions, and proceed instead of asking for permission on every decision. Mid-phase questions (design choices, permissions, preferences) are eliminated across all specialists. Boundary checkpoints kept: commit autonomous, push conditional (auto on feature branches, ask on main), PR creation automatic on feature branches after push (user can edit after creation). - **Autonomous commit protocol.** Commit is fully autonomous - agent reads git log for past corrections, composes correct conventional commit message, commits without asking. Per-turn authorization requirement removed. Push is automatic on feature branches, asks only on main/master. - **OpenCode permission alignment.** Builder shell permissions expanded from 5 narrow patterns to comprehensive allow-list covering read-only file operations, git, package managers, and build/test tools. Diagnose edit permission changed from ask to allow. Both keep catch-all ask for unusual commands. - **Structured work result summaries.** Orchestrator now presents completed work as a file-by-file table focusing on signatures and interfaces (not function bodies). Builder reports at the signature level. Users can spot issues in 1-2 prompts instead of reading the full diff. - **`!!!` Convention formalized.** Non-negotiable rules are scar tissue from past failures, not preferences. New "Never delete what you didn't create" rule. Recognizing User Frustration escalation ladder (5 levels with prescribed responses). Anti-Patterns enriched with named patterns and concrete fixes. Complexity-Based Routing (SIMPLE/COMPLEX classification). Session Flow section added - orchestrator proactively proposes next steps instead of going silent. Proven directive combos documented in COMPOSITION.md. - **Writing style improvements.** The "Write for humans" rule hardened to non-negotiable (`!!!`). humanizer skill added as always-load for orchestrator. Reviewer gained Writing Style checklist item 9 to catch violations. ## 2026-07-01 - **Code intelligence tool preference.** Agents now prefer code intelligence tools (MCP, CLI, or other) before falling back to grep and read when exploring your codebase. If you use a tool like CodeGraph, agents will route through it automatically. ## 2026-06-26 - **Two new design principles.** Agents now check from first principles before adopting existing patterns, and check for existing solutions before building from scratch. This pushes toward better design decisions with less wasted effort. ## 2026-06-25 - **Anthropomorphism guard added.** Agents no longer bias decisions based on "that would be a lot of work" - they operate at machine scale. The right technical choice wins, regardless of perceived effort. - **Project-level workflow customization.** You can now add `.maestria/workflow.md` and `.maestria/rules.md` to your project root to define custom delegation sequences and project-specific rules. Core rules always take precedence. ## 2026-06-24 - **Single source of truth for agent directives.** Agent prompts and global rules now live in one canonical location and sync automatically to all platform plugins (OpenCode, Kimi Code, Pi). No more drift between platforms. ## 2026-06-23 - **Pipeline redesigned.** Roles and their order now adapt to task needs instead of running a fixed sequence. The pipeline stops as soon as the verifier accepts - no unnecessary refinement loops. ## 2026-06-22 - **Strict commit protocol.** Agents now follow inspect → propose → execute → stop for every commit. Commit and push authorization are separate - no autonomous pushes without explicit approval. ## 2026-06-20 - **Workflow modes introduced.** Prefix your message with `fein`, `sonar`, or `blitz` to control pipeline depth per turn: - **fein** - full pipeline, no shortcuts - **sonar** - reconnaissance only, no implementation - **blitz** - straight to implementation, skip preamble ## 2026-06-18 - **Permission model overhaul.** Fixed a bug where some agents couldn't read the files they needed despite having permissions configured. Full audit closed gaps across all specialists. Delegation scoping strictly enforced. ## 2026-06-13 - **Skill system.** Agents now load skills based on what the current task needs, not a static preload. Four buckets: always load, load on trigger, defer to specialist, skip if. Skills stay out of context until they're relevant. - **Tool access hierarchy.** Established clear rules for how agents find information: local tools first, then webfetch for known URLs, websearch only for discovery (with explicit justification). ## 2026-06-12 - **Initial release.** 7 specialist agents (orchestrator + adventurer + architect + builder + diagnose + planner + reviewer + writer) with global rules injection. Key patterns from day one: makers don't review their own work, all delegation goes through the orchestrator, structured handoff contracts between agents.