Agent must scan skills/ before improvising multi-step workflows

[MScottAdams]

Problem

Agents improvise multi-step workflows from scratch instead of checking whether a documented skill already exists. Even when AGENTS.md is read at session start, the agent has no behavioral rule requiring it to scan skills/ before building an ad-hoc process.

Observed failure (2026-04-06)

User asked agent to "analyze roadmap for a swarm." Agent read AGENTS.md (which had no swarm routing — tracked in #147), then improvised a full swarm analysis from scratch. The agent never checked the skills/ directory, missing skills/deft-swarm/SKILL.md which contains a structured 6-phase workflow, file-overlap audit, prompt template, and launch options. The failure was only caught when the user explicitly asked whether the agent was using the skill.

Why #147 alone is insufficient

#147 adds a keyword routing table to AGENTS.md. That fixes the known-keyword case. But:

• New skills added after the routing table was written won't be routed
• Agents encountering unfamiliar workflow keywords will still improvise if the keyword isn't in the table
• The defensive behavior (scan skills/ before improvising) is the safety net for routing table gaps

Relationship to #75

#75 tracks platform-level skill auto-discovery (symlinks, .agents/skills/, etc.). This issue is the behavioral rule that works today without platform changes — a single ! rule that makes agents self-check before improvising.

Fix

1. AGENTS.md — Add a ! rule under Development Process or a new ## Behavioral Gates section:

   ! Before improvising any multi-step structured workflow, scan skills/ for a relevant SKILL.md. If one exists, read and follow it.

2. AGENTS.md — Add a ⊗ anti-pattern:

   ⊗ Improvise a multi-step workflow without first checking whether skills/ contains a matching SKILL.md

3. Candidate meta/lessons.md entry — document the failure pattern: "Agent improvised swarm workflow instead of reading existing skill; root cause was no scan-before-improvise gate"

Xrefs

• Skills undiscoverable — no keyword routing in AGENTS.md, 3 skills missing from README #147 (keyword routing table — the explicit routing fix)
• Skill auto-discovery: make deft skills work in both user projects and deft development #75 (skill auto-discovery — platform-level solution)
• Update deft-swarm: add Oz start_agent orchestration option (Warp Preview only) and dynamic path selection #188 (deft-swarm runtime capability detection)

[MScottAdams]

Roadmap Refresh Analysis (2026-04-06)

Category: Behavioral rule / agent governance

Summary: Add ! rule to AGENTS.md requiring agents to scan skills/ before improvising multi-step workflows. Safety net for #147 routing table gaps (new skills, unfamiliar keywords).

Relationship to existing issues:

• Skills undiscoverable — no keyword routing in AGENTS.md, 3 skills missing from README #147 (Phase 2) — keyword routing table (explicit routing); Agent must scan skills/ before improvising multi-step workflows #200 is the defensive fallback; bundle together (both modify AGENTS.md)
• Skill auto-discovery: make deft skills work in both user projects and deft development #75 (Phase 4) — platform-level skill auto-discovery (long-term solution)
• Update deft-swarm: add Oz start_agent orchestration option (Warp Preview only) and dynamic path selection #188 (Phase 1) — deft-swarm capability detection
• main.md: add rules against mid-task instant-fix drift and skill-context bleed past instruction boundary #198 (Phase 1) — same class: behavioral gate in main.md

Scope: Small — add 2 rules to AGENTS.md, 1 lesson entry to meta/lessons.md. ~5 lines.

Recommendation: Phase 1 — Cleanup. Behavioral governance gap that caused a real session failure. Fix goes in AGENTS.md (loaded every session). Bundle with #147.