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.