diff --git a/docs/MODEL_ROUTING_AGENTS.md b/docs/MODEL_ROUTING_AGENTS.md new file mode 100644 index 0000000..61c8f90 --- /dev/null +++ b/docs/MODEL_ROUTING_AGENTS.md @@ -0,0 +1,35 @@ +# Model Routing in Codex and Claude Code + +Codex and Claude Code use the same `mq-mcp` server, routing tools, and +versioned contracts in VS Code. The local Ollama candidate is advisory; the +active coding agent remains authoritative. + +## Codex example + +For `Review the mq-hal route status implementation`: + +1. Codex calls `mq_route_inspect` with the task. +2. For cross-repo evidence, Codex calls `mq_context_pack`. +3. Codex may call `mq_route_shadow`, but never treats its candidate as accepted. +4. Codex verifies findings against source and tests. +5. Codex escalates when the decision contains an escalation condition. + +## Claude Code example + +Claude Code follows the same sequence because `CLAUDE.md` imports `@AGENTS.md`: + +1. Call `mq_route_inspect` before planning the non-trivial change. +2. Call `mq_context_pack` when the task crosses repository boundaries. +3. Use `mq_route_shadow` only as additional evidence. +4. Keep Claude authoritative for medium/high-risk work. +5. Verify against source and tests; escalate on the same reason codes. + +## Boundaries + +- Do not replace either agent's model backend. +- Do not intercept every editor prompt. +- Do not execute or persist a shadow candidate automatically. +- Do not implement separate routing policy for Codex and Claude. + +The tools are documented by `mq-mcp`; routing policy and decision/outcome +contracts are owned by `mq-agent`. diff --git a/examples/generated-agent-entrypoints/macos-scripts/AGENTS.md b/examples/generated-agent-entrypoints/macos-scripts/AGENTS.md index 6e19fef..2815265 100644 --- a/examples/generated-agent-entrypoints/macos-scripts/AGENTS.md +++ b/examples/generated-agent-entrypoints/macos-scripts/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mcamner-journal/AGENTS.md b/examples/generated-agent-entrypoints/mcamner-journal/AGENTS.md index 7a9cbc3..04e1ea7 100644 --- a/examples/generated-agent-entrypoints/mcamner-journal/AGENTS.md +++ b/examples/generated-agent-entrypoints/mcamner-journal/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mq-agent/AGENTS.md b/examples/generated-agent-entrypoints/mq-agent/AGENTS.md index 6b63072..bbed16f 100644 --- a/examples/generated-agent-entrypoints/mq-agent/AGENTS.md +++ b/examples/generated-agent-entrypoints/mq-agent/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mq-hal/AGENTS.md b/examples/generated-agent-entrypoints/mq-hal/AGENTS.md index ff82513..41a7f6c 100644 --- a/examples/generated-agent-entrypoints/mq-hal/AGENTS.md +++ b/examples/generated-agent-entrypoints/mq-hal/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mq-image-analyze/AGENTS.md b/examples/generated-agent-entrypoints/mq-image-analyze/AGENTS.md index 04169cb..e6f30a1 100644 --- a/examples/generated-agent-entrypoints/mq-image-analyze/AGENTS.md +++ b/examples/generated-agent-entrypoints/mq-image-analyze/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mq-mcp/AGENTS.md b/examples/generated-agent-entrypoints/mq-mcp/AGENTS.md index ec63817..69ca646 100644 --- a/examples/generated-agent-entrypoints/mq-mcp/AGENTS.md +++ b/examples/generated-agent-entrypoints/mq-mcp/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mq-ums/AGENTS.md b/examples/generated-agent-entrypoints/mq-ums/AGENTS.md index f35e923..5e9d49c 100644 --- a/examples/generated-agent-entrypoints/mq-ums/AGENTS.md +++ b/examples/generated-agent-entrypoints/mq-ums/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/mqobsidian/AGENTS.md b/examples/generated-agent-entrypoints/mqobsidian/AGENTS.md index 06dbf47..35e863e 100644 --- a/examples/generated-agent-entrypoints/mqobsidian/AGENTS.md +++ b/examples/generated-agent-entrypoints/mqobsidian/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/examples/generated-agent-entrypoints/repo-signal/AGENTS.md b/examples/generated-agent-entrypoints/repo-signal/AGENTS.md index 2518c8d..8ed1d6d 100644 --- a/examples/generated-agent-entrypoints/repo-signal/AGENTS.md +++ b/examples/generated-agent-entrypoints/repo-signal/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory ${MQ_OBSIDIAN_DIR:-$HOME/mqobsidian}/memory run python commands/emit_observation.py \ @@ -83,19 +79,24 @@ Do not emit secrets, private paths, raw logs, chain-of-thought, or unevidenced o ## Source Intelligence -If `.codegraph/` exists, prefer CodeGraph for source-structure questions before -broad file scans: symbol lookup, callers/callees, impact analysis, code-flow. +If `.codegraph/` exists, use CodeGraph MCP before broad scans: +`codegraph_context` first; use trace/explore/impact as the task requires. +Treat returned source as read; use targeted reads only for missing, stale, or +unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. -Do not use CodeGraph as durable MQ memory. Use `mqobsidian` context packs and -cards for memory, repo boundaries, and prior verified work. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -104,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor diff --git a/scripts/agent_entrypoints.py b/scripts/agent_entrypoints.py index 1ab8119..2262147 100644 --- a/scripts/agent_entrypoints.py +++ b/scripts/agent_entrypoints.py @@ -26,6 +26,7 @@ "## Durable Memory", "## Observation Emission", "## Source Intelligence", + "## MQ Model Routing", "## Writing Rules", "## MQ Skills", "## Fallback Rule", @@ -38,6 +39,11 @@ "--workflow", # required observation field "--evidence-excerpt", # required observation evidence field "Do not store or copy secrets", # secrets / private-path safety rule + "mq_route_inspect", # deterministic route inspection + "mq_context_pack", # equivalent task context for both agents + "mq_route_shadow", # advisory local-model evidence only + "medium/high-risk", # authoritative-agent boundary + "escalation condition", # explicit escalation behavior ] LITERAL_PLACEHOLDERS = ["", ""] diff --git a/templates/AGENTS.md b/templates/AGENTS.md index 5875811..eac8bf8 100644 --- a/templates/AGENTS.md +++ b/templates/AGENTS.md @@ -44,22 +44,19 @@ Stop reading as soon as the task is grounded. - Prefer task packs and agent views over full notes. - Prefer hot/index over pattern notes. -- Do not scan the whole vault by default. -- Do not open multiple pattern notes unless clearly needed. -- Summarize instead of replaying long note bodies. +- Do not scan the whole vault or several pattern notes by default. +- Summarize instead of replaying note bodies. ## Rules - Do not duplicate logic owned by another MQ repo. - Prefer JSON contracts over free-text coupling. -- Keep repo boundaries explicit. -- Use `mqobsidian` only as durable memory, not runtime truth. -- Verify current code behavior, tests, contracts, and CLI behavior in this repo. +- Keep repo boundaries explicit; use `mqobsidian` as memory, not runtime truth. +- Verify current code, tests, contracts, and CLI behavior in this repo. ## Durable Memory -MQ-stack memory lives in `mqobsidian`. Use generated context packs before -reading large docs. +MQ-stack memory lives in `mqobsidian`; use context packs before large docs. `mqobsidian` is durable memory, not live runtime truth. If the task depends on current code behavior, tests, contracts, CLI behavior, or runtime state, verify @@ -67,8 +64,7 @@ in this repo before making claims. ## Observation Emission -After evidence-backed work reveals a reusable pattern, workflow, convention, or -review finding, emit one observation: +After evidence-backed work reveals a reusable pattern or finding, emit one observation: ```bash uv --directory /memory run python commands/emit_observation.py \ @@ -88,13 +84,19 @@ If `.codegraph/` exists, use CodeGraph MCP before broad scans: Treat returned source as read; use targeted reads only for missing, stale, or unsupported detail. Use `mqobsidian` for durable memory and repo boundaries. +## MQ Model Routing + +Before a non-trivial change, call `mq_route_inspect`; for cross-repo work also +call `mq_context_pack`. Treat `mq_route_shadow` only as advisory evidence. +Codex or Claude stays authoritative for medium/high-risk work. Verify against +repo code/tests and escalate when the router reports an escalation condition. + ## Writing Rules When creating notes, summaries, or exports: - separate facts, interpretation, and recommendation -- keep outputs compact -- preserve timestamps and provenance when relevant +- keep outputs compact; preserve timestamps and provenance when relevant - prefer links over duplicated prose - avoid raw dumps @@ -103,9 +105,8 @@ or machine-specific private paths. ## MQ Skills -Use repo-local skills from `.agents/skills/` (Codex) and `.claude/skills/` -(Claude Code); route by frontmatter `description`. Near-universal: -`mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. +Use `.agents/skills/` (Codex) and `.claude/skills/` (Claude); route by frontmatter +`description`. Common: `mq-writing-plans`, `mq-worktree-safe`, `mq-secrets-public-safe`. ## Codex Governor