jared/cc-os

Watch

Fork 0

Add map-router agent and map-making skill for reroute selection #869

New issue

Closed

opened 2026-10-01 14:26:05 +00:00 by jared · 2 comments

jared commented

2026-10-01 14:26:05 +00:00

Owner

Problem

ADR-0258 decision 3 adds a map-router agent (model opus) that selects an approved map and an entry node for a reroute, with a preloaded map-making skill that teaches how to read maps. Neither exists. AgentType::ALL (model/agent_type.rb:7) globs agents/*.md, so the reroute gate ticket cannot dispatch map-router until agents/map-router.md exists.

Reproduce

n/a: new agent and skill prose, nothing to reproduce.

Approach

Slice 1 is selection only. Drafting (maps/drafts/<name>.yaml) is slice 4; do not write it here.

plugins/os-sdlc/agents/map-router.md: frontmatter description:, tools: Read, Glob, Grep, Bash (Bash only for os-sdlc-gate and os-sdlc-subagent-stop), skills: [os-sdlc:map-making], model: opus. Body: input = the requester handoff (situation, misfit, work already done; handoff in the brief) and the brief fact approved_maps (the joined approved maps, each under a Map: <name> line; #885 adds the fact). map-router is an in-map node gated by reroute (ADR-0259 decision 7). Job: choose one approved map whose fits: matches the situation, and choose the entry node = the first node in that map's entries: whose work is not yet verified ("bridging"). It never edits code or maps. Run os-sdlc-gate DISPATCH_ID until it is green, then stop with a YAML handoff: summary:, map: <name>, node: <entry node>, situation: and misfit: (carried from the requester handoff; the reroute gate refuses a handoff without them). If no approved map fits, say so in summary: and leave out map:; the gate fails and the run returns to the orchestrator at needs-orchestrator. Submit with os-sdlc-subagent-stop like agents/seam-designer.md:65-68.

plugins/os-sdlc/skills/map-making/SKILL.md: how to read a map — header (name, fits, entries, entry, dispatch_cap, ticket_shape), nodes (agent nodes, routing nodes, and waiting nodes such as needs-orchestrator), verdict.source, gates with expect, edges and bound, terminals; why every entry must reach merge-ready through [required-work, suite]; how to pick the entry node from the work already done. Frontmatter has description: and when_to_use:; per cc-os naming it has NO name: field, and there is no commands/ directory.

Authoring guidance (user ruling, 2026-10-01, verbatim):
"Use existing project agents/skills (plugins/os-sdlc/agents/.md, plugins/os-sdlc/skills/) as examples, plus the orwell-writing skill, the os-sdlc:technical-communication skill, cc-architect (plugins/cc-architect, incl. references/conventions/cc-os-naming.md: never name: in SKILL.md frontmatter, no commands/ dir), and the mattpocock-skills:writing-for-agents skill, to guide language and structure."

Required work:

Add the map-router agent — check: present skills: [os-sdlc:map-making] in plugins/os-sdlc/agents/map-router.md
Pin the agent model — check: present model: opus in plugins/os-sdlc/agents/map-router.md
Add the map-making skill — check: present when_to_use: in plugins/os-sdlc/skills/map-making/SKILL.md
Keep the skill frontmatter free of a name field — check: absent name: map-making in plugins/os-sdlc/skills/map-making/SKILL.md
Name the output contract — check: present misfit: in plugins/os-sdlc/agents/map-router.md
Name the approved maps fact — check: present approved_maps in plugins/os-sdlc/agents/map-router.md

Orchestrator work: run bin/refresh-plugins after merge; restart the session before the first live map-router dispatch (new agent types load at session start).

Acceptance criteria

Given the map-router agent file, when it is read, then it names its input as the requester handoff plus the approved_maps fact, and its output as a YAML handoff with summary:, map:, node:, situation:, and misfit:.
Given the agent file, when it is read, then it forbids code and map edits and tells the agent to leave out map: when no approved map fits.
Given the map-making skill, when it is read, then it explains fits:, entries:, and the rule that every entry reaches merge-ready through the required-work and suite gates.

Owner sketch

# no new class: agents/map-router.md and skills/map-making/SKILL.md prose only

Origin

Trigger: user ruling on the map reroute design, 2026-10-01 (ADR-0258)
Improvised this session: none
Chain: no actor chooses a new map ← no map-router agent exists ← DESIGN (docs/adr/0258 decision 3)
Root candidate: #859
Where: plugins/os-sdlc/agents/
Session: 55a56279-83ee-47d5-a21e-ee67f9e28abd
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/55a56279-83ee-47d5-a21e-ee67f9e28abd.jsonl

Parent: #859

## Problem ADR-0258 decision 3 adds a `map-router` agent (model opus) that selects an approved map and an entry node for a reroute, with a preloaded map-making skill that teaches how to read maps. Neither exists. `AgentType::ALL` (model/agent_type.rb:7) globs `agents/*.md`, so the reroute gate ticket cannot dispatch `map-router` until `agents/map-router.md` exists. ## Reproduce n/a: new agent and skill prose, nothing to reproduce. ## Approach Slice 1 is selection only. Drafting (`maps/drafts/<name>.yaml`) is slice 4; do not write it here. `plugins/os-sdlc/agents/map-router.md`: frontmatter `description:`, `tools: Read, Glob, Grep, Bash` (Bash only for `os-sdlc-gate` and `os-sdlc-subagent-stop`), `skills: [os-sdlc:map-making]`, `model: opus`. Body: input = the requester handoff (situation, misfit, work already done; `handoff` in the brief) and the brief fact `approved_maps` (the joined approved maps, each under a `Map: <name>` line; #885 adds the fact). map-router is an in-map node gated by `reroute` (ADR-0259 decision 7). Job: choose one approved map whose `fits:` matches the situation, and choose the entry node = the first node in that map's `entries:` whose work is not yet verified ("bridging"). It never edits code or maps. Run `os-sdlc-gate DISPATCH_ID` until it is green, then stop with a YAML handoff: `summary:`, `map: <name>`, `node: <entry node>`, `situation:` and `misfit:` (carried from the requester handoff; the `reroute` gate refuses a handoff without them). If no approved map fits, say so in `summary:` and leave out `map:`; the gate fails and the run returns to the orchestrator at `needs-orchestrator`. Submit with `os-sdlc-subagent-stop` like `agents/seam-designer.md:65-68`. `plugins/os-sdlc/skills/map-making/SKILL.md`: how to read a map — header (`name`, `fits`, `entries`, `entry`, `dispatch_cap`, `ticket_shape`), nodes (agent nodes, routing nodes, and waiting nodes such as `needs-orchestrator`), `verdict.source`, `gates` with `expect`, edges and `bound`, terminals; why every entry must reach `merge-ready` through `[required-work, suite]`; how to pick the entry node from the work already done. Frontmatter has `description:` and `when_to_use:`; per cc-os naming it has NO `name:` field, and there is no `commands/` directory. Authoring guidance (user ruling, 2026-10-01, verbatim): "Use existing project agents/skills (plugins/os-sdlc/agents/*.md, plugins/os-sdlc/skills/*) as examples, plus the orwell-writing skill, the os-sdlc:technical-communication skill, cc-architect (plugins/cc-architect, incl. references/conventions/cc-os-naming.md: never `name:` in SKILL.md frontmatter, no commands/ dir), and the mattpocock-skills:writing-for-agents skill, to guide language and structure." Required work: 1. Add the map-router agent — check: present `skills: [os-sdlc:map-making]` in `plugins/os-sdlc/agents/map-router.md` 2. Pin the agent model — check: present `model: opus` in `plugins/os-sdlc/agents/map-router.md` 3. Add the map-making skill — check: present `when_to_use:` in `plugins/os-sdlc/skills/map-making/SKILL.md` 4. Keep the skill frontmatter free of a name field — check: absent `name: map-making` in `plugins/os-sdlc/skills/map-making/SKILL.md` 5. Name the output contract — check: present `misfit:` in `plugins/os-sdlc/agents/map-router.md` 6. Name the approved maps fact — check: present `approved_maps` in `plugins/os-sdlc/agents/map-router.md` Orchestrator work: run `bin/refresh-plugins` after merge; restart the session before the first live map-router dispatch (new agent types load at session start). ## Acceptance criteria 1. Given the map-router agent file, when it is read, then it names its input as the requester handoff plus the `approved_maps` fact, and its output as a YAML handoff with `summary:`, `map:`, `node:`, `situation:`, and `misfit:`. 2. Given the agent file, when it is read, then it forbids code and map edits and tells the agent to leave out `map:` when no approved map fits. 3. Given the map-making skill, when it is read, then it explains `fits:`, `entries:`, and the rule that every entry reaches `merge-ready` through the `required-work` and `suite` gates. ## Owner sketch ```ruby # no new class: agents/map-router.md and skills/map-making/SKILL.md prose only ``` ## Origin - Trigger: user ruling on the map reroute design, 2026-10-01 (ADR-0258) - Improvised this session: none - Chain: no actor chooses a new map ← no map-router agent exists ← DESIGN (docs/adr/0258 decision 3) - Root candidate: #859 - Where: plugins/os-sdlc/agents/ - Session: 55a56279-83ee-47d5-a21e-ee67f9e28abd - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/55a56279-83ee-47d5-a21e-ee67f9e28abd.jsonl Parent: #859

jared added the

plugin/os-sdlc

filed-by/user

labels

2026-10-01 14:26:05 +00:00

~~jared referenced this issue 2026-10-01 14:26:18 +00:00~~

Add the reroute gate and the reroute landing with the REROUTE block #873

jared referenced this issue

2026-10-01 14:26:18 +00:00

Document reroute recovery in implement skill and escalation procedure #874

jared added the

ready-for-agent

label

2026-10-01 14:26:43 +00:00

jared added a new dependency

2026-10-01 14:27:27 +00:00

#873 Add the reroute gate and the reroute landing with the REROUTE block

jared added a new dependency

2026-10-01 14:27:27 +00:00

#874 Document reroute recovery in implement skill and escalation procedure

jared referenced this issue

2026-10-01 14:27:34 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared referenced this issue

2026-10-01 15:26:47 +00:00

Document map drafting and the promote-map step #882

jared referenced this issue

2026-10-01 15:26:51 +00:00

Route the ticket map waiting node to an in-map map-router node #885

jared removed a dependency

2026-10-01 15:29:27 +00:00

#873 Add the reroute gate and the reroute landing with the REROUTE block

jared added a new dependency

2026-10-01 15:29:28 +00:00

#885 Route the ticket map waiting node to an in-map map-router node

jared referenced this issue

2026-10-01 15:29:38 +00:00

Add the poodr-guard-implementation map for green guard tests #876

jared referenced this issue

2026-10-01 15:29:41 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared added a new dependency

2026-10-01 15:29:48 +00:00

#876 Add the poodr-guard-implementation map for green guard tests

jared added a new dependency

2026-10-01 15:29:50 +00:00

#882 Document map drafting and the promote-map step

jared commented

2026-10-01 16:18:06 +00:00

Author

Owner

Work started on branch ticket-869 (os-sdlc pipeline, map poodr-ticket-implementation).

jared commented

2026-10-01 16:24:06 +00:00

Author

Owner

Resolution

Done: map-router agent (opus, skills [os-sdlc:map-making], reads requester handoff + approved_maps, writes summary/map/node/situation/misfit, leaves out map: when nothing fits, never edits code or maps) and the map-making skill (fits, entries, the merge-ready rule through required-work and suite). Deviation: ran on map poodr-implementation instead of poodr-ticket-implementation because the ticket is prose only (implement skill rule). Note: new agent types load at session start, so a live map-router dispatch needs a session restart.

Evidence: main bcd0a3cc (Runner commit, implementation 1 implementation_complete, 8 dispatches, 0 retries), History row; six Required-work checks verified by grep; bin/test on main: 9 suites passed.

Follow-ups: none

## Resolution **Done:** map-router agent (opus, skills [os-sdlc:map-making], reads requester handoff + approved_maps, writes summary/map/node/situation/misfit, leaves out map: when nothing fits, never edits code or maps) and the map-making skill (fits, entries, the merge-ready rule through required-work and suite). Deviation: ran on map poodr-implementation instead of poodr-ticket-implementation because the ticket is prose only (implement skill rule). Note: new agent types load at session start, so a live map-router dispatch needs a session restart. **Evidence:** main bcd0a3cc (Runner commit, implementation 1 implementation_complete, 8 dispatches, 0 retries), History row; six Required-work checks verified by grep; bin/test on main: 9 suites passed. **Follow-ups:** none

jared closed this issue

2026-10-01 16:24:06 +00:00

jared referenced this issue

2026-10-01 18:17:51 +00:00

no pipeline path for guard/characterization tests (unexpected_pass escalation) #859

jared referenced this issue from a commit

2026-10-01 18:24:32 +00:00

feat(os-sdlc): Audited POODR boundaries for #869; prose-only agent and skill, all six WORK items present, AgentType.parse contract protected. (#869)

jared referenced this issue from a commit

2026-10-01 18:24:32 +00:00

docs: #869 History row

jared referenced this issue