6d1e0ae4af
* refactor(ci): shift quality checks to pre-commit, CI as 2nd pass
- Remove ci.yml (lint, security, pytest were only for EPUB scripts)
- Move EPUB build to pre-commit local hook (runs on .md changes)
- Add check_cross_references.py, check_mermaid.py, check_links.py scripts
- Add markdown-lint, cross-references, mermaid-syntax, link-check as
pre-commit hooks — mirrors all 4 CI doc-check jobs locally
- Remove spell check job from docs-check.yml (breaks on translations)
- Refactor docs-check.yml to reuse scripts/ instead of inline Python
- Add .markdownlint.json config shared by pre-commit and CI
- Update CONTRIBUTING.md with required dependencies and hook table
* fix(ci): resolve all CI check failures in docs-check workflow
- fix(check_cross_references): skip code blocks and inline code spans
to avoid false positives from documentation examples; fix emoji
heading anchor generation (rstrip not strip); add blog-posts,
openspec, prompts, .agents to IGNORE_DIRS; ignore README.backup.md
- fix(check_links): strip trailing Markdown punctuation from captured
URLs; add wikipedia, api.github.com to SKIP_DOMAINS; add placeholder
URL patterns to SKIP_URL_PATTERNS; add .agents/.claude to IGNORE_DIRS
- fix(check_mermaid): add --no-sandbox puppeteer config support via
MERMAID_PUPPETEER_NO_SANDBOX env var for GitHub Actions Linux runners
- fix(docs-check.yml): pass MERMAID_PUPPETEER_NO_SANDBOX=true to mermaid job
- fix(content): repair broken anchors in README.md, 09-advanced-features;
fix #plugins -> #claude-code-plugins in claude_concepts_guide.md;
remove non-existent ./docs/performance.md placeholder links; fix
dependabot alerts URL in SECURITY_REPORTING.md; update auto-mode URL
in resources.md; use placeholder pattern for 07-plugins example URL
- remove README.backup.md (stale file)
* fix(check-scripts): fix strip_code_blocks regex and URL fragment handling
- fix regex in strip_code_blocks to avoid conflicting MULTILINE+DOTALL
flags that could fail to strip indented code fences; use DOTALL only
- strip URL fragments (#section) before dispatching link checks to avoid
false-positive 404s on valid URLs with anchor fragments
* fix(check-scripts): fix anchor stripping, cross-ref enforcement, and mermaid temp file cleanup
- heading_to_anchor: use .strip("-") instead of .rstrip("-") to also strip leading hyphens
produced by emoji-prefixed headings, preventing false-positive anchor errors
- check_cross_references: always exit with main()'s return code — filesystem checks
should block pre-commit unconditionally, not silently pass on errors
- check_mermaid: wrap file-processing loop in try/finally so the puppeteer config
temp file is cleaned up even if an unexpected exception (e.g. UnicodeDecodeError) occurs
- docs-check.yml: remove now-unused CROSS_REF_STRICT env var
* fix(scripts): fix anchor stripping and mermaid output path
- Replace .strip('-') with .rstrip('-') in heading_to_anchor() so leading
hyphens from emoji-prefixed headings are preserved, matching GitHub's
anchor generation behaviour.
- Use Path.with_suffix('.svg') in check_mermaid.py instead of
str.replace('.mmd', '.svg') to avoid replacing all occurrences of .mmd
in the full temp path.
292 lines
12 KiB
Markdown
292 lines
12 KiB
Markdown
# 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 |
|