@qazuor/claude-code-config 0.1.0

package/templates/docs/diagrams/tools-relationship.mmd

@@ -0,0 +1,55 @@
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#3B82F6','primaryTextColor':'#fff','primaryBorderColor':'#2563EB','lineColor':'#6B7280','secondaryColor':'#10B981','tertiaryColor':'#F59E0B'}}}%%
+flowchart LR
+    %% Commands Layer
+    subgraph Commands ["/commands (16)"]
+        direction TB
+        QualityCmd["/quality-check<br/>/code-check"]
+        PlanningCmd["/start-feature-plan<br/>/start-refactor-plan"]
+        AuditCmd["/security-audit<br/>/performance-audit<br/>/accessibility-audit"]
+        MetaCmd["/create-agent<br/>/create-command<br/>/create-skill<br/>/help"]
+        DevCmd["/add-new-entity<br/>/update-docs<br/>/commit"]
+    end
+    
+    %% Agents Layer
+    subgraph Agents ["Agents (14)"]
+        direction TB
+        LeadAgents[tech-lead<br/>product-functional<br/>product-technical]
+        BackendAgents[hono-engineer<br/>db-engineer<br/>node-typescript-engineer]
+        FrontendAgents[astro-engineer<br/>tanstack-start-engineer<br/>react-senior-dev]
+        DesignAgents[ux-ui-designer<br/>content-writer]
+        QualityAgents[qa-engineer<br/>debugger]
+        SupportAgents[tech-writer<br/>i18n-specialist<br/>seo-ai-specialist<br/>enrichment-agent]
+    end
+    
+    %% Skills Layer
+    subgraph Skills ["Skills (16)"]
+        direction TB
+        TestingSkills[Testing & Quality 6:<br/>web-app-testing<br/>api-app-testing<br/>performance-testing<br/>security-testing<br/>tdd-methodology<br/>qa-criteria-validator]
+        DevSkills[Development Tools 5:<br/>git-commit-helper<br/>vercel-specialist<br/>shadcn-specialist<br/>mermaid-diagram-specialist<br/>add-memory]
+        DesignSkills[Design & Patterns 3:<br/>brand-guidelines<br/>error-handling-patterns<br/>markdown-formatter]
+        UtilSkills[Documentation & Utils 2:<br/>pdf-creator-editor<br/>json-data-auditor]
+    end
+    
+    %% Relationships
+    Commands -->|invoke| Agents
+    Agents -->|use| Skills
+    
+    QualityCmd -.->|uses| QualityAgents
+    PlanningCmd -.->|uses| LeadAgents
+    AuditCmd -.->|tech-lead coordinates| TestingSkills
+    DevCmd -.->|uses| BackendAgents
+    DevCmd -.->|uses| FrontendAgents
+    
+    LeadAgents -.->|invokes| DevSkills
+    BackendAgents -.->|invokes| TestingSkills
+    FrontendAgents -.->|invokes| DesignSkills
+    QualityAgents -.->|invokes| TestingSkills
+    SupportAgents -.->|invokes| UtilSkills
+    
+    classDef commandClass fill:#8B5CF6,stroke:#7C3AED,color:#fff
+    classDef agentClass fill:#3B82F6,stroke:#2563EB,color:#fff
+    classDef skillClass fill:#10B981,stroke:#059669,color:#fff
+    
+    class Commands,QualityCmd,PlanningCmd,AuditCmd,MetaCmd,DevCmd commandClass
+    class Agents,LeadAgents,BackendAgents,FrontendAgents,QualityAgents,SupportAgents agentClass
+    class Skills,TestingSkills,DevSkills,DesignSkills,UtilSkills skillClass

package/templates/docs/diagrams/workflow-decision-tree.mmd

@@ -0,0 +1,38 @@
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#3B82F6','primaryTextColor':'#fff','primaryBorderColor':'#2563EB','lineColor':'#6B7280','secondaryColor':'#10B981','tertiaryColor':'#F59E0B'}}}%%
+flowchart TD
+    Start([New Task/Issue]) --> Assess{Assess<br/>Task}
+    
+    %% Quick Fix Path
+    Assess --> QuickCheck{< 30 min<br/>1-2 files<br/>Very low risk?}
+    QuickCheck -->|Yes| QuickFix[Level 1: Quick Fix]
+    QuickFix --> QuickSteps[6 Steps:<br/>1. Verify<br/>2. Change<br/>3. Validate<br/>4. Commit<br/>5. Push<br/>6. Done]
+    QuickSteps --> QuickEnd([Complete!])
+    
+    %% Atomic Task Path
+    QuickCheck -->|No| AtomicCheck{30min-3h<br/>2-10 files<br/>Low-med risk?}
+    AtomicCheck -->|Yes| Atomic[Level 2: Atomic Task]
+    Atomic --> AtomicSteps[11 Steps:<br/>1. Create PB-XXX<br/>2. Tech Analysis<br/>3. Review<br/>4. Tests RED<br/>5. Implement GREEN<br/>6. Refactor<br/>7. Docs<br/>8. Coverage<br/>9. Quality<br/>10. Commit<br/>11. Registry]
+    AtomicSteps --> AtomicEnd([Complete!])
+    
+    %% Feature Planning Path
+    AtomicCheck -->|No| FeatureCheck{Multi-day<br/>Architecture<br/>DB changes?}
+    FeatureCheck -->|Yes| Feature[Level 3: Feature Planning]
+    Feature --> FeatureSteps[4 Phases:<br/>Phase 1: Planning<br/>Phase 2: Implementation<br/>Phase 3: Validation<br/>Phase 4: Finalization]
+    FeatureSteps --> FeatureEnd([Complete!])
+    
+    %% Error handling
+    FeatureCheck -->|Unclear| Clarify{Need more<br/>information?}
+    Clarify -->|Yes| Gather[Gather Requirements]
+    Gather --> Assess
+    Clarify -->|No| DefaultPath[Use Level 2<br/>when uncertain]
+    DefaultPath --> Atomic
+    
+    classDef quickClass fill:#10B981,stroke:#059669,color:#fff
+    classDef atomicClass fill:#F59E0B,stroke:#D97706,color:#fff
+    classDef featureClass fill:#3B82F6,stroke:#2563EB,color:#fff
+    classDef decisionClass fill:#8B5CF6,stroke:#7C3AED,color:#fff
+    
+    class QuickFix,QuickSteps,QuickEnd quickClass
+    class Atomic,AtomicSteps,AtomicEnd atomicClass
+    class Feature,FeatureSteps,FeatureEnd featureClass
+    class QuickCheck,AtomicCheck,FeatureCheck,Clarify decisionClass

package/templates/docs/doc-sync.md

@@ -0,0 +1,533 @@
+# Documentation Sync Process
+
+## Overview
+
+This guide explains how to keep documentation synchronized across the system, validate consistency, and maintain quality standards. It covers the validation process, sync scripts, and a comprehensive checklist for documentation updates.
+
+**Purpose**: Ensure all documentation is accurate, up-to-date, and properly cross-referenced.
+
+---
+
+## Table of Contents
+
+<!-- markdownlint-disable MD051 -->
+
+1. [Documentation Structure](#documentation-structure)
+2. [Validation Process](#validation-process)
+3. [Sync Scripts](#sync-scripts)
+4. [Update Checklist](#update-checklist)
+5. [Common Sync Issues](#common-sync-issues)
+6. [Automation](#automation)
+
+<!-- markdownlint-enable MD051 -->
+
+---
+
+## Documentation Structure
+
+### Documentation Hierarchy
+
+```text
+.claude/
+├── agents/           # 14 agent definitions
+│   ├── engineering/
+│   ├── specialized/
+│   ├── management/
+│   └── README.md
+├── commands/         # 16 command definitions
+│   ├── audit/
+│   ├── formatting/
+│   ├── git/
+│   ├── meta/
+│   └── README.md
+├── skills/           # 16 skill definitions
+│   ├── brand/
+│   ├── git/
+│   ├── patterns/
+│   ├── tech/
+│   ├── testing/
+│   ├── utils/
+│   └── README.md
+├── docs/             # Core documentation
+│   ├── INDEX.md     # Master index
+│   ├── quick-start.md
+│   ├── glossary.md
+│   ├── RECOMMENDED-HOOKS.md
+│   ├── CHECKPOINT-SYSTEM.md
+│   ├── system-maintenance.md
+│   ├── doc-sync.md  # This file
+│   ├── learnings/   # 8 learning documents
+│   ├── workflows/   # 9 workflow documents
+│   ├── diagrams/    # 4 mermaid diagrams
+│   └── standards/   # Standards & guidelines
+├── schemas/         # JSON schemas (9 files)
+└── sessions/        # Planning sessions
+    └── planning/
+```text
+
+### Master Documents
+
+Files that must stay synchronized:
+
+| File | Sync With | Update Frequency |
+|------|-----------|------------------|
+| `CLAUDE.md` | All sections | On major changes |
+| `.claude/docs/INDEX.md` | All documentation | When new docs added |
+| `README.md` | Project changes | As needed |
+| `.claude/agents/README.md` | Agent files | When agents change |
+| `.claude/commands/README.md` | Command files | When commands change |
+| `.claude/skills/README.md` | Skill files | When skills change |
+| `.claude/docs/learnings/README.md` | Learning files | When learnings added |
+| `.claude/docs/workflows/README.md` | Workflow files | When workflows change |
+
+---
+
+## Validation Process
+
+### 1. File Count Validation
+
+Verify all file counts match expected values:
+
+```bash
+# Run health check
+pnpm health-check
+```text
+
+**Expected counts:**
+
+- Agents: 14
+- Commands: 16
+- Skills: 16
+- Learnings: 8
+- Workflows: 9
+- Diagrams: 4
+
+**If counts don't match:**
+
+```bash
+# Find actual counts
+echo "Agents: $(find .claude/agents -name "*.md" ! -name "README.md" | wc -l)"
+echo "Commands: $(find .claude/commands -name "*.md" ! -name "README.md" | wc -l)"
+echo "Skills: $(find .claude/skills -name "*.md" ! -name "README.md" | wc -l)"
+echo "Learnings: $(find .claude/docs/learnings -name "*.md" ! -name "README.md" | wc -l)"
+echo "Workflows: $(find .claude/docs/workflows -name "*.md" ! -name "README.md" | wc -l)"
+echo "Diagrams: $(find .claude/docs/diagrams -name "*.mmd" | wc -l)"
+
+# Update health-check.sh with correct counts
+vim .claude/scripts/health-check.sh
+```text
+
+### 2. Link Validation
+
+Check for broken links across all documentation:
+
+```bash
+# Method 1: Via health check
+pnpm health-check
+
+# Method 2: Manual grep
+for file in $(find .claude -name "*.md" -type f); do
+  echo "Checking: $file"
+  grep -oP '\]\(\K[^)]+' "$file" 2>/dev/null | while read -r link; do
+    # Skip URLs and anchors
+    if ! echo "$link" | grep -qE '^(https?:|#)'; then
+      # Convert relative path to absolute
+      link_dir=$(dirname "$file")
+      link_path="$link_dir/$link"
+      if [ ! -f "$link_path" ] && [ ! -d "$link_path" ]; then
+        echo "  ⚠️  Broken: $link"
+      fi
+    fi
+  done
+done
+```text
+
+### 3. Cross-Reference Validation
+
+Verify all cross-references are correct:
+
+```bash
+# Check CLAUDE.md references
+grep -n "\[.*\](.claude/" CLAUDE.md
+
+# Check INDEX.md references
+grep -n "\[.*\](./" .claude/docs/INDEX.md
+
+# Check workflow references
+grep -rn "\[.*\](./" .claude/docs/workflows/
+```text
+
+### 4. Schema Validation
+
+Validate JSON files against schemas:
+
+```bash
+# Validate code registry
+jq empty .claude/sessions/planning/.code-registry.json
+
+# Validate checkpoints
+find .claude/sessions/planning -name ".checkpoint.json" -exec jq empty {} \;
+
+# Run schema validation script (if exists)
+pnpm claude:validate:schemas
+```text
+
+---
+
+## Sync Scripts
+
+### Available Scripts
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| **Health Check** | `pnpm health-check` | Validate entire system |
+| **Format Markdown** | `pnpm format:md:claude` | Auto-format .claude/ docs |
+| **Lint Markdown** | `pnpm lint:md` | Check markdown quality |
+| **Validate Docs** | `pnpm claude:validate:docs` | Run doc validation |
+| **Validate Schemas** | `pnpm claude:validate:schemas` | Validate JSON schemas |
+| **Planning Sync** | `pnpm planning:sync <path>` | Sync planning to GitHub |
+
+### Manual Sync Process
+
+When adding/modifying documentation:
+
+```bash
+# 1. Make changes
+vim .claude/docs/new-doc.md
+
+# 2. Format markdown
+pnpm format:md:claude
+
+# 3. Validate changes
+pnpm health-check
+
+# 4. Update INDEX.md
+vim .claude/docs/INDEX.md
+# Add: - [New Doc](./new-doc.md) - Description
+
+# 5. Update relevant README
+# If it's a learning:
+vim .claude/docs/learnings/README.md
+
+# 6. Commit with proper message
+git add .
+git commit -m "docs: add new-doc documentation"
+
+# 7. Push and verify CI
+git push origin main
+# Check: https://github.com/qazuor/your-repo/actions
+```text
+
+---
+
+## Update Checklist
+
+### When Adding a New Agent
+
+- [ ] Create agent file in `.claude/agents/{category}/`
+- [ ] Update `.claude/agents/README.md`
+  - [ ] Add to category list
+  - [ ] Update count (14 → 15)
+- [ ] Update `CLAUDE.md`
+  - [ ] Add to Subagents section
+  - [ ] Update Quick Reference count
+- [ ] Update `.claude/docs/INDEX.md`
+  - [ ] Add to Agents section
+- [ ] Run `pnpm health-check` (verify count)
+- [ ] Commit: `feat(agents): add {name} agent`
+- [ ] Push and verify CI
+
+### When Adding a New Command
+
+- [ ] Create command file in `.claude/commands/{category}/`
+- [ ] Update `.claude/commands/README.md`
+  - [ ] Add to category list
+  - [ ] Update count (16 → 17)
+- [ ] Update `CLAUDE.md`
+  - [ ] Add to Commands section
+  - [ ] Update Quick Reference count
+- [ ] Update `.claude/docs/INDEX.md`
+  - [ ] Add to Commands section
+- [ ] Test command in Claude Code
+- [ ] Run `pnpm health-check`
+- [ ] Commit: `feat(commands): add /{name} command`
+- [ ] Push and verify CI
+
+### When Adding a New Skill
+
+- [ ] Create skill file in `.claude/skills/{category}/`
+- [ ] Update `.claude/skills/README.md`
+  - [ ] Add to category list
+  - [ ] Update count (16 → 17)
+- [ ] Update `CLAUDE.md`
+  - [ ] Add to Skills section (if major)
+  - [ ] Update Quick Reference count
+- [ ] Update `.claude/docs/INDEX.md`
+  - [ ] Add to Skills section
+- [ ] Run `pnpm health-check`
+- [ ] Commit: `feat(skills): add {name} skill`
+- [ ] Push and verify CI
+
+### When Adding a New Learning
+
+- [ ] Create learning file in `.claude/docs/learnings/`
+  - [ ] Use proper template (Date, Category, Problem, Solution, Impact, Related)
+- [ ] Update `.claude/docs/learnings/README.md`
+  - [ ] Add to appropriate category
+  - [ ] Update category count
+- [ ] Update `CLAUDE.md`
+  - [ ] Add to "Archived Learnings" section
+- [ ] Update `.claude/docs/INDEX.md`
+  - [ ] Verify Learnings section is correct
+- [ ] Run `pnpm health-check`
+- [ ] Commit: `docs(learnings): add {name} learning`
+- [ ] Push and verify CI
+
+### When Adding a New Workflow
+
+- [ ] Create workflow file in `.claude/docs/workflows/`
+- [ ] Update `.claude/docs/workflows/README.md`
+  - [ ] Add to workflow list
+  - [ ] Update count (9 → 10)
+- [ ] Update `.claude/docs/INDEX.md`
+  - [ ] Add to Workflows section
+- [ ] Create/update related diagram (if needed)
+- [ ] Update `CLAUDE.md` workflow references
+- [ ] Run `pnpm health-check`
+- [ ] Commit: `docs(workflows): add {name} workflow`
+- [ ] Push and verify CI
+
+### When Updating Core Documents
+
+**CLAUDE.md:**
+
+- [ ] Update relevant sections
+- [ ] Verify all links work
+- [ ] Keep within recommended size (≤ 600 lines)
+- [ ] Update "Last updated" date
+- [ ] Run `pnpm format:md`
+- [ ] Commit: `docs: update CLAUDE.md - {what changed}`
+
+**INDEX.md:**
+
+- [ ] Add new sections as needed
+- [ ] Verify all links point to correct locations
+- [ ] Keep structure organized
+- [ ] Update counts if changed
+- [ ] Run `pnpm health-check`
+- [ ] Commit: `docs: update documentation index`
+
+---
+
+## Common Sync Issues
+
+### Issue 1: File Count Mismatch
+
+**Symptom**: Health check shows incorrect counts
+
+**Causes:**
+
+- Added file but forgot to update README
+- Deleted file but count not updated
+- Duplicate files exist
+
+**Fix:**
+
+```bash
+# Find actual count
+find .claude/agents -name "*.md" ! -name "README.md" | wc -l
+
+# Update README count
+vim .claude/agents/README.md
+
+# Update health-check.sh expected count
+vim .claude/scripts/health-check.sh
+```text
+
+### Issue 2: Broken Links
+
+**Symptom**: 404s or link validation errors
+
+**Causes:**
+
+- File moved but links not updated
+- Incorrect relative path
+- File renamed
+
+**Fix:**
+
+```bash
+# Find file
+find .claude -name "target-file.md"
+
+# Update all references
+grep -rl "broken-link.md" .claude/ | xargs sed -i 's|broken-link.md|correct-link.md|g'
+
+# Validate
+pnpm health-check
+```text
+
+### Issue 3: Markdown Formatting Errors
+
+**Symptom**: Lint errors in CI
+
+**Causes:**
+
+- Missing blank lines
+- Incorrect list indentation
+- Missing language in code blocks
+
+**Fix:**
+
+```bash
+# Auto-fix
+pnpm format:md:claude
+
+# Manual check specific file
+pnpm markdownlint-cli2 file.md --fix
+```text
+
+### Issue 4: Out-of-Sync README
+
+**Symptom**: README lists wrong count or missing items
+
+**Causes:**
+
+- Forgot to update README when adding file
+- Manual edit error
+
+**Fix:**
+
+```bash
+# Regenerate list
+for file in .claude/agents/*/*.md; do
+  echo "- [$(basename $file .md)]($(realpath --relative-to=.claude/agents $file))"
+done
+
+# Update README manually
+vim .claude/agents/README.md
+```text
+
+---
+
+## Automation
+
+### Git Hooks
+
+Documentation sync is partially automated via Git hooks:
+
+**Pre-commit hook** (`.husky/pre-commit`):
+
+- Auto-formats markdown files
+- Validates .claude documentation
+- Checks for broken links (warning)
+
+**Post-checkout hook** (`.husky/post-checkout`):
+
+- Validates code registry
+- Checks for stale registry (> 7 days)
+
+### CI/CD Pipeline
+
+GitHub Actions validates documentation on push:
+
+**Workflow**: `.github/workflows/validate-docs.yml`
+
+**Checks:**
+
+1. Documentation structure
+2. JSON schemas
+3. System health
+4. Markdown linting
+5. Broken links
+6. File counts
+
+**Badge**: [![Documentation Validation](https://github.com/qazuor/your-repo/actions/workflows/validate-docs.yml/badge.svg)](https://github.com/qazuor/your-repo/actions/workflows/validate-docs.yml)
+
+### Scheduled Tasks
+
+**Future automation** (not yet implemented):
+
+- Weekly: Auto-archive learnings > 30 days
+- Monthly: Generate documentation metrics
+- Quarterly: Suggest outdated documentation for review
+
+---
+
+## Best Practices
+
+### DO ✅
+
+- **Always update README** when adding files
+- **Run health check** before committing
+- **Format markdown** before committing
+- **Validate links** after moving files
+- **Use conventional commits** for doc changes
+- **Keep counts updated** in all locations
+- **Test commands** before documenting
+- **Cross-reference** related documents
+
+### DON'T ❌
+
+- **Skip validation** before pushing
+- **Leave broken links** unresolved
+- **Forget to update INDEX.md** for new docs
+- **Commit without formatting** markdown
+- **Use absolute paths** (use relative)
+- **Duplicate information** across files (link instead)
+- **Ignore CI failures** on documentation
+- **Manually edit counts** without verifying actual number
+
+---
+
+## Quick Reference
+
+### Common Commands
+
+```bash
+# Full validation
+pnpm health-check
+
+# Format all .claude markdown
+pnpm format:md:claude
+
+# Lint markdown
+pnpm lint:md .claude/**/*.md
+
+# Validate schemas
+pnpm claude:validate:schemas
+
+# Count files
+find .claude/agents -name "*.md" ! -name "README.md" | wc -l
+
+# Find broken links
+grep -r "](./" .claude/docs/ | grep -v "http"
+
+# Check file size
+du -sh .claude/docs/*.md
+```text
+
+### File Locations
+
+```text
+Documentation sync checklist: .claude/docs/doc-sync.md (this file)
+System maintenance guide: .claude/docs/system-maintenance.md
+Health check script: .claude/scripts/health-check.sh
+Validation workflow: .github/workflows/validate-docs.yml
+Pre-commit hook: .husky/pre-commit
+```text
+
+---
+
+## Related Documentation
+
+- **System Maintenance**: `.claude/docs/system-maintenance.md`
+- **Health Check System**: `.claude/scripts/health-check.sh`
+- **Git Hooks**: `.claude/docs/RECOMMENDED-HOOKS.md`
+- **Documentation Index**: `.claude/docs/INDEX.md`
+
+---
+
+**Last updated**: 2025-10-31
+**Version**: 1.0.0
+**Maintained by**: Documentation team