# Tasks: Dual-Layer Knowledge Base — claude-howto

> Created: 2026-04-01

---

## Milestones

| # | Milestone | Target | Description |
|---|-----------|--------|-------------|
| M1 | Infrastructure Live | End of April 2026 | quickstart.sh, CLAUDE.md, staleness action, agent index generator live; 2 weakest modules upgraded |
| M2 | 6/10 Modules Complete | End of June 2026 | Slash commands, memory, skills, CLI modules fully upgraded; generator producing valid manifest |
| M3 | All 10 Modules Complete | End of August 2026 | Every module has scenario intro, Try It Now blocks, decision tree, named patterns |
| M4 | Agent Layer Live | End of September 2026 | agent-manifest.json + AGENT-INDEX.md generated; lookup skill in repo; RECIPES.md + COMMUNITY-PROJECTS.md live |
| M5 | Version Audit Complete | End of November 2026 | All 10 modules verified against current CC version; RECIPES.md at 8+ recipes |
| M6 | Self-Sustaining System | End of March 2027 | Agent manifest covers 100% modules (CI-validated); RECIPES.md at 10+; community page growing organically |

---

## Phase 1 — Infrastructure & Weak Modules (April 2026)

**Target milestone: M1**

### Pillar 4: Newcomer Onboarding

- [ ] **T-001** — Write `scripts/quickstart.sh`
  - Detects `~/.claude/` directory (creates with user confirmation if missing)
  - Copies first slash command + CLAUDE.md + skill to user's setup
  - Appends agent-discovery line to CLAUDE.md linking to AGENT-INDEX.md
  - Idempotent: skips existing files with a warning, never overwrites
  - Prints next steps on completion

- [ ] **T-002** — Create `QUICKSTART.md` (First 15 Minutes visual guide)
  - Annotated terminal steps as code blocks (avoid PNG screenshots where possible; prefer ASCII or Mermaid)
  - Document which commands produce each visual so they can be re-captured

- [ ] **T-003** — Add difficulty badges to all 10 module READMEs
  - Format: `> 🟢 **Beginner** | ⏱ 30 minutes` at top of each module README
  - Add "What you'll build" bullet preview below the badge

### Pillar 7: Living Curriculum

- [ ] **T-004** — Create `WHATS-NEW.md`
  - Format: `## CC vX.X — DATE` with bullet items per feature change
  - Add at least one entry for current CC version

- [ ] **T-005** — Add version badges to all 10 module READMEs
  - Format: `> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD`
  - Add `cc_version_verified` to each module's frontmatter

- [ ] **T-006** — Create `.github/workflows/staleness-check.yml`
  - Schedule: weekly Monday 09:00 UTC
  - Reads each module's `last_verified` date from frontmatter (use `yq` or 10-line Python script)
  - Creates a GitHub Issue for any module not verified in 30+ days
  - Skips if open issue with same title already exists

### Pillar 6: Content Quality (CLAUDE.md)

- [ ] **T-007** — Create root `CLAUDE.md` for the project
  - Demonstrates best practices as the project's own configuration
  - Documents contributing conventions, module structure, and maintenance workflow

### Pillar 2: AI Agent Index (Generator)

- [ ] **T-008** — Write `scripts/build-agent-index.py`
  - Reads all 10 module README files
  - Extracts: headings (→ topics), code blocks (→ examples with language tags), tables (→ reference data)
  - Outputs `agent-manifest.json` with schema defined in CEO plan
  - Outputs `AGENT-INDEX.md` (human-readable summary)
  - Validates references point to actual files

### Module 08-checkpoints: Full Deep Pass (311 → 800+ lines)

- [ ] **T-009** — Rewrite module intro with real-world scenario
  - Example: "Your refactor just broke 3 things. Here's how checkpoints save you..."

- [ ] **T-010** — Add checkpoint strategy decision tree (Mermaid flowchart)
  - "I want to do X" → follow arrows → land on checkpoint pattern

- [ ] **T-011** — Add 3 workflow templates
  - Safe refactoring workflow
  - A/B testing with checkpoints
  - Disaster recovery workflow

- [ ] **T-012** — Add integration with planning mode section

- [ ] **T-013** — Add Mermaid diagram for checkpoint lifecycle

- [ ] **T-014** — Add 2+ "Try It Now" blocks with verifiable commands
  - Each: context sentence, command to run, expected output description

- [ ] **T-015** — Add "Patterns & Recipes" section with 2+ named patterns
  - Each pattern: problem, solution code, when to use, when NOT to use

### Module 06-hooks: Full Deep Pass

- [ ] **T-016** — Rewrite module intro with real-world scenario
  - Example: "Your CI caught a lint error after 20 minutes. Hooks catch it in 2 seconds..."

- [ ] **T-017** — Add hooks decision tree (Mermaid flowchart)
  - "I want to trigger X when Y happens" → follow arrows → land on hook type

- [ ] **T-018** — Add 5 complete hook examples with full scripts (~80 lines each)
  1. Auto-format on write (prettier/black)
  2. Security scan on commit (trufflehog/bandit)
  3. Test runner on file change
  4. Notification on session end
  5. Prompt validation (block dangerous patterns)

- [ ] **T-019** — Add 2+ "Try It Now" blocks with verifiable commands

- [ ] **T-020** — Add "Patterns & Recipes" section with 2+ named patterns

**M1 Checkpoint: infrastructure live, 2 weakest modules fully upgraded**

---

## Phase 2 — Deep Pass: Strong Modules Batch 1 (May–June 2026)

**Target milestone: M2**

### Module 01-slash-commands: Full Deep Pass

- [ ] **T-021** — Rewrite intro with scenario ("Your teammate just pushed 47 files...")
- [ ] **T-022** — Add decision tree (Mermaid)
- [ ] **T-023** — Add 2+ "Try It Now" blocks
- [ ] **T-024** — Add "Patterns & Recipes" section with 2+ named patterns

### Module 02-memory: Full Deep Pass

- [ ] **T-025** — Rewrite intro with real-world scenario
- [ ] **T-026** — Add decision tree (Mermaid)
- [ ] **T-027** — Add 2+ "Try It Now" blocks
- [ ] **T-028** — Add "Patterns & Recipes" section with 2+ named patterns

### Module 03-skills: Full Deep Pass

- [ ] **T-029** — Rewrite intro with real-world scenario
- [ ] **T-030** — Add decision tree (Mermaid)
- [ ] **T-031** — Add 2+ "Try It Now" blocks
- [ ] **T-032** — Add "Patterns & Recipes" section with 2+ named patterns

### Module 10-cli: Full Deep Pass

- [ ] **T-033** — Rewrite intro with real-world scenario
- [ ] **T-034** — Add decision tree (Mermaid)
- [ ] **T-035** — Add 2+ "Try It Now" blocks
- [ ] **T-036** — Add "Patterns & Recipes" section with 2+ named patterns

### Generator Validation

- [ ] **T-037** — Run `scripts/build-agent-index.py` after each module upgrade; confirm valid manifest output
- [ ] **T-038** — Add CI step: validate agent-manifest.json schema on every push

**M2 Checkpoint: 6/10 modules complete, generator producing valid manifest**

---

## Phase 3 — Deep Pass: Strong Modules Batch 2 (July–August 2026)

**Target milestone: M3**

### Module 04-subagents: Full Deep Pass

- [ ] **T-039** — Rewrite intro with real-world scenario
- [ ] **T-040** — Add decision tree (Mermaid)
- [ ] **T-041** — Add 2+ "Try It Now" blocks
- [ ] **T-042** — Add "Patterns & Recipes" section (e.g., "The Multi-Agent Review Pattern")

### Module 05-mcp: Full Deep Pass

- [ ] **T-043** — Rewrite intro with real-world scenario
- [ ] **T-044** — Add decision tree (Mermaid)
- [ ] **T-045** — Add 2+ "Try It Now" blocks
- [ ] **T-046** — Add "Patterns & Recipes" section with 2+ named patterns

### Module 07-plugins: Full Deep Pass

- [ ] **T-047** — Rewrite intro with real-world scenario
- [ ] **T-048** — Add decision tree (Mermaid)
- [ ] **T-049** — Add 2+ "Try It Now" blocks
- [ ] **T-050** — Add "Patterns & Recipes" section with 2+ named patterns

### Module 09-advanced-features: Full Deep Pass

- [ ] **T-051** — Rewrite intro with real-world scenario
- [ ] **T-052** — Add decision tree (Mermaid)
- [ ] **T-053** — Add 2+ "Try It Now" blocks
- [ ] **T-054** — Add "Patterns & Recipes" section with 2+ named patterns

**M3 Checkpoint: all 10 modules complete and consistent**

---

## Phase 4 — Agent Layer & Cross-Module (September 2026)

**Target milestone: M4**

### Pillar 2: Finalize AI Agent Index

- [ ] **T-055** — Run `scripts/build-agent-index.py` against all 10 completed modules
  - Produce final `agent-manifest.json` with 100% module coverage
  - Produce `AGENT-INDEX.md` and link from README.md

- [ ] **T-056** — Create `skills/claude-howto-lookup/SKILL.md`
  - Reads `agent-manifest.json` to find relevant modules
  - Uses `Read` to load the section
  - Installation: `cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/`

- [ ] **T-057** — Mention lookup skill in quickstart.sh and QUICKSTART.md as optional feature

### Pillar 3b: Cross-Module RECIPES.md

- [ ] **T-058** — Create `RECIPES.md` with 5+ compound workflows
  - Schema per recipe: name, modules-used, problem, solution code block, expected outcome
  - Example: skill + hook + subagent = automated review pipeline
  - Ensure HTML anchors on all major headings for deep-linking

### Pillar 5: Community Showcase

- [ ] **T-059** — Create `COMMUNITY-PROJECTS.md`
  - Static Markdown page with submission format: name, description, link, features used
  - Template entry included
  - PR-based submission instructions

**M4 Checkpoint: agent index live, recipes live, community page live**

---

## Phase 5 — Version Audit & Recipe Expansion (October–November 2026)

**Target milestone: M5**

- [ ] **T-060** — Run full version audit: verify all 10 modules against current CC version
  - Update `cc_version_verified` frontmatter in each module
  - Update version badges

- [ ] **T-061** — Expand `RECIPES.md` to 8+ recipes based on observed community patterns

- [ ] **T-062** — Iterate agent manifest schema if new patterns emerge from completed modules

- [ ] **T-063** — Open pinned GitHub Discussion: "Share your Claude Code workflows"
  - Collect signal on real agent usage to inform future recipe expansion

**M5 Checkpoint: all modules verified current, recipes growing**

---

## Phase 6 — Compound & Sustain (December 2026 – March 2027)

**Target milestone: M6**

- [ ] **T-064** — Run `/docs-sync-claude-code` skill after every CC release; update `WHATS-NEW.md`

- [ ] **T-065** — Ensure agent manifest covers 100% of modules (CI regression test)

- [ ] **T-066** — Grow `RECIPES.md` to 10+ recipes

- [ ] **T-067** — Monitor `COMMUNITY-PROJECTS.md` for organic growth; curate new entries

- [ ] **T-068** — Evaluate agent usage signal from GitHub Discussions; if validated, invest in promoting the lookup skill (marketing, asm registry)

**M6 Checkpoint: the system is self-sustaining**

---

## Deferred (TODOS.md)

These items are out of scope for this plan. Record here to avoid scope creep:

- Skill marketplace / installable registry
- Custom website or dashboard
- Completion tracking infrastructure (cc-progress)
- Community tutorial template with CI validation
- Auto-generated CONTRIBUTORS.md
- Multi-language translations
- Quiz/assessment infrastructure upgrades
- Community voting/review mechanism for COMMUNITY-PROJECTS.md

---

## Task Summary by Phase

| Phase | Tasks | Period | Modules Touched |
|-------|-------|--------|-----------------|
| 1 — Infrastructure & Weak Modules | T-001 to T-020 | April 2026 | 06-hooks, 08-checkpoints + infra |
| 2 — Batch 1 Deep Pass | T-021 to T-038 | May–June 2026 | 01, 02, 03, 10 |
| 3 — Batch 2 Deep Pass | T-039 to T-054 | July–August 2026 | 04, 05, 07, 09 |
| 4 — Agent Layer & Cross-Module | T-055 to T-059 | September 2026 | All (manifest) + new files |
| 5 — Version Audit & Recipes | T-060 to T-063 | October–November 2026 | All (audit) |
| 6 — Sustain | T-064 to T-068 | December 2026–March 2027 | Ongoing |