# 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
