Skip to content

Roadmap

Jump to bottom
McAmner edited this page Jun 2, 2026 · 1 revision

mq-agent Roadmap

mq-agent is a terminal-native workflow orchestration runtime for the mq ecosystem.

It connects safe local execution, repo intelligence, MCP tools, mqlaunch workflows, and semantic repository memory into one controlled, operator-driven orchestration surface.

Current status

Current project phase:

v1.4.0 — mq-image-analyze perception tool integration (done)
Next:    define v1.5.0

Completed foundation:

  • Terminal-native CLI
  • Planner / Executor / Verifier architecture
  • Safety modes
  • Tool registry
  • repo-signal integration (v0.7.0+ with version guard)
  • mq-mcp bridge (mq-mcp v1.3.0, 66 tools, safety classes A–D)
  • mqlaunch integration
  • mq-image-analyze perception tool integration
  • Command surface documentation
  • Semantic repository memory
  • GitHub Pages documentation
  • Release hygiene and docs consistency checks
  • Protected main workflow
  • Browser-assisted verification workflows (read-only, operator-approved)
  • Declarative task runner with {{step:name}} templates
  • Controlled specialist orchestration
  • run_task tool — task chaining

Release map

Version Theme Status
v0.1.0 Project foundation Done
v0.2.0 Repo productization Done
v0.3.0 Local tool orchestration via mq-mcp Done
v0.4.0 mqlaunch integration Done
v0.4.1 Consistency, readability and release hygiene Done
v0.5.0 Semantic repository memory Done
v0.5.1 Semantic memory hardening Done
v0.5.2 mcp start/stop process management Done
v0.6.0 Controlled agent loops (task runner) Done
v0.6.1 Orchestration stabilization Done
v0.7.0 Browser-assisted verification workflows Done
v0.8.0 Controlled specialist orchestration Done
v0.9.0 Orchestration kernel consolidation Done
v1.0.0 Stable orchestration platform Done
v1.1.0 mq-mcp review runtime integration Done
v1.2.0 mq-mcp semantic memory + risk review routing Done
v1.3.0 Architecture memory, model-selection, learn Done
v1.4.0 mq-image-analyze perception tool integration Done

v1.4.0 — mq-image-analyze perception tool integration

Goal: route mq-image-analyze visual perception tools through mq-agent. mq-agent delegates image inspection to mq-image-analyze and passes structured visual context onward to mq-mcp or the user.

Items:

  • mq-agent run-tool observe_architecture — delegate to mq-image-analyze observe_architecture tool
  • mq-agent run-tool image_ocr — delegate to mq-image-analyze image_ocr tool
  • Route mq-agent review --architecture to include visual_architecture_observation.v1 context
  • Document mq-image-analyze tool registration in docs/MQ_ECOSYSTEM.md
  • Smoke tests: mq-agent → mq-image-analyze → structured visual context → mq-mcp

Hard boundary (unchanged): mq-agent must never implement image analysis locally. Delegation and rendering only.

Completed

v0.1.0 — Foundation

  • CLI foundation
  • Project structure
  • Core agent concepts
  • Basic docs
  • Local development setup

v0.2.0 — Productization

  • README polish
  • GitHub Pages front door
  • Demo docs
  • Safety docs
  • Release checklist
  • repo-signal scoring
  • Publish checklist proof

v0.3.0 — Local tool orchestration via mq-mcp

  • MCP bridge
  • MCP status command
  • MCP tool listing
  • MCP tool safety classes
  • Tool metadata inspection
  • run-tool command
  • Docs for MCP integration
  • Tests for local tool orchestration

v0.4.0 — mqlaunch integration

  • mqlaunch agent
  • Direct mqlaunch agent commands
  • 12-item mqlaunch agent menu
  • 6 direct prompt commands
  • smoke test for mqlaunch bridge
  • mqlaunch integration docs
  • command surface docs
  • README proof updates

v0.4.1 — Consistency, readability and release hygiene

  • Source readability pass
  • Docs consistency guard
  • Command count guard
  • COMMAND_SURFACE.md as single source of truth
  • Release hygiene cleanup
  • GitHub release
  • GitHub Pages deployment
  • Protected main workflow

v0.5.0 — Semantic repository memory

  • mq-agent memory status
  • mq-agent memory build
  • mq-agent memory refresh --approve
  • repo-signal semantic upload bridge
  • vector store status detection
  • dry-run default for memory build
  • explicit approval for memory refresh
  • semantic memory docs
  • memory smoke test
  • tests for memory helpers
  • README semantic memory section
  • GitHub release
  • GitHub Pages deployment

v0.5.1 — Semantic memory hardening

  • mq-agent memory doctor — diagnose environment with per-item status and actionable fixes
  • mq-agent memory doctor --json — machine-readable diagnostics
  • mq-agent memory status --json — machine-readable status output
  • Example output in docs/SEMANTIC_MEMORY.md
  • Memory proof section in README with verified output
  • release-check.sh includes memory smoke
  • Missing vector store reported clearly with fix instruction
  • Missing repo-signal reported clearly with fix instruction
  • Refresh never runs without --approve
  • 18 CLI-level tests — dry-run default, approval gate, JSON output, doctor diagnostics
  • Tests pass locally (94 total)
  • GitHub Actions pass
  • GitHub release v0.5.1 exists

v0.6.0 — Controlled agent loops (task runner)

  • mq-agent task list — list available YAML task workflow files
  • mq-agent task list --json — machine-readable task list
  • mq-agent task run <name> — execute declarative YAML workflow via tool registry
  • mq-agent task run <name> --dry-run — preview steps without execution
  • mq-agent task run <name> --json — machine-readable step results
  • mq_agent/core/task_runner.py — load_task, run_task, find_task_files
  • Task lookup by filename stem OR internal YAML name: field
  • tests/test_task_runner.py — 18 tests
  • Tool registry hardened — _EXCLUDE_DIRS, write_file, repo_signal_json, timeout 120s
  • Task YAML args corrected (suffix→pattern, n→limit, ci.yml→tests.yml)
  • 134 tests total

v0.6.1 — Orchestration stabilization

  • Tool registry hardened — excludes, write_file, repo_signal_json, timeout 120s
  • Task YAML args corrected (suffix→pattern, n→limit, ci.yml→tests.yml)
  • {{step:name}} template system — string args resolved from prior step output
  • run_task tool registered — tasks can chain other tasks
  • Version guard for repo-signal — clear error when too old
  • 204 tests total

v0.7.0 — Browser-assisted workflows

  • mq-agent browser inspect <url> — structured URL metadata: title, description, h1/h2, links, word count
  • mq-agent browser summarize <url> — plain-text content summary
  • mq-agent browser verify-release <url> — release page field verification; --tag <v> for version check
  • mq_agent/tools/browser_tools.py — fetch_url, inspect_url, summarize_url, verify_release_url
  • URL safety gate: blocks file://, ftp://, data:, javascript: schemes
  • Browser tools registered in TOOL_REGISTRY — usable in task YAML workflows
  • tasks/browser_verify.yaml — declarative browser verification task
  • tests/test_browser.py — 27 tests (URL safety, HTML parsing, CLI commands)
  • 161 tests total

Non-goals (v0.7.0)

  • No credential handling
  • No hidden form submission
  • No checkout/payment flows
  • No unsafe automation

Architectural guardrails (v0.7.0)

  • Browser workflows must be read-only by default
  • No credential capture or storage
  • No hidden form submission
  • No purchase, booking or account actions
  • No autonomous browser control
  • All browser actions require explicit operator confirmation
  • Browser results must be inspectable and citeable
  • Browser workflow logic must use existing task/orchestration systems
  • Do not create a second workflow engine

v0.8.0 — Controlled specialist orchestration

This phase coordinates specialized agents through the existing task runner and safety model. Each agent declares its purpose, safety class, allowed tools, and failure behavior via AgentManifest.

The goal is planner-driven specialization, not autonomous multi-agent behavior.

  • mq-agent swarm list — list swarm configs with agents and safety classes
  • mq-agent swarm plan <config> — dry plan; no API, no execution
  • mq-agent swarm run <config> [path] — execute swarm, unified report
  • mq-agent swarm audit [path] — audit + signal + docs
  • mq-agent swarm release-check [path] — CI + audit + release
  • AgentManifest — declares purpose, safety_class, allowed_tools, requires_approve, output_contract, failure_behavior
  • SwarmRunner — dispatches agents, collects results, handles failures per manifest policy
  • --approve gate for write-capable agents
  • Dry-run requires no API key
  • Built-in swarm configs: audit, release-check, ci
  • tests/test_swarm.py — 29 tests
  • 190 tests total

v0.9.0 — Orchestration kernel consolidation

Goal:

Stabilize orchestration boundaries and normalize runtime coordination before the v1.0.0 stable release. No new features — only consolidation.

v0.9.0 focus

  • Normalize orchestration lifecycle — planner / executor / verifier contracts
  • Unify task execution model — consistent step contracts across task runner and specialist orchestration
  • Separate orchestration from presentation — CLI output must not bleed into core logic
  • Formalize runtime provider layer — tool registry, MCP bridge, signal integration
  • Reduce architectural drift — remove or document any divergent patterns
  • Strengthen state consistency — no silent state across step boundaries
  • Improve workflow composability — tasks and swarm configs are interchangeable primitives

Non-goals (v0.9.0)

  • No redesign of TUI or CLI surface
  • No new autonomous systems
  • No additional orchestration modes
  • No uncontrolled browser automation
  • No duplicate orchestration engines

v0.9.0 checklist

Orchestration lifecycle

  • Document the boundary between PlanStep (executor loop) and StepResult (task runner) — docstrings in core/state.py, core/task_runner.py, and test_orchestration_contract.py
  • Document SwarmRunner as a separate runtime mode, not a competing implementation of Executor — docstring in core/swarm.py
  • Verify executor stop-on-failure behavior is consistent with task runner error propagation — confirmed by design: executor stops on failure (safety), task runner collects all results (batch)
  • Verify AgentState.to_dict() output matches JSON output format used by CLI commands — locked by test_agent_state_to_dict_shape_is_stable()

Presentation separation

  • Extract orchestration logic out of main.py — doctor() logic → core/diagnostics.py; rendering helpers → cli/render.py
  • Centralize status/result rendering — cli/render.py owns all Rich output helpers; core has no CLI imports

Runtime provider layer

  • Define ~/.mq-agent/config.json schema — MqAgentConfig dataclass in mq_agent/config.py; schema documented in module docstring
  • Wire Planner to use MqAgentConfig — load_config().effective_model() replaces direct env var read
  • Enforce tool registry signature contract — test_tool_registry_has_no_positional_only_params() passes

Contract tests

  • Extend tests/test_orchestration_contract.py — 7 new shape/delegation tests locking PlanStep, StepResult, AgentManifest, AgentState
  • Test that run_task tool delegates correctly to task_runner.run_task — test_run_task_tool_delegates_to_task_runner()
  • Test that AgentManifest.allowed_tools entries are a subset of TOOL_REGISTRY keys — test_agent_manifest_allowed_tools_must_be_subset_of_registry()

Release

  • 229 tests pass
  • Green CI
  • GitHub release v0.9.0 published

v1.0.0 — Stable orchestration platform

Goal:

Publish mq-agent as a stable, documented orchestration runtime for the mq ecosystem. The platform is stable when its contracts are locked and its orchestration boundaries are enforced.

v1.0.0 requirements

  • Stable CLI command surface — COMMAND_SURFACE.md is single source of truth
  • Stable config format — MqAgentConfig dataclass with documented ~/.mq-agent/config.json schema
  • Stable safety model — read-only / suggest / execute / approve gates
  • Stable memory model — dry-run default, explicit --approve
  • Stable mqlaunch integration — bridge tested, menu + direct commands
  • Stable mq-mcp integration — start/stop, tool listing, safety classes
  • Stable repo-signal integration — version guard, suggest.v1, signal_json
  • Stable orchestration contracts — planner / executor / verifier / task runner (v0.9.0)
  • Extract orchestration logic from main.py — cli/render.py + core/diagnostics.py
  • Wire Planner to MqAgentConfig — load_config().effective_model()
  • Complete docs — ARCHITECTURE.md updated with full module map, runtime modes, config schema, safety model
  • Complete examples — EXAMPLES.md covers all commands: task, browser, swarm, memory, mcp, score, signal
  • Complete release checklist — release-check.sh verified
  • Green CI
  • Protected main branch
  • Versioned GitHub releases — v0.6.0, v0.7.0, v0.8.0 published on GitHub
  • GitHub Pages documentation
  • No known critical safety gaps

Post-v1.0 roadmap

v1.1.0 — mq-mcp review runtime integration

Goal: route repo-aware cognition through mq-mcp; mq-agent surfaces findings without re-implementing review logic.

The formal boundary is defined in mq-mcp/docs/ORCHESTRATION_CONTRACT.md:

  • mq-agent may auto-invoke Class A/B tools without user confirmation
  • Class C (write) and Class D (subprocess) tools require explicit user approval
  • mq-agent must never reimplement review logic locally
  • mq-agent must not assume mq-mcp maintains session state between calls

Items:

  • mq-agent review command — calls review_file / review_diff / review_repo via MCPBridge; displays severity summary in terminal
  • Route --security and --architecture flags to mq-mcp review contracts
  • Route --risk only when supported by the installed mq-mcp version (v1.5.0 risk layer in mq-mcp)
  • Display mq-mcp severity findings (RISK, ARCHITECTURE, WARNING, etc.) without reinterpreting — pass through as-is
  • --dry-run on all review commands — plan output without executing
  • Keep TUI/session UX in mq-agent while leaving cognition logic in mq-mcp
  • Smoke tests: mq-agent → mq-mcp review_file / review_diff / review_repo
  • validate_orchestration_contract invocable from mq-agent doctor checks
  • Surface mq-mcp architecture-memory context (list_architecture_decisions, get_architecture_decision) — shown automatically after review findings when available
  • Model-selection policy: --fast flag on review commands passes fast=True to mq-mcp; mq-mcp routes to Class A tools internally

Implementation plan:

  1. Add CLI command group:
    • mq-agent review file <path>
    • mq-agent review diff
    • mq-agent review repo [path]
  2. Add MCPBridge review helpers:
    • review_file(path, flags)
    • review_diff(flags)
    • review_repo(path, flags)
  3. Add pass-through renderer:
    • severity summary
    • grouped findings
    • source file / line when available
    • raw JSON with --json
  4. Add flags:
    • --risk
    • --security
    • --architecture
    • --json
    • --approve only if future write-capable review tools require it
  5. Add tests:
    • command invokes correct mq-mcp tool
    • no local review logic exists in mq-agent
    • severity labels are passed through unchanged
    • missing mq-mcp tool gives clear error
    • validate_orchestration_contract appears in doctor output

Hard boundary:

mq-agent must not implement:

  • severity scoring
  • architecture reasoning
  • risk classification
  • semantic retrieval
  • review heuristics
  • drift detection

mq-agent may implement:

  • CLI command routing
  • MCPBridge calls
  • result rendering
  • JSON output
  • approval gates
  • doctor checks
  • orchestration contract validation

v1.1.0 definition of done:

  • mq-agent review file works through mq-mcp
  • mq-agent review diff works through mq-mcp
  • mq-agent review repo works through mq-mcp
  • --json output is stable and tested
  • severity labels are passed through unchanged
  • no local review engine exists in mq-agent
  • doctor verifies mq-mcp orchestration contract
  • smoke tests pass against mq-mcp v1.3.0+
  • docs updated:
    • COMMAND_SURFACE.md
    • MCP_INTEGRATION.md
    • EXAMPLES.md
    • ROADMAP.md

Non-goals:

  • No duplicate review engine in mq-agent
  • No architecture reasoning implementation in mq-agent
  • No separate semantic retrieval runtime in mq-agent

v1.2.0 — mq-mcp semantic memory + risk review routing

Goal: surface mq-mcp semantic memory (v1.4.0) and risk analysis (v1.5.0) in mq-agent workflows.

Items:

  • mq-agent memory search <query> — calls search_semantic_memory via MCPBridge; renders key/excerpt table; degrades gracefully when mq-mcp v1.4.0 tool is absent
  • mq-agent memory store <key> <value> --approve — calls store_semantic_memory (Class C write tool); requires --approve; --dry-run supported
  • Risk review routing: mq-agent review --risk invokes risk_review_file / risk_review_diff when available in mq-mcp ≥ v1.5.0 — already implemented in bridge
  • mq-agent mcp status extended: shows semantic memory item count and contract freshness from validate_orchestration_contract when tools are available

Learned review patterns (implemented in v1.3.0):

  • mq-agent learn status — check mq-mcp learn system availability
  • mq-agent learn search <query> — search learned review patterns
  • mq-agent learn explain <pattern-id> — fetch pattern explanation

Non-goal:

mq-agent must not train, infer, mutate or store learning data directly. All learning and memory behavior belongs in mq-mcp.

v1.3.0 — Architecture memory, model-selection, learn commands

  • Architecture-memory context in review — list_architecture_decisions surfaced automatically after review findings when tool is available
  • get_architecture_decision bridge method for fetching individual decisions
  • --fast flag on review file/diff/repo — passes fast=True to mq-mcp for Class A tool routing
  • mq-agent learn status — check mq-mcp learn system
  • mq-agent learn search <query> — search learned patterns (read-only)
  • mq-agent learn explain <pattern-id> — fetch pattern explanation (read-only)
  • Optional Ollama-backed learn extraction documented as an mq-mcp-owned policy
  • MultiMCPBridge._call_optional_tool() — silent None when tool not available
  • 24 new tests (292 total)

Long-term ideas

These are intentionally not scheduled yet.

  • Local model fallback
  • Ollama learn provider in mq-mcp
  • Visual TUI dashboard
  • Repository health history
  • Agent-generated release notes
  • Agent-generated docs diffs
  • Cross-repo ecosystem memory
  • Integration with macos-scripts
  • Integration with mq-hal
  • Integration with mq-ums
  • Integration with mq-mcp tool safety map
  • Semantic memory comparison between releases

Research / Experimental

These ideas are architecturally interesting but conflict with the current orchestration philosophy. They are not on the roadmap mainline. Any implementation must be isolated, gated, and not merged into the core runtime.

  • HAL-style conversational shell — autonomous conversational loops break the explicit approval model
  • Autonomous looping agents — recursive agent execution without operator checkpoints
  • Self-modifying task graphs — tasks that generate and run new tasks at runtime
  • Uncontrolled browser automation — beyond operator-approved, read-only browser workflows

Design principles

mq-agent should remain:

  • terminal-native
  • explicit
  • safe by default
  • observable
  • testable
  • local-first
  • repo-aware
  • dry-run friendly
  • approval gated
  • useful without hiding execution

The model should assist the operator, not replace the operator.

Safety principles

mq-agent must never:

  • run destructive commands silently
  • upload memory silently
  • commit secrets
  • bypass approval gates
  • hide shell execution
  • treat AI output as automatically trusted
  • mutate repositories without explicit approval

Every powerful feature must have:

  • dry-run mode
  • JSON output when useful
  • clear status output
  • test coverage
  • documentation
  • failure behavior

Current recommended next step

Start v1.1.0 implementation:

  • Add mq-agent review command group
  • Route review_file, review_diff and review_repo through MCPBridge
  • Display mq-mcp severity findings without reinterpretation
  • Route --security and --architecture flags to mq-mcp review contracts
  • Route --risk only when supported by the installed mq-mcp version
  • Add smoke tests for mq-agent -> mq-mcp review runtime calls
  • Add validate_orchestration_contract to mq-agent doctor checks
  • Update COMMAND_SURFACE.md, MCP_INTEGRATION.md and EXAMPLES.md

mq-agent

Clone this wiki locally