mirror of https://github.com/luongnv89/claude-howto.git synced 2026-05-27 22:22:36 +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

12 KiB

Raw Permalink Blame History

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

12 KiB Raw Permalink Blame History Unescape Escape