mirror of https://github.com/luongnv89/claude-howto.git synced 2026-06-01 10:31:33 +02:00

Files

T

Luong NGUYEN 6d1e0ae4af 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.

2026-04-02 02:20:45 +02:00

6.1 KiB

Raw Permalink Blame History

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

6.1 KiB Raw Permalink Blame History Unescape Escape

Roadmap: claude-howto 2026–2027

Vision

The 7 Pillars

Timeline at a Glance

Milestones

M1 — Infrastructure Live · End of April 2026

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

M3 — All 10 Modules Complete · End of August 2026

M4 — Agent Layer Live · End of September 2026

M5 — Version Audit Complete · End of November 2026

M6 — Self-Sustaining System · End of March 2027

Deliverables Summary

What Is NOT in Scope

6.1 KiB

Raw Permalink Blame History