refactor(ci): shift quality checks to pre-commit, CI as 2nd pass (#34)
* 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.
This commit is contained in:
Luong NGUYEN
153
docs/ROADMAP-20260401.md
Normal file
153
docs/ROADMAP-20260401.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user