Skip to content

STATUS.md

Latest commit

 

History

History
438 lines (302 loc) · 18.3 KB

STATUS.md

File metadata and controls

438 lines (302 loc) · 18.3 KB

Claude Code Implementation Guide - Project Status

Created: 2025-12-14 Updated: 2026-04-21 Status: v5.0.0 released — 6 topical Parts, manifest-driven install, CC 2.1.111+ compatible Progress: v5.0 content work complete; template/ realignment tracked as next workstream

2026-04-21 — v5.0.0 Release

What landed

  • Structural restructure: 68 flat numbered chapters collapsed into 6 topical Parts (~42 chapters) with per-Part index pages:
    • Part I — Foundation (5 chapters)
    • Part II — Workflow (6 chapters)
    • Part III — Extension (9 chapters)
    • Part IV — Context Engineering (7 chapters)
    • Part V — Advanced (7 chapters)
    • Part VI — Reference (6 chapters)
  • Manifest-driven installer: install.sh rewritten to read best-practices/manifest.json. Three tiers:
    • Core: 8 rules, 3 skills, 1 hook
    • Recommended: 30 rules, 16 skills, 7 hooks
    • Full: 64 rules, 44 skills, 12 hooks + 4 governance scripts
  • New flags: --recommended, --full, --dry-run, --uninstall (manifest-aware)
  • Removed flags: --commands, --all-rules, --with-hooks (v4.x legacy)
  • CC version floor: 2.1.99 → 2.1.111+ across hero, FAQ, and touched chapters
  • Redirects: jekyll-redirect-from plugin enabled; docs/guide/_redirect-plan.md maps 51 old→new URLs
  • Public roadmap: ROADMAP-v5.md shipped with B2-B7 phase tracker

Content work

  • 42 absorbed chapters deleted with redirect coverage (02, 04, 06, 12, 13, 14, 15, 18, 19, 19b, 22, 23, 25, 26, 27, 28, 29, 32, 34, 35, 36, 37, 38, 39, 40, 42, 43, 44, 45, 50, 51, 53, 58, 61, 62, 63, 65, 74, 75, 76, 77, 78)
  • 9 ship-logs (54, 57, 60, 64, 66, 70, 71, 72, 73) consolidated into part6/01-cc-version-history.md
  • Out-of-scope chapters pruned: 05, 17, 20, 21, 24, 30, 30b, 31, 31b, 33, 41, 46, 47, 48, 49, 52, 55, 56, 59, 67, 68, 69

Docs refreshed

  • README.md — tier install table, Part structure, honest counts, CC 2.1.111+, Opus 4.7 model
  • CHANGELOG.md — 5.0.0 entry with Added / Changed / Removed / Fixed sections
  • llms.txt — regenerated with per-Part and per-chapter index
  • CITATION.cff — version 5.0.0, date 2026-04-20, abstract with tier counts
  • STATUS.md — this entry
  • ROADMAP-v5.md — B2-B7 marked shipped; template/ gap recorded as next workstream

Known gaps (tracked)

  • template/ directory at repo root has not yet been repopulated to match manifest contents. Installer is mechanically correct but most Recommended/Full fetches will 404 until template/ is refilled. Separate sub-plan.
  • A few pruned chapter files may still physically exist under docs/guide/ numbered names. They are excluded from navigation; residual cleanup can happen opportunistically.

Recent Updates (Feb 24, 2026)

v3.3.0: 1M Context Window, Model Updates, Comprehensive Refresh

  • README.md: Added 1M token context window and Opus 4.6/Sonnet 4.6/Haiku 4.5 model names to metrics table and hero section
  • docs/index.md: Updated intro, Key Metrics table, TechArticle schema keywords, FAQ schema installation answer, and frontmatter description with 1M context and model names. Chapters count updated to 51
  • _config.yml: Added SEO keywords: claude opus 4.6, claude sonnet 4.6, 1m context window, agent teams, task management. Updated description
  • llms.txt: Complete rewrite with models section, 1M context window, 25 hook events, agent teams, task management, 240+ skills, 59 chapters
  • sitemap.xml: All lastmod dates updated to 2026-02-24
  • CHANGELOG.md: Added v3.3.0 entry and version history summary rows for v3.1.0-v3.3.0
  • Chapters updated in prior session: Ch 4 (task management), Ch 13 (25 hooks, new events, hook types), Ch 36 (worktree, CLI agents), Ch 37 (worktree note), Ch 38 (1M context, pricing), Ch 45 (plansDirectory), Ch 46 (permission precedence)

File Size / Modularity Enforcement Hooks (Chapter 13)

  • Chapter 13: Added production example showing PreToolUse + PostToolUse paired pattern for enforcing max file size rules
  • Pattern: PreToolUse reads tool_input.content before Write to catch new god files; PostToolUse checks actual file on disk after Write|Edit with growth detection via /tmp cache
  • Key design: Non-blocking (exit 0 always), growth-based noise reduction (only warns on >500L files if they grew 20+ lines), source-files-only filtering
  • Examples: Added file-size-precheck.sh and file-size-warning.sh to examples/production-claude-hooks/hooks/

Generalizable pattern: Any code quality rule (line length, complexity, naming conventions) can use this PreToolUse + PostToolUse sandwich to catch violations before and after writes.

Previous Updates (Feb 12, 2026)

Context Optimization: INDEX.txt + Rules Trimming Guide

  • Chapter 26: Added "Optimization Tips" section with 4 production-tested techniques
  • INDEX.txt pattern: README.md in .claude/rules/ wastes ~700 tokens — rename to .txt to prevent auto-loading
  • Evidence trimming: Move dated evidence/lessons from rules to memory-bank/learned/ (saved ~5k tokens in production)
  • Token measurement script: Added bash snippet to count total auto-loaded rule tokens
  • Template updated: template/.claude/rules/README.md renamed to INDEX.txt

Production results (LIMOR AI project):

  • Before: ~51k tokens auto-loaded per session
  • After: ~39k tokens (24% reduction)
  • Techniques: INDEX.txt rename, evidence trimming, cross-reference dedup, CLAUDE.md condensation

Previous Updates (Feb 5, 2026)

Critical Fix: Hook stdin Timeout (Prevents Infinite Hangs)

  • Chapter 13: Added "Hook Safety: stdin Timeout" section
  • 3 template hooks fixed: $(cat) → $(timeout 2 cat) in stop-hook.sh, pre-compact.sh, pre-prompt.sh
  • Root Cause: $(cat) blocks forever if Claude Code doesn't close stdin pipe (intermittent, more common under high context load)
  • Impact: Hooks that read stdin no longer hang — exit after 2s max

The Critical Fix:

  • ❌ JSON_INPUT=$(cat) → Can hang forever if stdin pipe not closed
  • ✅ JSON_INPUT=$(timeout 2 cat) → Exits after 2 seconds, hook continues safely

Evidence: Feb 2026, production — PostToolUse:Read hook hung during multi-file implementation. Reproduced with FIFO test (infinite hang → 2016ms with fix).

🆕 Previous Updates (Jan 26, 2026)

Critical Fix: Dynamic @ Import Mechanism

  • Chapter 29: Fixed critical bug - hook now WRITES to CLAUDE.md (not just displays)
  • Template session-start.sh: Added dynamic @ import generation from CONTEXT-MANIFEST.json
  • Root Cause: Code showed echo "@$file" (prints to terminal) instead of echo "@$file" >> CLAUDE.md (writes to file)
  • Impact: Files listed in CONTEXT-MANIFEST.json now actually get loaded into Claude's context

🆕 Previous Updates (Jan 2, 2026)

Entry #229: Skills Filtering Optimization

  • Pre-prompt.sh: Updated with score-at-match-time filtering
  • Chapter 20: Added complete documentation
  • Chapter 16: Updated with Entry #229 reference
  • Impact: 93% reduction (127-145 → 6-10 matched skills)
  • Success Rate: 95%+ (exceeds Scott Spence 84% baseline)

✅ What's Complete and Ready to Use

1. Repository Structure ✅

claude-code-guide/
├── README.md                     ✅ Complete with 4-format navigation
├── LICENSE.md                    ✅ MIT license with attribution
├── .gitignore                    ✅ Protects credentials
├── STATUS.md                     ✅ This file (updated Jan 2)
├── docs/
│   ├── quick-start.md            ✅ 30-minute entry point
│   └── guide/
│       ├── 02-minimal-setup.md   ✅ Detailed step-by-step
│       ├── 16-skills-activation-breakthrough.md ✅ Scott Spence + Entry #203
│       ├── 17-skill-detection-enhancement.md ✅ Synonym expansion
│       ├── 18-perplexity-cost-optimization.md ✅ Memory MCP caching
│       ├── 19-playwright-mcp-integration.md ✅ Browser automation
│       └── 20-skills-filtering-optimization.md ✅ Entry #229 (NEW!)
├── template/                     ✅ Clone-and-go starter (COMPLETE)
├── skills-library/               📁 Created (ready for extraction)
├── mcp-configs/                  ✅ 3 configurations ready
├── scripts/                      ✅ 3 validation scripts working
├── examples/                     📁 Created (ready for examples)
└── web/                          📁 Created (checklist pending)

2. Template Repository ✅ ENHANCED WITH ENTRY #229

Location: template/

Complete with:

  • .claude/CLAUDE.md - Project context template
  • .claude/hooks/pre-prompt.sh - ⭐ UPDATED with Entry #229 (175 lines, 93% reduction)
  • .claude/hooks/session-start.sh - Anthropic session protocol
  • .claude/mcp_servers.json.template - MCP configuration
  • .claude/skills/ - 3 starter skills + template
  • memory-bank/always/ - 3 core files (CORE-PATTERNS, system-status, CONTEXT-ROUTER)
  • .gitkeep files for empty directories

Status: ✅ Ready to clone and use immediately (with Entry #229 improvements!)

3. Starter Skills ✅ 3/3 Complete

Location: template/.claude/skills/starter/

CORRECT Structure (FIXED Dec 14):

  1. ✅ troubleshooting-decision-tree-skill/SKILL.md - Error routing (84% success)
  2. ✅ session-start-protocol-skill/SKILL.md - Anthropic best practice
  3. ✅ project-patterns-skill/SKILL.md - Pattern reference

Plus: ✅ skill-template/SKILL.md - Create your own skills

Critical Fix: Changed from standalone .md files to directory/SKILL.md structure (Claude Code requirement)

Status: ✅ All skills follow proven 84% activation pattern (95%+ with Entry #229!)

4. Validation Scripts ✅ 3/3 Complete

Location: scripts/

  1. ✅ validate-setup.sh - Master validator (checks structure, MCP, skills, memory)
  2. ✅ check-mcp.sh - MCP connection tester (validates configs)
  3. ✅ setup-wizard.sh - Interactive setup (guides through configuration)

Status: ✅ All scripts are executable and tested

5. Documentation ✅ 49 Guide Chapters Complete

Core docs + 49 numbered chapters in docs/guide/:

  1. ✅ README.md - Complete overview with 4-format navigation
  2. ✅ docs/quick-start.md - 30-minute entry point
  3. ✅ docs/guide/02-minimal-setup.md through docs/guide/49-*.md - 59 chapters covering setup, hooks, skills, MCP, context, deployment, agents, planning, resilience, and more
  4. ✅ docs/guide/13-claude-code-hooks.md - Updated Feb 2026 with stdin timeout safety section
  5. ✅ docs/guide/45-plan-mode-checklist.md - Updated Feb 2026 with 11 mandatory sections + modularity gate + sideways detection
  6. ✅ docs/guide/26-claude-code-rules-system.md - Updated Feb 2026 with rule deduplication best practice
  7. ✅ docs/guide/49-workflow-resilience-patterns.md - NEW Feb 2026 autonomous fixing, correction capture, task tracking, sideways detection

Status: ✅ Comprehensive guide with 59 chapters

6. MCP Configurations ✅ 3/4 Complete

Location: mcp-configs/

  1. ✅ minimal/ - GitHub only (3 min setup)
  2. ✅ essential/ - + Memory Bank (5 min setup)
  3. ✅ productive/ - + PostgreSQL + Perplexity (10 min setup)
  4. ⏸️ advanced/ - + Playwright (Chapter 19 - Custom servers pending)

Each includes: mcp_servers.json + detailed README

Status: ✅ Ready for immediate use

🚧 What's Pending (Optional Enhancements)

High Priority

  • Interactive web checklist (web/index.html)
  • Audit remaining hooks in other projects for $(cat) without timeout

Medium Priority

  • Extract troubleshooting/workflow skills to skills-library/
  • Advanced MCP config examples (mcp-configs/advanced/)
  • Create guide-specific skills (claude-code-setup-guide-skill, mcp-tool-evaluation-skill)

Low Priority

  • Test with fresh user (validate 30-min setup path)
  • Video walkthrough
  • Migration guide for existing projects
  • CONTRIBUTING.md

✅ Current Capabilities

What Works Right Now

A developer can:

  1. Clone template to new project (< 5 min)
  2. Customize core patterns (10 min)
  3. Configure GitHub MCP (3 min)
  4. Install 3 starter skills (2 min)
  5. Validate setup (2 min)
  6. Start using Claude Code productively (immediate)

Total: 22-30 minutes to working Claude Code

Validation: Run ./scripts/validate-setup.sh on template directory

What the Guide Provides

✅ Immediate Value (Phase 0 - 30 min):

  • Pattern-aware Claude (CORE-PATTERNS.md)
  • Session continuity (system-status.json)
  • GitHub integration (MCP)
  • Troubleshooting support (3 skills)
  • Validation tools (3 scripts)
  • Entry #229 filtering (6-10 matched skills, 95%+ activation)

✅ Growth Path (Phases 1-3):

  • Clear documentation for expansion
  • MCP configs for essential, productive, advanced
  • Skill creation framework
  • Template for consistency

🎯 Success Criteria Met

Minimal Viable Guide

  • 30-minute setup path documented
  • Template repository complete and functional
  • 3 starter skills with 84% → 95%+ activation pattern (Entry #229)
  • Validation scripts working
  • MCP configs for 3 phases
  • Quick start documentation
  • NEW: Skills filtering optimization (Chapter 20)

Quality Standards

  • All scripts executable and tested
  • All JSON files validated
  • All templates have clear placeholders
  • Skills follow YAML frontmatter standard
  • Documentation is clear and actionable
  • Entry #229: pre-prompt.sh optimized (175 lines, score-at-match-time)

User Experience

  • Can clone and use immediately
  • Validation catches common errors
  • Setup wizard provides guidance
  • Multiple entry points (README, quick-start, detailed guide)
  • Skills matched ≤10 per query (Scott Spence standard met)

Ready for Use

This guide is ready for:

  1. ✅ Personal use (you can use it for new projects today)
  2. ✅ Team sharing (templates are team-ready)
  3. ✅ Testing (validation scripts ensure it works)
  4. ⏸️ Public sharing (after completing optional enhancements)

Estimated value: 30-60 hours saved per new project setup

Recent Improvements

Feb 23, 2026 - Workflow Resilience Patterns (Chapter 49)

  • Chapter 49: Four production-tested patterns for session resilience
  • Pattern 1: Autonomous Fixing -- fix/ask decision framework (fix your own mess, ask before architectural changes)
  • Pattern 2: Correction Capture -- persist user corrections to Basic Memory MCP or .claude/rules/
  • Pattern 3: Task Tracking Conventions -- when and how to use TaskCreate/TaskUpdate with 6 hygiene rules
  • Pattern 4: Sideways Detection -- 3-strike rule, scope creep, wrong assumptions trigger re-planning
  • Each pattern includes an adoptable rule template for .claude/rules/
  • Evidence: 400+ production entries from LIMOR AI project

Feb 18, 2026 - Plan Mode Modularity Gate + Rule Deduplication

  • Chapter 45: Plan checklist expanded from 10 to 11 sections. New Section 10 (Modularity Enforcement) is a blocking gate with 4 sub-checks: File Size Gate, Layer Separation Gate, Extraction Gate, God File Prevention
  • Chapter 26: Added "Global vs Project Rule Deduplication" section. Prevents double-loading identical rules from ~/.claude/rules/ and .claude/rules/
  • Evidence: Production project saved ~1,139 lines of redundant context by removing 15 duplicate rule files
  • Files Updated: Chapter 26, Chapter 45, Chapter 47, CHANGELOG.md, template plan-checklist.md

Feb 5, 2026 - Hook stdin Timeout Fix

  • Problem: $(cat) in hooks hangs forever when Claude Code doesn't close stdin pipe
  • Fix: $(timeout 2 cat) — exits after 2s max
  • Result: Zero hangs in production (was intermittent, especially under high context load)
  • Evidence: PostToolUse:Read hook reproduced and fixed
  • Files Updated: stop-hook.sh, pre-compact.sh, pre-prompt.sh, Chapter 13

Jan 2, 2026 - Entry #229 Skills Filtering

  • Problem: When skills grew to 150-200, matched 127-145 per query
  • Fix: Score-at-match-time with relevance threshold
  • Result: 6-10 matched skills (93% reduction)
  • Evidence: 95%+ activation rate (exceeds Scott Spence 84%)
  • Files Updated: pre-prompt.sh, Chapter 16, Chapter 20 (NEW)

Dec 31, 2025 - Playwright MCP Integration

  • Added: Chapter 19 with browser automation guide
  • Added: WSL-specific setup instructions
  • Evidence: Production-tested on example.com

Dec 23, 2025 - Skills Activation Breakthrough

  • Added: Chapter 16 (Scott Spence pattern)
  • Added: Chapter 17 (synonym expansion)
  • Evidence: 500/500 test score (100% activation)

Next Actions (Your Choice)

Option A: Use It Now

  • Test with a fresh project
  • Get feedback
  • Iterate based on real usage

Option B: Complete Remaining Docs (8-12 hours)

  • Write remaining guide chapters
  • Build interactive checklist
  • Extract more skills from production

Option C: Hybrid Approach (Recommended)

  • Use minimal setup for next project (validate it works)
  • Add enhancements based on what you need
  • Grow guide organically

Files Ready to Deploy

Immediately usable:

  • template/ - Complete, tested, validated (Entry #229 enhanced)
  • scripts/ - All 3 scripts working
  • mcp-configs/minimal/ - GitHub integration
  • mcp-configs/essential/ - + Memory Bank
  • mcp-configs/productive/ - + PostgreSQL
  • docs/quick-start.md - Entry point
  • docs/guide/ - 59 chapters complete (02 through 49)

Total deliverable: ~45 files, ~9,100 lines, production-ready

Summary

✅ MVP COMPLETE + ENTRY #229: This guide can be used today for new Claude Code projects with optimized skills filtering

Time invested: ~5 hours implementation Time to use: 30 minutes per new project ROI: Pays for itself after 6 new projects

Quality: Based on 240+ proven patterns, 95%+ activation rate, Anthropic best practices, Scott Spence research

Ready: Clone template, customize placeholders, start coding with skills that actually activate

Last Updated: 2026-02-24 (v3.3.0 - 1M context window, Opus 4.6/Sonnet 4.6/Haiku 4.5, 25 hook events, agent teams, task management, SEO/AEO refresh) Next: Test with a real project or continue building optional enhancements