claude-howto/uk/docs/ROADMAP-20260401.md

Roadmap: claude-howto 2026–2027

April 2026 – March 2027 · Dual-Layer Knowledge Base | Full plan: TASKS-20260401.md

---

Vision

Transform claude-howto from a static tutorial repo into a living, dual-audience knowledge system:

• For humans — interactive, scenario-based learning with progressive difficulty, decision trees, and named patterns that experts bookmark
• For AI agents — structured metadata index that agents query before performing Claude Code tasks, making this repo infrastructure, not just content

No competitor targets AI agents as a primary audience. This is the moat.

---

The 7 Pillars

#	Pillar	What it delivers
P1	Fun Layer	Scenario intros + "Try It Now" blocks in every module
P2	AI Agent Index	Generated agent-manifest.json + AGENT-INDEX.md + lookup skill
P3a	Expert Reference (in-module)	Decision trees + named patterns per module
P3b	Expert Reference (cross-module)	RECIPES.md — compound multi-feature workflows
P4	Newcomer Onboarding	quickstart.sh + QUICKSTART.md + difficulty badges
P5	Community Showcase	COMMUNITY-PROJECTS.md — curated user projects
P6	Content Quality	Expand weakest modules; project CLAUDE.md
P7	Living Curriculum	WHATS-NEW.md + version badges + weekly staleness CI action

---

Timeline at a Glance

Apr 2026   May–Jun 2026   Jul–Aug 2026   Sep 2026   Oct–Nov 2026   Dec 2026–Mar 2027
   |             |              |             |             |               |
  [M1]          [M2]           [M3]          [M4]          [M5]            [M6]
Infrastructure  6/10 modules   10/10         Agent layer   Version audit   Self-sustaining
+ hooks/checks  complete       complete      + recipes     complete        system

---

Milestones

M1 — Infrastructure Live · End of April 2026

What ships:

• scripts/quickstart.sh — one-command setup for new users (idempotent)
• QUICKSTART.md — First 15 Minutes visual guide
• Difficulty badges + "What you'll build" previews on all 10 modules
• WHATS-NEW.md + version badges on all modules
• .github/workflows/staleness-check.yml — weekly Monday issue if module unverified 30+ days
• Root CLAUDE.md — project's own configuration as a best-practice example
• scripts/build-agent-index.py — generator that reads all 10 modules → outputs agent-manifest.json + AGENT-INDEX.md
• 06-hooks — full deep pass: 5 complete hook scripts, decision tree, Try It Now, patterns
• 08-checkpoints — full deep pass: 311 → 800+ lines, 3 workflow templates, decision tree, patterns

Why start here: Infrastructure benefits every future phase. Hooks and checkpoints are the weakest modules and most likely to lose new visitors.

---

M2 — 6/10 Modules Complete · End of June 2026

What ships (one deep pass per module):

• 01-slash-commands — scenario intro, decision tree, Try It Now, named patterns
• 02-memory — scenario intro, decision tree, Try It Now, named patterns
• 03-skills — scenario intro, decision tree, Try It Now, named patterns
• 10-cli — scenario intro, decision tree, Try It Now, named patterns
• CI step: validate agent-manifest.json schema on every push

Each module pass = run the generator to confirm valid manifest output.

---

M3 — All 10 Modules Complete · End of August 2026

What ships:

• 04-subagents — full deep pass (incl. "The Multi-Agent Review Pattern")
• 05-mcp — full deep pass
• 07-plugins — full deep pass
• 09-advanced-features — full deep pass

Every module now has: scenario intro, 2+ Try It Now blocks, Mermaid decision tree, 2+ named patterns.

---

M4 — Agent Layer Live · End of September 2026

What ships:

• Final agent-manifest.json covering 100% of modules (generated from completed content)
• AGENT-INDEX.md linked from README.md
• skills/claude-howto-lookup/SKILL.md — lightweight agent skill that queries the manifest
• RECIPES.md — 5+ compound workflows (schema: name, modules-used, problem, solution, expected outcome)
• COMMUNITY-PROJECTS.md — static curated list with PR-based submission format

Why September: The agent index is only meaningful once all 10 modules are content-complete.

---

M5 — Version Audit Complete · End of November 2026

What ships:

• Full version audit: all 10 modules verified against current CC version
• Updated cc_version_verified frontmatter + version badges everywhere
• RECIPES.md expanded to 8+ recipes based on observed community patterns
• Pinned GitHub Discussion: "Share your Claude Code workflows" — signal collection for agent usage

---

M6 — Self-Sustaining System · End of March 2027

What ships / runs continuously:

• /docs-sync-claude-code skill runs after every CC release → WHATS-NEW.md updated
• Agent manifest CI regression: 100% module coverage enforced
• RECIPES.md at 10+ recipes
• COMMUNITY-PROJECTS.md growing organically
• Agent usage signal evaluated → if validated, promote the lookup skill (marketing, asm registry)

---

Deliverables Summary

Deliverable	Type	Phase
scripts/quickstart.sh	Script	P1
QUICKSTART.md	Doc	P1
Root CLAUDE.md	Config	P1
WHATS-NEW.md	Doc	P1
.github/workflows/staleness-check.yml	CI	P1
scripts/build-agent-index.py	Script	P1
10 module deep passes (scenario + Try It Now + decision tree + patterns)	Content	P1–P3
agent-manifest.json (generated)	Data	P4
AGENT-INDEX.md (generated)	Doc	P4
skills/claude-howto-lookup/SKILL.md	Skill	P4
RECIPES.md (5 → 8 → 10+ recipes)	Doc	P4–P6
COMMUNITY-PROJECTS.md	Doc	P4

---

What Is NOT in Scope

Deferred to TODOS.md — do not let these creep in:

• Skill marketplace or installable registry
• Custom website or dashboard
• Completion tracking (cc-progress)
• Community tutorial CI validation
• Auto-generated CONTRIBUTORS.md
• Multi-language translations
• Quiz/assessment infrastructure
• Community voting on projects