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-08-03

• Selective routing by task class. Maestria now guides turns through direct, focused, or full routes: explanations and discovery use direct execution, tiny edits use direct execution or a native builder, ordinary code changes use focused delegation, and complex or high-risk work uses the full pipeline with independent review where supported. The full route is selected for that work or for explicit fein requests, not forced for every turn.
• Explicit modes and route-scaled safeguards. fein selects the full route, sonar is research-only, and blitz is a low-risk/direct bypass that does not waive safety floors. Delegation and review scale with the route. Maker/checker enforcement varies by platform; where separate sessions or tool controls are unavailable, the split is advisory.

2026-07-21

• Mode commands behave consistently across platforms. The fein/sonar/blitz mode commands now work the same way on OpenCode, Kimi Code, Pi, Cursor, and Hermes.

• Compact agent directives. Agent directives compressed to cut orchestrator context usage by ~38% without removing rules or intent. Commit, review, and routing instructions are now grouped together. Rules shared by all specialists now live in one place instead of being repeated seven times. Fixes duplicate skill recommendations in diagnose and architect, a formatting bug, and stale cross-references.

2026-07-14

• Structured work results are now mandatory. After every task, the agent must produce a ## Changes summary table instead of a free-form description. This overrides the usual “write for humans” guidance for this specific output.
• Documentation audit before every commit. The agent now checks four areas before committing: internal docs, the user-facing docs site, the user-facing changelog, and changesets.
• Work results format simplified. The old 3-part narrative format (Overview, File-by-file, Cohesion) is replaced by a table-first format. Context paragraphs are now optional.
• Change-type prefixes for easier scanning. Every entry now uses + (added), ~ (modified), or - (deleted). Breaking changes are marked with ! (e.g. !~). Test files are annotated with (test).
• Work results appear in PR descriptions. The ## Changes section of every PR now includes the structured work results table, so human reviewers see the same summary without anyone having to write it twice.

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 → report 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.