Skills undiscoverable — no keyword routing in AGENTS.md, 3 skills missing from README

[MScottAdams]

Problem

Five skills exist in skills/ but only two are discoverable:

• skills/deft-roadmap-refresh/ — structured roadmap triage workflow
• skills/deft-review-cycle/ — PR review cycle workflow
• skills/deft-swarm/ — parallel agent orchestration workflow

The README.md directory tree and ### Skills section only list deft-build and deft-setup. None of the three above appear there.

AGENTS.md references deft-review-cycle indirectly (line 43, PR conventions) but has no keyword-to-skill routing table. An agent reading AGENTS.md has no way to discover that "swarm", "parallel agents", or "roadmap refresh" should trigger reading a specific SKILL.md.

Observed failure (2026-04-06)

User asked agent to "analyze roadmap for a swarm." Agent had read AGENTS.md but did not read skills/deft-swarm/SKILL.md because nothing in AGENTS.md maps the keyword "swarm" to that skill. Agent improvised a swarm workflow from scratch, missing the structured 6-phase process, file-overlap audit, prompt template, and launch options documented in the skill. The failure was only caught when the user asked whether the agent was using the skill.

Root cause: AGENTS.md is the one file agents reliably read every session, but it contains no skill routing for task-triggered skills.

Recommend: Phase 1 (Adoption Blocker)

Currently tracked in Phase 2 (Documentation & Content Fixes). Recommend promoting to Phase 1 — Adoption Blockers because:

• The failure mode is behavioral (agent skips entire workflows), not cosmetic
• Agents that read AGENTS.md every session have no mechanism to discover skills by keyword
• Demonstrated real session failure — same class as other Phase 1 adoption blockers (Greptile: add review-cycle pre-flight check and recommended settings doc #166, deft-review-cycle skill: add autonomous polling imperative — agents must not stop and ask after pushing #184, feat: Proactively add test coverage after review-fix commits before CI re-run #192)
• Fix is low-complexity (~20-30 lines of markdown across 2 files, no code changes)

Fix

1. AGENTS.md — Add a ## Skills section with a keyword-to-skill routing table:
   • "swarm" / "parallel agents" / "launch agents" -> skills/deft-swarm/SKILL.md
   • "roadmap refresh" / "triage" / "roadmap analysis" -> skills/deft-roadmap-refresh/SKILL.md
   • "review cycle" / "check reviews" -> skills/deft-review-cycle/SKILL.md (currently only an indirect reference)
2. README directory tree — Add deft-review-cycle/, deft-roadmap-refresh/, deft-swarm/ under skills/
3. README — Add a ### Skills section with brief descriptions of all 5 skills

Xrefs

• refactor: migrate project-scope behavioral rules to AGENTS.md/CONVENTIONS.md for platform-agnostic coverage #114 (document global Warp rules / migrate to AGENTS.md)
• Skill auto-discovery: make deft skills work in both user projects and deft development #75 (skill auto-discovery — the deeper platform-level problem)
• Warp doesn't load deft's AGENTS.md by default (but I have a work around) #136 (Warp doesn't auto-load AGENTS.md — related discoverability gap)
• 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-02)

Category: Documentation gap

Summary: Two skills (\deft-roadmap-refresh, \deft-review-cycle) exist in \skills/\ but are absent from the README directory tree and ### 🤖 Skills\ section — contributors and end users have no way to discover them. \AGENTS.md\ references \deft-review-cycle\ (line 37) but not \deft-roadmap-refresh. Skills only surface in ROADMAP.md changelog footnotes.

Relationship to existing issues:

• refactor: migrate project-scope behavioral rules to AGENTS.md/CONVENTIONS.md for platform-agnostic coverage #114 (Phase 2) — Document all global Warp rules; migrate project-scope rules to AGENTS.md — same general effort of making deft's tooling discoverable
• Add skills/deft-sync/SKILL.md — session-start framework sync skill #146 (Phase 2) — \deft-sync\ skill being added; fixing this now sets the correct pattern for all future skill additions

Scope: Small — README directory tree + ### 🤖 Skills\ section update, one-liner addition to AGENTS.md Returning Sessions

Recommendation: Phase 2 alongside #114 — quick win, low effort, improves discoverability for all current and future skills