diff --git a/.claude/agents/dev-agent.md b/.claude/agents/dev-agent.md index 0dc5f38..95195ac 100644 --- a/.claude/agents/dev-agent.md +++ b/.claude/agents/dev-agent.md @@ -6,19 +6,24 @@ You are the **Development Agent**, responsible for implementing features, writing code, and following project patterns and best practices. ## Required Skills + Load before ANY implementation: + - `.claude/skills/scope-guard/SKILL.md` - Scope validation ## CRITICAL: Scope Awareness ### Before ANY Implementation + 1. Load scope-guard skill 2. Check current phase from `.claude/state/execution.json` 3. Verify ALL planned files are within phase scope 4. If ANY file belongs to future phase → **STOP IMMEDIATELY** ### Scope Violation Response + If out-of-scope work is detected: + ``` ⛔ SCOPE VIOLATION DETECTED @@ -34,6 +39,7 @@ RESOLUTION: This deliverable is scheduled for Phase {{N}}. ``` ### MCP Integration + - Use **Serena** for code analysis before implementation - Use **Chrome DevTools** for live testing - Use **Context7** for framework documentation lookup diff --git a/.claude/agents/orchestrator-agent.md b/.claude/agents/orchestrator-agent.md index ee14366..5652abd 100644 --- a/.claude/agents/orchestrator-agent.md +++ b/.claude/agents/orchestrator-agent.md @@ -6,7 +6,9 @@ Central coordination agent that manages workflow execution, agent delegation, and system-wide state across the project lifecycle. ## Required Skills + Before ANY execution, load these skills: + - `.claude/skills/phase-control/SKILL.md` - Phase boundary enforcement - `.claude/skills/scope-guard/SKILL.md` - Scope violation prevention - `.claude/skills/checkpoint-manager/SKILL.md` - Checkpoint management @@ -14,6 +16,7 @@ Before ANY execution, load these skills: ## CRITICAL: Scope Control Rules ### Phase Boundaries (MANDATORY - NO EXCEPTIONS) + 1. **NEVER** execute tasks from a phase that hasn't been explicitly authorized 2. **NEVER** auto-generate Phase N+1 plans after completing Phase N 3. **NEVER** continue past a phase boundary without explicit user command @@ -22,6 +25,7 @@ Before ANY execution, load these skills: 6. **ALWAYS** load phase-control skill before task execution ### Before EVERY Task + ``` 1. Check current authorized phase from .claude/state/execution.json 2. Verify task belongs to authorized phase diff --git a/.claude/agents/planner-agent.md b/.claude/agents/planner-agent.md index 22450b0..95cea9e 100644 --- a/.claude/agents/planner-agent.md +++ b/.claude/agents/planner-agent.md @@ -169,6 +169,64 @@ Brief description of phase goals 4. **Appropriate Granularity**: Not too broad, not too detailed 5. **Realistic Sequencing**: Account for natural workflow +## Multi-Model Support + +The planner agent supports cross-validation with secondary models to get +different perspectives on architecture decisions. + +### Configuration + +See `.claude/config/models.yml`: + +```yaml +agent_overrides: + planner: + primary: 'claude-sonnet-4-20250514' + secondary: 'gemini-2.5-pro' + cross_validate: true +``` + +### Cross-Validation Process + +When cross-validation is enabled: + +1. Primary model (Claude) generates the plan +2. Secondary model (Gemini/GPT-4) reviews the plan +3. Differences are highlighted for user review +4. User makes final decisions on conflicts + +### When to Use Cross-Validation + +**Recommended for:** + +- Major architecture decisions +- Database schema design +- API structure planning +- Security-sensitive features + +**Optional for:** + +- Simple feature planning +- Bug fix planning +- Documentation tasks + +### Disabling Cross-Validation + +For a single run: + +``` +/project-planner --no-cross-validate +``` + +Permanently: + +```yaml +# .claude/config/models.yml +agent_overrides: + planner: + cross_validate: false +``` + ## Communication Reports to: Orchestrator agent Triggers: dev-agent, test-agent, docs-agent diff --git a/.claude/agents/review-agent.md b/.claude/agents/review-agent.md index 07930b6..6d57adf 100644 --- a/.claude/agents/review-agent.md +++ b/.claude/agents/review-agent.md @@ -251,3 +251,95 @@ When complete, report: ### Status: {{Complete}} ``` + +## Multi-Model Cross-Validation + +The review agent supports cross-validation where a secondary model independently +reviews the same code, catching issues that a single model might miss. + +### Configuration + +See `.claude/config/models.yml`: + +```yaml +agent_overrides: + review: + primary: 'claude-sonnet-4-20250514' + secondary: 'gpt-4o' + cross_validate: true +``` + +### Cross-Validation Process + +When enabled: + +1. **Primary Review** - Claude reviews the code +2. **Secondary Review** - GPT-4/Gemini independently reviews +3. **Comparison** - Findings are deduplicated and merged +4. **Conflict Highlighting** - Disagreements shown to user + +### Output with Cross-Validation + +```markdown +## Cross-Validated Review + +### Primary (Claude Sonnet 4) + +- Found 3 issues +- Security: ✅ Passed +- Accessibility: ⚠️ 1 issue + +### Secondary (GPT-4o) + +- Found 4 issues +- Security: ⚠️ 1 issue (XSS risk) +- Accessibility: ⚠️ 2 issues + +### Merged Findings (deduplicated) + +| # | Issue | Found By | Severity | +| --- | -------------------- | -------- | -------- | +| 1 | XSS vulnerability | GPT-4 | Critical | +| 2 | Missing ARIA label | Both | Major | +| 3 | Focus trap missing | GPT-4 | Major | +| 4 | Consider memoization | Claude | Minor | + +### Disagreements + +- Claude: Security passed +- GPT-4: Found potential XSS → Human review recommended for security concern +``` + +### When Cross-Validation Triggers + +By default: + +- **Security-sensitive code** - Always +- **High complexity** - When cyclomatic complexity > 10 +- **On request** - When `--cross-validate` flag used + +### Requesting Cross-Validation + +```bash +# Single file +/review --cross-validate src/auth.ts + +# Always for security +# Configure in models.yml: +cross_validation: + triggers: + review: + on_security: true +``` + +### Disabling Cross-Validation + +```bash +# Single run +/review --no-cross-validate src/utils.ts + +# Permanently - edit models.yml +agent_overrides: + review: + cross_validate: false +``` diff --git a/.claude/commands/phase-approve.md b/.claude/commands/phase-approve.md index b6d9647..3287f3f 100644 --- a/.claude/commands/phase-approve.md +++ b/.claude/commands/phase-approve.md @@ -1,24 +1,30 @@ # /phase-approve - Authorize Next Phase ## Purpose -Explicitly authorizes execution of the next phase. This is the ONLY way to advance beyond the current phase. + +Explicitly authorizes execution of the next phase. This is the ONLY way to +advance beyond the current phase. ## Trigger + ``` /phase-approve ``` ## Arguments + - `phase_number` (required): The phase number to authorize (e.g., 2) ## Process ### Step 1: Validate Request + 1. Check that previous phase is complete 2. Check that requested phase is next in sequence 3. Verify no unresolved scope violations ### Step 2: Confirm with User + ``` ╔══════════════════════════════════════════════════════════════╗ ║ 📋 PHASE AUTHORIZATION REQUEST ║ @@ -46,7 +52,9 @@ Type "APPROVE" to authorize Phase {{N}}, or "CANCEL" to abort. ``` ### Step 3: Update State + If approved, update `.claude/state/execution.json`: + ```json { "authorized_phases": [1, 2], @@ -56,6 +64,7 @@ If approved, update `.claude/state/execution.json`: ``` ### Step 4: Confirm Authorization + ``` ╔══════════════════════════════════════════════════════════════╗ ║ ✓ PHASE {{N}} AUTHORIZED ║ @@ -71,12 +80,14 @@ If approved, update `.claude/state/execution.json`: ## Validation Rules ### Cannot Approve If: + - Previous phase is not complete - Unresolved scope violations exist - Pending checkpoints require approval - Skipping phases (e.g., approving Phase 3 when Phase 2 not done) ### Error Messages + ``` ⛔ CANNOT AUTHORIZE PHASE {{N}} @@ -87,6 +98,7 @@ Complete Phase {{N-1}} first, then try again. ``` ## Example Usage + ```bash # After completing Phase 1 /phase-approve 2 diff --git a/.claude/commands/status.md b/.claude/commands/status.md index 6fac360..de93329 100644 --- a/.claude/commands/status.md +++ b/.claude/commands/status.md @@ -1,9 +1,11 @@ # /status - Execution Status Command ## Purpose + Displays current execution state, phase progress, and next steps. ## Trigger + Run `/status` at any time to see project state. ## Output Format @@ -50,6 +52,7 @@ Run `/status` at any time to see project state. ## Data Sources Read from: + 1. `.claude/state/execution.json` - Execution state 2. `.claude/tasks/phase-{{N}}-tasks.md` - Task progress 3. `.claude/config.yml` - Configuration @@ -57,14 +60,14 @@ Read from: ## Status Values -| Status | Meaning | -|--------|---------| -| `not_started` | Phase planning not yet run | -| `planning` | Running /project-planner or /task-planner | -| `in_progress` | Tasks being executed | -| `awaiting_approval` | At checkpoint, waiting for user | -| `complete` | Phase finished | -| `blocked` | Execution halted due to error/violation | +| Status | Meaning | +| ------------------- | ----------------------------------------- | +| `not_started` | Phase planning not yet run | +| `planning` | Running /project-planner or /task-planner | +| `in_progress` | Tasks being executed | +| `awaiting_approval` | At checkpoint, waiting for user | +| `complete` | Phase finished | +| `blocked` | Execution halted due to error/violation | ## Next Steps Logic diff --git a/.claude/commands/task-runner.md b/.claude/commands/task-runner.md index 9235ec8..9dd4f06 100644 --- a/.claude/commands/task-runner.md +++ b/.claude/commands/task-runner.md @@ -40,6 +40,7 @@ Before ANY execution, output: ### Step 0.5: Load Required Skills Before execution, load: + 1. `.claude/skills/phase-control/SKILL.md` 2. `.claude/skills/scope-guard/SKILL.md` 3. `.claude/skills/checkpoint-manager/SKILL.md` @@ -203,6 +204,7 @@ Output exactly this completion message: ``` **CRITICAL RULES:** + - **NEVER** automatically invoke task-planner for next phase - **NEVER** automatically invoke task-runner for next phase - **NEVER** generate Phase N+1 plans without explicit user command diff --git a/.claude/commands/worktree-disable.md b/.claude/commands/worktree-disable.md index 5a04b9f..e43a059 100644 --- a/.claude/commands/worktree-disable.md +++ b/.claude/commands/worktree-disable.md @@ -1,9 +1,11 @@ # /worktree-disable - Disable Git Worktree Mode ## Purpose + Returns to sequential task execution. Cleans up existing worktrees. ## Trigger + ``` /worktree-disable ``` @@ -11,7 +13,9 @@ Returns to sequential task execution. Cleans up existing worktrees. ## Process ### Step 1: Check for Active Worktrees + If worktrees exist with uncommitted work: + ``` ⚠️ ACTIVE WORKTREES DETECTED @@ -26,6 +30,7 @@ Options: ``` ### Step 2: Clean Up Worktrees + ```bash # Remove all worktrees git worktree list | grep ".worktrees" | while read wt; do @@ -37,7 +42,9 @@ git branch | grep "task/" | xargs git branch -D ``` ### Step 3: Update Config + Sets in `.claude/config.yml`: + ```yaml git: worktrees: @@ -45,6 +52,7 @@ git: ``` ### Step 4: Confirm + ``` ╔══════════════════════════════════════════════════════════════╗ ║ ✓ GIT WORKTREE MODE DISABLED ║ diff --git a/.claude/commands/worktree-enable.md b/.claude/commands/worktree-enable.md index 3d5d230..94bf553 100644 --- a/.claude/commands/worktree-enable.md +++ b/.claude/commands/worktree-enable.md @@ -1,9 +1,11 @@ # /worktree-enable - Enable Git Worktree Mode ## Purpose + Enables parallel task execution using git worktrees. Simple one-command opt-in. ## Trigger + ``` /worktree-enable ``` @@ -11,6 +13,7 @@ Enables parallel task execution using git worktrees. Simple one-command opt-in. ## What It Does ### Step 1: Check Prerequisites + ```bash # Verify git version supports worktrees git --version # Requires 2.5+ @@ -20,23 +23,27 @@ git rev-parse --git-dir ``` ### Step 2: Create Worktree Directory + ```bash mkdir -p .worktrees echo ".worktrees/" >> .gitignore ``` ### Step 3: Update Config + Adds to `.claude/config.yml`: + ```yaml git: worktrees: enabled: true - base_dir: ".worktrees" + base_dir: '.worktrees' auto_cleanup: true max_concurrent: 3 ``` ### Step 4: Confirm + ``` ╔══════════════════════════════════════════════════════════════╗ ║ ✓ GIT WORKTREE MODE ENABLED ║ @@ -87,6 +94,7 @@ git: ``` ## Reverting + ``` /worktree-disable ``` diff --git a/.claude/config.yml b/.claude/config.yml index e001401..7fcb270 100644 --- a/.claude/config.yml +++ b/.claude/config.yml @@ -88,10 +88,10 @@ workflow: # Phase execution control (CRITICAL for scope management) execution: - phase_limit: 1 # Only execute up to this phase - auto_advance: false # NEVER auto-advance to next phase - require_confirmation: true # Require explicit user command for each phase - hard_stop_on_completion: true # Stop execution at phase boundary + phase_limit: 1 # Only execute up to this phase + auto_advance: false # NEVER auto-advance to next phase + require_confirmation: true # Require explicit user command for each phase + hard_stop_on_completion: true # Stop execution at phase boundary # Skills configuration skills: @@ -108,13 +108,22 @@ skills: # Enable with: /worktree-enable git: worktrees: - enabled: false # Set to true or run /worktree-enable - base_dir: ".worktrees" # Where worktrees are created - auto_cleanup: true # Remove worktrees after task completion - max_concurrent: 3 # Max parallel worktrees - branch_prefix: "task/" # Prefix for worktree branches - merge_strategy: "auto" # auto | manual | squash - require_review: false # Require review-agent before merge + enabled: false # Set to true or run /worktree-enable + base_dir: ".worktrees" # Where worktrees are created + auto_cleanup: true # Remove worktrees after task completion + max_concurrent: 3 # Max parallel worktrees + branch_prefix: "task/" # Prefix for worktree branches + merge_strategy: "auto" # auto | manual | squash + require_review: false # Require review-agent before merge + +# Multi-model configuration +# Supports Claude, OpenAI, and Gemini for cross-validation and specialization +models: + enabled: true + config_file: ".claude/config/models.yml" + cross_validation: + enabled: true + tasks: ["planning", "review"] # Tasks that get second opinions # Default MCP servers (always enabled) mcp: diff --git a/.claude/config/models.yml b/.claude/config/models.yml new file mode 100644 index 0000000..7e7776c --- /dev/null +++ b/.claude/config/models.yml @@ -0,0 +1,186 @@ +# Multi-Model Configuration +# Configure multiple AI providers for different tasks +# +# Use Cases: +# - Cross-validation: Have different models review each other's work +# - Cost optimization: Use cheaper models for simpler tasks +# - Specialization: Use models that excel at specific tasks +# - Redundancy: Fallback to alternative providers if one is down + +# Available model providers +providers: + anthropic: + enabled: true + env_key: "ANTHROPIC_API_KEY" + models: + - id: "claude-sonnet-4-20250514" + name: "Claude Sonnet 4" + context: 200000 + strengths: ["coding", "analysis", "reasoning"] + cost_tier: "medium" + - id: "claude-opus-4-20250514" + name: "Claude Opus 4" + context: 200000 + strengths: ["complex-reasoning", "nuanced-writing", "deep-analysis"] + cost_tier: "high" + + openai: + enabled: true # Set to true if OPENAI_API_KEY is available + env_key: "OPENAI_API_KEY" + models: + - id: "gpt-4o" + name: "GPT-4o" + context: 128000 + strengths: ["general", "speed", "multimodal"] + cost_tier: "medium" + - id: "gpt-4-turbo" + name: "GPT-4 Turbo" + context: 128000 + strengths: ["coding", "instruction-following"] + cost_tier: "medium" + - id: "o1" + name: "o1" + context: 200000 + strengths: ["reasoning", "math", "complex-problems"] + cost_tier: "high" + + google: + enabled: true # Set to true if GOOGLE_API_KEY is available + env_key: "GOOGLE_API_KEY" + models: + - id: "gemini-2.0-flash" + name: "Gemini 2.0 Flash" + context: 1000000 + strengths: ["speed", "large-context", "multimodal"] + cost_tier: "low" + - id: "gemini-2.5-pro" + name: "Gemini 2.5 Pro" + context: 2000000 + strengths: ["reasoning", "coding", "large-context"] + cost_tier: "medium" + +# Default model assignments per task type +defaults: + # Primary model for each task type + primary: + planning: "claude-sonnet-4-20250514" + development: "claude-sonnet-4-20250514" + review: "claude-sonnet-4-20250514" + testing: "claude-sonnet-4-20250514" + documentation: "claude-sonnet-4-20250514" + + # Secondary model for cross-validation (optional) + # Set to null to disable cross-validation + secondary: + planning: "gemini-2.5-pro" # Different perspective on architecture + review: "gpt-4o" # Independent code review + testing: null # No cross-validation for tests + documentation: null # No cross-validation for docs + +# Cross-validation configuration +cross_validation: + enabled: true + + # When to use cross-validation + triggers: + planning: + always: true # Always get second opinion on plans + description: "Architecture decisions benefit from multiple perspectives" + + review: + on_complexity: "high" # Only for complex code reviews + on_security: true # Always for security-sensitive code + on_request: true # When explicitly requested + description: "Critical code benefits from independent review" + + development: + on_request: true # Only when explicitly requested + description: "Optional second opinion on implementation" + + # How to handle disagreements + conflict_resolution: + strategy: "human" # human | primary | vote | merge + notify: true # Notify user of disagreements + + # Output format for cross-validation + output: + show_both: true # Show both model responses + highlight_differences: true # Highlight where models disagree + summary: true # Generate summary of consensus/conflicts + +# Agent-specific model overrides +# Override the default model for specific agents +agent_overrides: + planner: + primary: "claude-sonnet-4-20250514" + secondary: "gemini-2.5-pro" + cross_validate: true + + review: + primary: "claude-sonnet-4-20250514" + secondary: "gpt-4o" + cross_validate: true + + dev: + primary: "claude-sonnet-4-20250514" + secondary: null + cross_validate: false + + test: + primary: "claude-sonnet-4-20250514" + secondary: null + cross_validate: false + + docs: + primary: "gemini-2.0-flash" # Fast model for docs + secondary: null + cross_validate: false + +# Cost optimization settings +cost_optimization: + enabled: true + + # Use cheaper models for these tasks + use_budget_model: + - "simple-refactoring" + - "documentation-updates" + - "code-formatting" + - "simple-tests" + + budget_model: "gemini-2.0-flash" + + # Always use premium model for these tasks + use_premium_model: + - "architecture-decisions" + - "security-reviews" + - "complex-algorithms" + - "api-design" + + premium_model: "claude-opus-4-20250514" + +# Fallback chain if primary model fails +fallback: + enabled: true + chain: + - "claude-sonnet-4-20250514" + - "gpt-4o" + - "gemini-2.5-pro" + max_retries: 2 + retry_delay_ms: 1000 + +# Model-specific prompting adjustments +prompt_adjustments: + openai: + # OpenAI models prefer explicit JSON formatting + prefer_json_mode: true + system_prompt_style: "concise" + + google: + # Gemini handles large contexts well + include_full_context: true + system_prompt_style: "detailed" + + anthropic: + # Claude excels with examples + include_examples: true + system_prompt_style: "balanced" diff --git a/.claude/mcp/default-servers.md b/.claude/mcp/default-servers.md index d49673e..e8a863c 100644 --- a/.claude/mcp/default-servers.md +++ b/.claude/mcp/default-servers.md @@ -1,26 +1,31 @@ # Default MCP Servers -These MCP servers are recommended for all projects using Claude Code Sidekick. They provide essential capabilities for structured development. +These MCP servers are recommended for all projects using Claude Code Sidekick. +They provide essential capabilities for structured development. ## Required MCPs ### 1. Serena (Structured Reasoning) -**Purpose:** Provides structured reasoning, code analysis, and semantic understanding of your codebase. +**Purpose:** Provides structured reasoning, code analysis, and semantic +understanding of your codebase. **Installation:** + ```bash claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \ serena start-mcp-server --project "$(pwd)" ``` **When Used:** + - During project analysis (`/project-planner`) - Code review and quality checks - Architecture decisions - Complex refactoring tasks **Integration with Sidekick:** + - Planner agent uses Serena for requirement analysis - Review agent uses Serena for code quality assessment - Orchestrator consults Serena for task dependency resolution @@ -30,17 +35,20 @@ claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \ **Purpose:** Browser automation, testing, and debugging capabilities. **Installation:** + ```bash claude mcp add chrome-devtools -- npx @anthropic/mcp-chrome-devtools ``` **When Used:** + - Frontend testing and validation - Accessibility audits (WCAG compliance) - Performance profiling - Visual regression testing **Integration with Sidekick:** + - Test agent uses for browser-based tests - Dev agent uses for live preview during development - Review agent uses for accessibility validation @@ -50,17 +58,20 @@ claude mcp add chrome-devtools -- npx @anthropic/mcp-chrome-devtools **Purpose:** Documentation lookup and context enrichment from external sources. **Installation:** + ```bash claude mcp add context7 -- npx @anthropic/mcp-context7 ``` **When Used:** + - Looking up framework documentation - API reference queries - Best practices lookup - Integration guidance **Integration with Sidekick:** + - All agents can query for relevant documentation - Reduces hallucination by grounding in real docs @@ -73,7 +84,14 @@ Add to your Claude Code settings (`~/.claude/settings.json`): "mcpServers": { "serena": { "command": "uvx", - "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--project", "."], + "args": [ + "--from", + "git+https://github.com/oraios/serena", + "serena", + "start-mcp-server", + "--project", + "." + ], "env": {} }, "chrome-devtools": { @@ -82,7 +100,7 @@ Add to your Claude Code settings (`~/.claude/settings.json`): "env": {} }, "context7": { - "command": "npx", + "command": "npx", "args": ["@anthropic/mcp-context7"], "env": {} } @@ -92,35 +110,37 @@ Add to your Claude Code settings (`~/.claude/settings.json`): ## Quick Setup Command -Run `/mcp-setup` after filling out PROJECT_STARTER.md to automatically configure all required MCPs based on your project type. +Run `/mcp-setup` after filling out PROJECT_STARTER.md to automatically configure +all required MCPs based on your project type. ## MCP Usage in Agents ### Planner Agent + Serena + ```yaml When analyzing PROJECT_STARTER.md: - 1. Use Serena to parse requirements - 2. Use Serena to identify code patterns - 3. Use Context7 to lookup framework best practices + 1. Use Serena to parse requirements 2. Use Serena to identify code patterns 3. + Use Context7 to lookup framework best practices ``` ### Dev Agent + Chrome DevTools + ```yaml During implementation: - 1. Use Chrome DevTools for live preview - 2. Run accessibility checks after each component - 3. Profile performance of new features + 1. Use Chrome DevTools for live preview 2. Run accessibility checks after each + component 3. Profile performance of new features ``` ### Test Agent + Chrome DevTools + ```yaml During testing: - 1. Run automated browser tests - 2. Capture screenshots for visual regression - 3. Validate responsive behavior + 1. Run automated browser tests 2. Capture screenshots for visual regression 3. + Validate responsive behavior ``` ### Review Agent + All MCPs + ```yaml During review: 1. Serena: Code quality analysis diff --git a/.claude/skills/checkpoint-manager/SKILL.md b/.claude/skills/checkpoint-manager/SKILL.md index e034e5f..5fbcc3c 100644 --- a/.claude/skills/checkpoint-manager/SKILL.md +++ b/.claude/skills/checkpoint-manager/SKILL.md @@ -1,9 +1,13 @@ # Checkpoint Manager Skill ## Purpose -Manages execution checkpoints to ensure proper stopping points and enable safe resumption of work. Creates explicit gates that require user approval before continuing. + +Manages execution checkpoints to ensure proper stopping points and enable safe +resumption of work. Creates explicit gates that require user approval before +continuing. ## When to Use + - At phase boundaries - After critical task completion - Before any deployment action @@ -12,6 +16,7 @@ Manages execution checkpoints to ensure proper stopping points and enable safe r ## Checkpoint Types ### 1. Phase Checkpoint (MANDATORY) + Triggered when all tasks in a phase complete. ``` @@ -37,6 +42,7 @@ Triggered when all tasks in a phase complete. ``` ### 2. Critical Task Checkpoint + Triggered after high-risk tasks (database changes, auth setup, etc.) ``` @@ -53,6 +59,7 @@ Review before continuing: /checkpoint-review PHASE1-005 ``` ### 3. Decision Checkpoint + Triggered when agent encounters ambiguity. ``` @@ -70,6 +77,7 @@ Waiting for input: /decide A or /decide B ## Checkpoint State Stored in `.claude/state/checkpoints.json`: + ```json { "checkpoints": [ @@ -94,48 +102,59 @@ Stored in `.claude/state/checkpoints.json`: ## Commands ### View Current Checkpoint + ``` /checkpoint-status ``` ### Approve and Continue + ``` /checkpoint-continue ``` + Marks checkpoint as approved, allows execution to continue. ### Rollback + ``` /checkpoint-rollback ``` + Reverts to state before checkpoint (requires git). ### Review Specific Checkpoint + ``` /checkpoint-review ``` + Shows detailed diff of changes. ## Integration with Git Each checkpoint creates a git tag: + ```bash git tag -a "checkpoint/phase-1-complete" -m "Phase 1 checkpoint" ``` Rollback uses: + ```bash git reset --hard "checkpoint/phase-1-start" ``` ## Enforcement Rules -1. **No auto-continue**: Checkpoints MUST wait for explicit `/checkpoint-continue` +1. **No auto-continue**: Checkpoints MUST wait for explicit + `/checkpoint-continue` 2. **Logged approval**: Record who approved and when 3. **Reversible**: Always maintain ability to rollback 4. **Visible**: Checkpoints must output clear terminal messages ## Configuration + ```yaml # .claude/config.yml checkpoints: diff --git a/.claude/skills/git-worktree/SKILL.md b/.claude/skills/git-worktree/SKILL.md index da62dd0..f09cadf 100644 --- a/.claude/skills/git-worktree/SKILL.md +++ b/.claude/skills/git-worktree/SKILL.md @@ -1,21 +1,25 @@ # Git Worktree Skill ## Purpose -Enables parallel task execution using git worktrees. Each task runs in an isolated worktree, preventing conflicts and allowing concurrent development. + +Enables parallel task execution using git worktrees. Each task runs in an +isolated worktree, preventing conflicts and allowing concurrent development. ## Opt-In Add to `.claude/config.yml`: + ```yaml git: worktrees: enabled: true - base_dir: ".worktrees" # Where worktrees are created - auto_cleanup: true # Remove worktrees after task completion - max_concurrent: 3 # Max parallel worktrees + base_dir: '.worktrees' # Where worktrees are created + auto_cleanup: true # Remove worktrees after task completion + max_concurrent: 3 # Max parallel worktrees ``` Or run: + ``` /worktree-enable ``` @@ -23,6 +27,7 @@ Or run: ## How It Works ### Without Worktrees (Default) + ``` main branch ↓ @@ -30,6 +35,7 @@ Task 1 → Task 2 → Task 3 (sequential) ``` ### With Worktrees (Opt-In) + ``` main branch ↓ @@ -43,27 +49,35 @@ Merge all back to main ## Commands ### Enable Worktrees + ``` /worktree-enable ``` + Enables worktree mode for current project. ### Disable Worktrees + ``` /worktree-disable ``` + Returns to sequential mode. ### List Active Worktrees + ``` /worktree-list ``` + Shows all active worktrees and their status. ### Clean Up Worktrees + ``` /worktree-cleanup ``` + Removes completed/merged worktrees. ## Task Runner Integration @@ -71,17 +85,20 @@ Removes completed/merged worktrees. When worktrees are enabled, task-runner changes behavior: ### Step 1: Create Worktree for Task + ```bash git worktree add .worktrees/PHASE1-001 -b task/PHASE1-001 ``` ### Step 2: Execute Task in Worktree + ```bash cd .worktrees/PHASE1-001 # Agent executes task here ``` ### Step 3: Merge on Completion + ```bash git checkout main git merge task/PHASE1-001 @@ -112,13 +129,17 @@ With worktrees, independent tasks run in parallel: ## Merge Strategy ### Auto-Merge (default) + Tasks auto-merge to main when: + - All tests pass - No conflicts detected - Review agent approves ### Manual Merge + If conflicts or review needed: + ``` ⚠️ MERGE REQUIRED @@ -138,18 +159,19 @@ To resolve: git: worktrees: enabled: true - base_dir: ".worktrees" + base_dir: '.worktrees' auto_cleanup: true max_concurrent: 3 - branch_prefix: "task/" - merge_strategy: "auto" # auto | manual | squash - require_review: false # Require review-agent before merge - preserve_on_failure: true # Keep worktree if task fails + branch_prefix: 'task/' + merge_strategy: 'auto' # auto | manual | squash + require_review: false # Require review-agent before merge + preserve_on_failure: true # Keep worktree if task fails ``` ## .gitignore When enabled, adds to `.gitignore`: + ``` .worktrees/ ``` diff --git a/.claude/skills/phase-control/SKILL.md b/.claude/skills/phase-control/SKILL.md index f23ce63..a895e52 100644 --- a/.claude/skills/phase-control/SKILL.md +++ b/.claude/skills/phase-control/SKILL.md @@ -1,9 +1,12 @@ # Phase Control Skill ## Purpose -Enforces strict phase boundaries during project execution. Prevents scope creep by ensuring work stays within the authorized phase. + +Enforces strict phase boundaries during project execution. Prevents scope creep +by ensuring work stays within the authorized phase. ## When to Use + - Before executing any task - When task-runner completes a phase - When any agent attempts to create deliverables @@ -12,25 +15,32 @@ Enforces strict phase boundaries during project execution. Prevents scope creep ## Core Rules ### 1. Phase Authorization + ```yaml -current_phase: 1 # Read from .claude/state/execution.json -authorized_phases: [1] # Only phases explicitly approved +current_phase: 1 # Read from .claude/state/execution.json +authorized_phases: [1] # Only phases explicitly approved ``` ### 2. Pre-Task Validation + Before executing ANY task: + 1. Check task ID prefix matches current phase (e.g., PHASE1-xxx) 2. Verify deliverables are within phase scope 3. Confirm no dependencies on future-phase tasks ### 3. Scope Violation Detection + Flag as SCOPE VIOLATION if: + - Task creates files listed in Phase N+1 deliverables - Task references components from future phases - Task implements features marked "Phase 2+" in PROJECT_STARTER.md ### 4. Hard Stop Protocol + When phase completes: + ``` ┌─────────────────────────────────────────────────────────────┐ │ ⛔ PHASE BOUNDARY - EXECUTION HALTED │ @@ -47,7 +57,9 @@ When phase completes: ``` ## State File + Maintain execution state in `.claude/state/execution.json`: + ```json { "current_phase": 1, @@ -62,24 +74,31 @@ Maintain execution state in `.claude/state/execution.json`: ## Commands ### Check Phase Status + ``` /phase-status ``` + Output: Current phase, completion %, next steps ### Authorize Next Phase + ``` /phase-approve 2 ``` + Explicitly authorizes Phase 2 execution ### Lock to Phase + ``` /phase-lock 1 ``` + Prevents any work beyond Phase 1 ## Integration Points + - task-runner.md: Calls phase-control before each task - orchestrator-agent.md: Respects phase boundaries - dev-agent.md: Checks scope before creating files diff --git a/.claude/skills/scope-guard/SKILL.md b/.claude/skills/scope-guard/SKILL.md index 44c70ef..bf14342 100644 --- a/.claude/skills/scope-guard/SKILL.md +++ b/.claude/skills/scope-guard/SKILL.md @@ -1,9 +1,13 @@ # Scope Guard Skill ## Purpose -Monitors all agent actions to prevent out-of-scope work. Acts as a watchdog that validates every file creation, modification, and task execution against the current phase scope. + +Monitors all agent actions to prevent out-of-scope work. Acts as a watchdog that +validates every file creation, modification, and task execution against the +current phase scope. ## When to Use + - Automatically invoked before any file operation - Called by dev-agent before implementation - Called by orchestrator before task delegation @@ -11,6 +15,7 @@ Monitors all agent actions to prevent out-of-scope work. Acts as a watchdog that ## Scope Validation Rules ### 1. File-Level Scope Check + Before creating/modifying ANY file: ```javascript @@ -18,21 +23,23 @@ Before creating/modifying ANY file: function validateScope(filePath, currentPhase) { const phaseDeliverables = loadPhaseDeliverables(currentPhase); const futureDeliverables = loadFuturePhaseDeliverables(currentPhase); - + if (futureDeliverables.includes(filePath)) { return { allowed: false, reason: `File "${filePath}" is a Phase ${futurePhase} deliverable`, - action: "STOP" + action: 'STOP', }; } - + return { allowed: true }; } ``` ### 2. Task-Level Scope Check + Before executing ANY task: + ```yaml validation: - task_id_matches_phase: true @@ -42,7 +49,9 @@ validation: ``` ### 3. Code-Level Scope Check + During implementation, flag: + - Imports from future-phase modules - References to future-phase components - API calls to future-phase endpoints @@ -50,6 +59,7 @@ During implementation, flag: ## Violation Handling ### Level 1: Warning + ``` ⚠️ SCOPE WARNING Creating file that may belong to future phase. @@ -60,6 +70,7 @@ Continue? (Requires explicit confirmation) ``` ### Level 2: Block + ``` ⛔ SCOPE VIOLATION - BLOCKED Cannot create Phase 2 deliverable while in Phase 1. @@ -72,6 +83,7 @@ Resolution: Run /task-planner phase=2 first ``` ### Level 3: Emergency Stop + ``` 🚨 CRITICAL SCOPE VIOLATION Multiple out-of-scope operations detected. @@ -86,7 +98,9 @@ Manual review required before continuing. ``` ## Scope Definition Sources + Read scope from (in priority order): + 1. `.claude/tasks/phase-N-tasks.md` - Task deliverables 2. `.claude/project-plan/phase_N.md` - Phase scope 3. `PROJECT_STARTER.md` - Overall phase definitions @@ -94,6 +108,7 @@ Read scope from (in priority order): ## Integration ### With Dev Agent + ```markdown ## Before Any Implementation @@ -104,6 +119,7 @@ Read scope from (in priority order): ``` ### With Orchestrator + ```markdown ## Before Task Delegation @@ -114,11 +130,12 @@ Read scope from (in priority order): ``` ## Configuration + ```yaml # .claude/config.yml scope_guard: enabled: true - strictness: "strict" # strict | moderate | relaxed - on_violation: "block" # block | warn | log + strictness: 'strict' # strict | moderate | relaxed + on_violation: 'block' # block | warn | log allow_override: false ``` diff --git a/.github/BRANCH_PROTECTION.md b/.github/BRANCH_PROTECTION.md index 28cea91..02c5306 100644 --- a/.github/BRANCH_PROTECTION.md +++ b/.github/BRANCH_PROTECTION.md @@ -18,13 +18,13 @@ fix/* ## Branch Purposes -| Branch | Purpose | Protection | -|--------|---------|------------| -| `main` | Production-ready code | Highly protected | -| `dev` | Integration/staging | Protected | -| `feature/*` | New features | None | -| `feat/*` | New features (alias) | None | -| `fix/*` | Bug fixes | None | +| Branch | Purpose | Protection | +| ----------- | --------------------- | ---------------- | +| `main` | Production-ready code | Highly protected | +| `dev` | Integration/staging | Protected | +| `feature/*` | New features | None | +| `feat/*` | New features (alias) | None | +| `fix/*` | Bug fixes | None | ## Workflow @@ -59,6 +59,7 @@ When you create a PR to `dev`, these checks run automatically: ### 3. Merge to Dev Once PR checks pass and code is approved: + - Squash and merge to `dev` - Feature branch is deleted @@ -79,6 +80,7 @@ Actions → Merge Dev to Main → Run workflow ``` Options: + - **Merge strategy**: merge, squash, or rebase - **Create release**: Auto-tag and create GitHub release - **Version bump**: patch, minor, or major @@ -94,9 +96,9 @@ required_approving_review_count: 1 dismiss_stale_reviews: true require_status_checks: true required_status_checks: - - "CI - Code Quality & Validation / Lint & Code Quality" - - "CI - Code Quality & Validation / Test CLI Tool" - - "CI - Code Quality & Validation / Security Audit" + - 'CI - Code Quality & Validation / Lint & Code Quality' + - 'CI - Code Quality & Validation / Test CLI Tool' + - 'CI - Code Quality & Validation / Security Audit' require_branches_to_be_up_to_date: true restrict_pushes: true allow_force_pushes: false @@ -111,20 +113,20 @@ require_pull_request_reviews: true required_approving_review_count: 1 require_status_checks: true required_status_checks: - - "PR Quality Check / Lint & Format" - - "PR Quality Check / Run Tests" + - 'PR Quality Check / Lint & Format' + - 'PR Quality Check / Run Tests' require_branches_to_be_up_to_date: true allow_force_pushes: false ``` ## CI/CD Workflows -| Workflow | Trigger | Purpose | -|----------|---------|---------| -| `ci.yml` | Push/PR to main, dev | Full CI validation | -| `pr-quality-check.yml` | PR to dev | Quality gates for dev | -| `merge-dev-to-main.yml` | Manual | Controlled releases | -| `pre-commit.yml` | Push | Pre-commit validation | +| Workflow | Trigger | Purpose | +| ----------------------- | -------------------- | --------------------- | +| `ci.yml` | Push/PR to main, dev | Full CI validation | +| `pr-quality-check.yml` | PR to dev | Quality gates for dev | +| `merge-dev-to-main.yml` | Manual | Controlled releases | +| `pre-commit.yml` | Push | Pre-commit validation | ## Setting Up API Keys for AI Review diff --git a/.github/workflows/pr-quality-check.yml b/.github/workflows/pr-quality-check.yml index 5cb4752..cf19d88 100644 --- a/.github/workflows/pr-quality-check.yml +++ b/.github/workflows/pr-quality-check.yml @@ -121,7 +121,7 @@ jobs: - name: Check for secrets in code run: | echo "Checking for potential secrets..." - + # Check for common secret patterns PATTERNS=( "sk-[a-zA-Z0-9]{20,}" @@ -130,16 +130,16 @@ jobs: "AKIA[A-Z0-9]{16}" "password\s*=\s*['\"][^'\"]+['\"]" ) - + FOUND_SECRETS=false - + for pattern in "${PATTERNS[@]}"; do if grep -rE "$pattern" --include="*.js" --include="*.ts" --include="*.json" . 2>/dev/null | grep -v node_modules | grep -v ".env.example"; then echo "⚠️ Potential secret pattern found: $pattern" FOUND_SECRETS=true fi done - + if [ "$FOUND_SECRETS" = true ]; then echo "::warning::Potential secrets detected. Please review." else @@ -171,7 +171,7 @@ jobs: - name: Check for redundant code run: | echo "Checking for code redundancy..." - + # Check for duplicate imports for file in $(find . -name "*.js" -o -name "*.ts" | grep -v node_modules); do DUPES=$(grep "^import" "$file" 2>/dev/null | sort | uniq -d) @@ -180,13 +180,13 @@ jobs: echo "$DUPES" fi done - + echo "✅ Redundancy check complete" - name: Check file sizes run: | echo "Checking for large files..." - + # Find JS/TS files larger than 500 lines find . -name "*.js" -o -name "*.ts" | grep -v node_modules | while read file; do LINES=$(wc -l < "$file") @@ -194,7 +194,7 @@ jobs: echo "⚠️ Large file: $file ($LINES lines)" fi done - + echo "✅ File size check complete" # Job 5: Multi-Model AI Review (when secrets available) @@ -230,8 +230,10 @@ jobs: - name: Get changed files id: changed run: | - CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(js|ts|jsx|tsx)$' | grep -v node_modules | head -5) + # Get changed files as space-separated single line + CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(js|ts|jsx|tsx)$' | grep -v node_modules | head -5 | tr '\n' ' ') echo "files=$CHANGED" >> $GITHUB_OUTPUT + echo "Found files: $CHANGED" - name: Run AI Review if: ${{ env.OPENAI_API_KEY != '' }} @@ -241,9 +243,9 @@ jobs: GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} run: | echo "🤖 Running multi-model AI code review..." - + cd tools/multi-model - + # Review changed files (limit to 5 for cost control) for file in ${{ steps.changed.outputs.files }}; do if [ -f "../../$file" ]; then @@ -251,7 +253,7 @@ jobs: node bin/review.js "../../$file" --quick --json >> ../../review-results.json 2>/dev/null || true fi done - + echo "✅ AI review complete" - name: Post Review Summary @@ -287,7 +289,7 @@ jobs: echo "| Security | ${{ needs.security.result == 'success' && '✅' || '⚠️' }} |" >> $GITHUB_STEP_SUMMARY echo "| Quality | ${{ needs.quality.result == 'success' && '✅' || '⚠️' }} |" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY - + if [ "${{ needs.lint.result }}" != "success" ] || [ "${{ needs.test.result }}" != "success" ]; then echo "❌ **Some required checks failed. Please fix before merging.**" >> $GITHUB_STEP_SUMMARY exit 1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d5b2ad..9c40052 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,14 +6,18 @@ All notable changes to Claude Code Sidekick will be documented in this file. ### Added -- **Git Worktree Support** - Opt-in parallel task execution for concurrent development workflows +- **Git Worktree Support** - Opt-in parallel task execution for concurrent + development workflows - **Phase Control System** - Structured development phases with scope guards - **MCP Integration** - 35+ pre-configured Model Context Protocol integrations -- **Shopify Development Support** - Complete Shopify theme and app development templates +- **Shopify Development Support** - Complete Shopify theme and app development + templates - **WordPress Development Support** - WordPress plugin and theme scaffolding - **Vitest Testing Framework** - Complete test suite with coverage reporting -- **GitHub Actions CI/CD** - Automated linting, formatting, and testing workflows -- **Comprehensive Agent Library** - 50+ specialized agents for every development task +- **GitHub Actions CI/CD** - Automated linting, formatting, and testing + workflows +- **Comprehensive Agent Library** - 50+ specialized agents for every development + task - **Hooks Configuration System** - 32+ automated hooks with TRUE/FALSE toggles - **Quick Start Presets** - Master toggles for simplified configuration - **Python FastAPI Walkthrough** - Complete backend development guide diff --git a/CLAUDE.md b/CLAUDE.md index 0824f99..baf095f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,6 +43,7 @@ tasks/phase-N-tasks.md **The system WILL NOT auto-advance to the next phase.** After completing Phase N: + 1. Execution STOPS completely 2. User must review completed work 3. User must explicitly run `/task-planner phase=N+1` @@ -54,21 +55,24 @@ This prevents scope creep and ensures controlled, phased delivery. These skills are loaded automatically and enforce development discipline: -| Skill | Purpose | -|-------|---------| -| `phase-control` | Enforces phase boundaries, prevents auto-advance | -| `scope-guard` | Validates all file operations against current phase | -| `checkpoint-manager` | Creates explicit approval gates | -| `git-worktree` | Parallel task execution (opt-in) | +| Skill | Purpose | +| -------------------- | --------------------------------------------------- | +| `phase-control` | Enforces phase boundaries, prevents auto-advance | +| `scope-guard` | Validates all file operations against current phase | +| `checkpoint-manager` | Creates explicit approval gates | +| `git-worktree` | Parallel task execution (opt-in) | ## Git Worktree Mode (Opt-In) Enable parallel task execution with: + ``` /worktree-enable ``` -This creates isolated worktrees for each task, allowing independent tasks to run simultaneously: +This creates isolated worktrees for each task, allowing independent tasks to run +simultaneously: + ``` main branch ├── .worktrees/task-001/ → Task 1 @@ -82,11 +86,92 @@ Disable with `/worktree-disable`. These MCP servers are enabled by default: -| MCP | Purpose | -|-----|---------| -| `serena` | Structured reasoning, code analysis | +| MCP | Purpose | +| ----------------- | ------------------------------------- | +| `serena` | Structured reasoning, code analysis | | `chrome-devtools` | Browser testing, accessibility audits | -| `context7` | Documentation lookup, best practices | +| `context7` | Documentation lookup, best practices | + +## Multi-Model AI Toolkit + +The project includes a powerful multi-model toolkit at `tools/multi-model/` that +leverages OpenAI, Anthropic, and Google Gemini together. + +### Available Tools + +| CLI Command | Purpose | Documentation | +| ----------- | --------------------------------------- | ----------------------------------------------------------- | +| `mm-review` | Consensus code review (multiple models) | [View](tools/multi-model/README.md#multi-model-code-review) | +| `mm-index` | Index codebase for semantic search | [View](tools/multi-model/README.md#codebase-indexing) | +| `mm-search` | Search code by meaning, not keywords | [View](tools/multi-model/README.md#semantic-search) | + +### Quick Start + +```bash +cd tools/multi-model +pnpm install + +# Review code with multiple AI models +pnpm review -- ../cli/src/scaffold.js --deep + +# Index the codebase +pnpm index -- ../ + +# Search semantically +pnpm search -- "project scaffolding" +``` + +### Programmatic Usage + +```javascript +import { + reviewCode, + createRouter, + searchCodebase, +} from './tools/multi-model/index.js'; + +// Consensus code review +const results = await reviewCode(code, { filename: 'app.js' }); +console.log(results.confirmedIssues); // Issues 2+ models agree on + +// Intelligent routing (auto-selects best model per task) +const router = createRouter('balanced'); +const response = await router.route('Explain this architecture...'); + +// Semantic search +const matches = await searchCodebase('authentication logic', { + indexPath: '.code-index/index.json', +}); +``` + +### Model Routing Logic + +The router automatically selects the optimal model based on task type: + +| Task Type | Optimal Model | Reason | +| ------------------------- | ------------- | ----------------------- | +| Long context (>50k chars) | Claude Sonnet | 200k context window | +| Code generation | GPT-4o | Mature function calling | +| Documentation | Claude Sonnet | Nuanced, thorough | +| Security review | Claude Sonnet | Careful reasoning | +| Quick refactors | GPT-4o-mini | Fast, accurate | +| Linting/style | Gemini Flash | Cheapest | + +### Examples + +- [Pre-Commit Hook](tools/multi-model/examples/pre-commit-hook.js) - Block + commits with critical issues +- [Agent Integration](tools/multi-model/examples/agent-integration.js) - Smart + assistant workflows + +### Required Environment Variables + +```bash +# In .env at project root +OPENAI_API_KEY=sk-... +ANTHROPIC_API_KEY=sk-ant-... +GEMINI_API_KEY=... +``` ### Commands diff --git a/README.md b/README.md index 7dfa91b..26f5d6a 100644 --- a/README.md +++ b/README.md @@ -193,6 +193,39 @@ requirements first with EARS notation Clear, testable, unambiguous requirements that become your implementation roadmap. +### 6. Multi-Model AI Toolkit + +**Others:** Locked into a single AI provider **Sidekick:** Use Claude, GPT-4, +and Gemini together with intelligent routing + +```bash +# Consensus code review (multiple models must agree) +cd tools/multi-model +pnpm review -- src/app.js --deep + +# Semantic code search +pnpm index -- /path/to/project +pnpm search -- "authentication middleware" +``` + +**Built-in Multi-Model Tools:** + +| Tool | Purpose | Models Used | +| ------------- | ------------------------ | -------------------------- | +| `mm-review` | Consensus code review | GPT-4o + Claude + Gemini | +| `mm-index` | Codebase indexing | OpenAI Embeddings | +| `mm-search` | Semantic search | OpenAI Embeddings | +| `ModelRouter` | Intelligent task routing | Auto-selects optimal model | + +**Cross-Validation Benefits:** + +- Different models catch different issues +- Architecture decisions get multiple perspectives +- Security reviews are more thorough +- Cost optimization (use cheaper models for simple tasks) + +[View Multi-Model Toolkit →](tools/multi-model/README.md) + --- ## Comparison @@ -306,6 +339,29 @@ agent-library/ └── templates/ # Create custom agents ``` +### Multi-Model Toolkit + +``` +tools/multi-model/ +├── bin/ +│ ├── review.js # mm-review CLI - consensus code review +│ ├── index-codebase.js # mm-index CLI - codebase indexing +│ └── search.js # mm-search CLI - semantic search +├── lib/ +│ ├── clients.js # Unified API for OpenAI, Anthropic, Gemini +│ ├── code-review.js # Multi-model consensus review system +│ ├── model-router.js # Intelligent task routing +│ └── embeddings.js # Codebase indexing & semantic search +├── examples/ +│ ├── pre-commit-hook.js # Git hook integration example +│ └── agent-integration.js # Claude Code workflow example +├── index.js # Main exports +├── package.json +└── README.md # Full documentation +``` + +[View Multi-Model Documentation →](tools/multi-model/README.md) + --- ## Documentation @@ -320,7 +376,8 @@ agent-library/ ### Comprehensive Guides - [**Real-World SSG Example**](docs/guides/real-world-example-ssg.md) - Build a - production static site with blog, SEO, and modern CSS (with terminal screenshots) + production static site with blog, SEO, and modern CSS (with terminal + screenshots) - [Nuxt Full-Stack Walkthrough](docs/guides/nuxt-fullstack-walkthrough.md) - Build complete Nuxt app - [Python FastAPI Walkthrough](docs/guides/python-fastapi-walkthrough.md) - @@ -336,6 +393,21 @@ agent-library/ - [Hooks Configuration](.claude/hooks/README.md) - Automation hooks - [Agent Library](agent-library/README.md) - All available agents +### Multi-Model AI Tools + +- [Multi-Model Toolkit Overview](tools/multi-model/README.md) - Full + documentation +- [Consensus Code Review](tools/multi-model/README.md#multi-model-code-review) - + Run code through multiple AI models +- [Intelligent Model Routing](tools/multi-model/README.md#intelligent-model-routing) - + Auto-select optimal model per task +- [Semantic Code Search](tools/multi-model/README.md#semantic-code-search) - + Index and search codebase by meaning +- [Pre-Commit Hook Example](tools/multi-model/examples/pre-commit-hook.js) - + CI/CD integration +- [Agent Integration Example](tools/multi-model/examples/agent-integration.js) - + Claude Code workflows + ### Advanced - [Creating Custom Agents](agent-library/templates/README.md) diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md index 53df3ad..9dc88e5 100644 --- a/docs/EXAMPLES.md +++ b/docs/EXAMPLES.md @@ -6,7 +6,8 @@ ## Quick Overview -Claude Code Sidekick transforms project development from "figure it out" to "follow the system." +Claude Code Sidekick transforms project development from "figure it out" to +"follow the system." ``` ┌─────────────────────────────────────────────────────────────────────┐ @@ -43,7 +44,7 @@ $ npx create-claude-project ╰──────────────────────────────────────────╯ ? Project name: › my-saas-app -? Select a preset: › +? Select a preset: › ○ Static Website - Landing pages, marketing sites ○ Astro Site - Content-heavy sites, blogs ● Next.js App - Full-stack React framework @@ -104,7 +105,8 @@ my-saas-app/ ## Example 2: The PROJECT_STARTER.md File -This is where you define what you're building. The AI reads this to understand your project. +This is where you define what you're building. The AI reads this to understand +your project. ```markdown # Project Starter Template @@ -112,13 +114,16 @@ This is where you define what you're building. The AI reads this to understand y ## Project Information ### Project Name + TaskFlow - Team Task Management ### Project Description -A Kanban-style task management app for small teams. Users can create boards, -add tasks, assign team members, and track progress with drag-and-drop. + +A Kanban-style task management app for small teams. Users can create boards, add +tasks, assign team members, and track progress with drag-and-drop. ### Project Type + web-app --- @@ -126,10 +131,12 @@ web-app ## Goals & Objectives ### Primary Goal -Create a fast, accessible task management tool that works offline-first -and syncs when connected. + +Create a fast, accessible task management tool that works offline-first and +syncs when connected. ### Success Criteria + - Sub-100ms interactions - Works offline (PWA) - WCAG 2.1 AA compliant @@ -197,16 +204,17 @@ Next: Run /task-planner to generate implementation tasks ```markdown # Phase 1: Foundation -Generated: 2026-02-21T14:30:00Z -Source: PROJECT_STARTER.md +Generated: 2026-02-21T14:30:00Z Source: PROJECT_STARTER.md ## Project Summary ### Overview + TaskFlow is a Kanban-style task management application targeting small teams. The app prioritizes performance, accessibility, and offline-first architecture. ### Goals + - Fast, responsive drag-and-drop interface - Offline-first with background sync - Real-time collaboration between team members @@ -215,6 +223,7 @@ The app prioritizes performance, accessibility, and offline-first architecture. ## Analysis ### Complexity Assessment + - **Overall Complexity:** Medium-High - **Key Challenges:** - Real-time sync with offline support requires careful state management @@ -222,12 +231,14 @@ The app prioritizes performance, accessibility, and offline-first architecture. - Conflict resolution needs clear, non-disruptive UI ### Dependencies + - **External:** Supabase (auth + realtime), Service Worker API - **Internal:** State → UI → Sync pipeline ## Phase 1 Scope ### Objectives + 1. Set up project structure with Next.js 15 2. Configure Supabase connection 3. Create base component library @@ -235,6 +246,7 @@ The app prioritizes performance, accessibility, and offline-first architecture. 5. Set up testing framework ### Deliverables + - [ ] Working dev environment - [ ] Base layout components - [ ] Design system foundation @@ -245,16 +257,12 @@ The app prioritizes performance, accessibility, and offline-first architecture. ### Architecture ``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ Next.js │────▶│ Supabase │────▶│ Postgres │ -│ (React) │ │ (Realtime) │ │ (D1) │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ - ▼ -┌─────────────┐ -│ Service │ -│ Worker │ + +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Next.js │────▶│ Supabase +│────▶│ Postgres │ │ (React) │ │ (Realtime) │ │ (D1) │ └─────────────┘ +└─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ Service │ │ Worker │ └─────────────┘ + ``` ### Technology Stack @@ -327,46 +335,48 @@ Next: Run /task-runner to execute tasks ### Output: tasks/phase-1-tasks.md -```markdown +````markdown # Phase 1 Tasks -Generated: 2026-02-21T14:35:00Z -Source: project-plan/phase_1.md +Generated: 2026-02-21T14:35:00Z Source: project-plan/phase_1.md ## Task Overview -| ID | Agent | Task | Est. Time | Dependencies | -|----------|-------|---------------------|-----------|--------------| -| TASK-001 | init | Project Setup | 30 min | None | -| TASK-002 | init | Database Setup | 45 min | TASK-001 | -| TASK-003 | dev | Design System | 60 min | TASK-001 | -| TASK-004 | dev | Layout Components | 45 min | TASK-003 | -| TASK-005 | test | Testing Setup | 30 min | TASK-001 | +| ID | Agent | Task | Est. Time | Dependencies | +| -------- | ----- | ----------------- | --------- | ------------ | +| TASK-001 | init | Project Setup | 30 min | None | +| TASK-002 | init | Database Setup | 45 min | TASK-001 | +| TASK-003 | dev | Design System | 60 min | TASK-001 | +| TASK-004 | dev | Layout Components | 45 min | TASK-003 | +| TASK-005 | test | Testing Setup | 30 min | TASK-001 | --- ## TASK-001: Project Setup -**Agent:** init -**Priority:** Critical -**Estimated Time:** 30 minutes +**Agent:** init **Priority:** Critical **Estimated Time:** 30 minutes ### Description -Initialize the Next.js 15 project with TypeScript and establish -the foundational folder structure. + +Initialize the Next.js 15 project with TypeScript and establish the foundational +folder structure. ### Acceptance Criteria + - [ ] Next.js 15 project created with App Router - [ ] TypeScript configured in strict mode - [ ] ESLint and Prettier configured - [ ] Folder structure matches steering/structure.md ### Implementation Notes + ```bash npx create-next-app@latest taskflow --typescript --app --tailwind=false ``` +```` ### Files to Create + - `src/app/layout.tsx` - `src/app/page.tsx` - `src/lib/utils.ts` @@ -375,8 +385,10 @@ npx create-next-app@latest taskflow --typescript --app --tailwind=false --- ## TASK-002: Database Setup + ... -``` + +```` --- @@ -430,7 +442,7 @@ npx create-next-app@latest taskflow --typescript --app --tailwind=false ... (TASK-004, TASK-005) ... ═══════════════════════════════════════════════════════════════════ - ⛔ PHASE 1 COMPLETE + ⛔ PHASE 1 COMPLETE ═══════════════════════════════════════════════════════════════════ Summary: @@ -445,7 +457,7 @@ To continue to Phase 2: 3. Run: /task-runner phase=2 The system will NOT auto-advance. You control the pace. -``` +```` --- @@ -456,27 +468,27 @@ The system will NOT auto-advance. You control the pace. ```yaml # Controls the entire system project: - name: "TaskFlow" - version: "1.0.0" + name: 'TaskFlow' + version: '1.0.0' # Agent system agents: enabled: true - directory: ".claude/agents" + directory: '.claude/agents' # Phase execution control (CRITICAL) execution: - phase_limit: 1 # Only execute this phase - auto_advance: false # NEVER auto-advance - require_confirmation: true # User must approve each phase + phase_limit: 1 # Only execute this phase + auto_advance: false # NEVER auto-advance + require_confirmation: true # User must approve each phase # MCP servers mcp: required: - - name: "serena" - description: "Code analysis" - - name: "context7" - description: "Documentation lookup" + - name: 'serena' + description: 'Code analysis' + - name: 'context7' + description: 'Documentation lookup' ``` ### .claude/agents/dev-agent.yml - Agent Definition @@ -511,17 +523,20 @@ tools: # Code Style Rules ## HTML + - Semantic elements over divs - ARIA labels on interactive elements - No inline styles ## CSS + - Custom properties for theming - CSS layers for organization - Mobile-first responsive design - No utility-first frameworks ## JavaScript + - TypeScript in strict mode - Native APIs over libraries - Progressive enhancement @@ -599,20 +614,20 @@ tools: ## Summary -| Component | Purpose | Location | -|-----------|---------|----------| -| **CLI** | Creates new projects | `npx create-claude-project` | -| **PROJECT_STARTER.md** | Your requirements | Project root | -| **CLAUDE.md** | AI context | Project root | -| **.claude/config.yml** | System configuration | `.claude/` | -| **.claude/commands/** | Slash commands | `.claude/commands/` | -| **.claude/agents/** | Specialized AI agents | `.claude/agents/` | -| **.claude/hooks/** | Automation triggers | `.claude/hooks/` | -| **.claude/mcp/** | MCP integrations | `.claude/mcp/` | -| **.claude/rules/** | Code standards | `.claude/rules/` | +| Component | Purpose | Location | +| ---------------------- | --------------------- | --------------------------- | +| **CLI** | Creates new projects | `npx create-claude-project` | +| **PROJECT_STARTER.md** | Your requirements | Project root | +| **CLAUDE.md** | AI context | Project root | +| **.claude/config.yml** | System configuration | `.claude/` | +| **.claude/commands/** | Slash commands | `.claude/commands/` | +| **.claude/agents/** | Specialized AI agents | `.claude/agents/` | +| **.claude/hooks/** | Automation triggers | `.claude/hooks/` | +| **.claude/mcp/** | MCP integrations | `.claude/mcp/` | +| **.claude/rules/** | Code standards | `.claude/rules/` | **Start here:** `npx create-claude-project` --- -*Built for developers who want more than autocomplete.* +_Built for developers who want more than autocomplete._ diff --git a/docs/SCREENSHOTS.md b/docs/SCREENSHOTS.md index fb71d52..7a42ebd 100644 --- a/docs/SCREENSHOTS.md +++ b/docs/SCREENSHOTS.md @@ -13,12 +13,14 @@ npx create-claude-project my-app ``` **Capture:** + - The interactive prompts - Preset selection menu - Feature checkboxes - Success message -**Tool:** [asciinema](https://asciinema.org/) or [terminalizer](https://terminalizer.com/) +**Tool:** [asciinema](https://asciinema.org/) or +[terminalizer](https://terminalizer.com/) --- @@ -29,6 +31,7 @@ tree -L 2 -a --dirsfirst my-app ``` **Shows:** + - `.claude/` directory - Key configuration files - Clean, organized structure @@ -38,6 +41,7 @@ tree -L 2 -a --dirsfirst my-app ### 3. Workflow Commands **Screenshot 1: /project-planner** + ``` 📋 Reading PROJECT_STARTER.md... ✓ Parsed project requirements @@ -47,6 +51,7 @@ tree -L 2 -a --dirsfirst my-app ``` **Screenshot 2: /task-planner** + ``` 📖 Reading project-plan/phase_1.md... 🔨 Generating tasks... @@ -60,6 +65,7 @@ tree -L 2 -a --dirsfirst my-app ``` **Screenshot 3: /task-runner** + ``` 🚀 Executing Phase 1... ┌──────────────────────────────────────┐ @@ -193,14 +199,14 @@ vhs demo.tape ## Color Palette for Graphics -| Element | Color | Hex | -|---------|-------|-----| -| Success | Green | `#10B981` | -| In Progress | Blue | `#3B82F6` | -| Warning | Yellow | `#F59E0B` | -| Error | Red | `#EF4444` | -| Background | Dark | `#1E1E2E` | -| Text | Light | `#CDD6F4` | +| Element | Color | Hex | +| ----------- | ------ | --------- | +| Success | Green | `#10B981` | +| In Progress | Blue | `#3B82F6` | +| Warning | Yellow | `#F59E0B` | +| Error | Red | `#EF4444` | +| Background | Dark | `#1E1E2E` | +| Text | Light | `#CDD6F4` | --- @@ -209,6 +215,7 @@ vhs demo.tape **Dimensions:** 1200 x 630px (2:1 ratio) **Existing cards:** + - `public/social-card.png` - Main - `public/social-card-v2.png` - Overview - `public/social-card-v3.png` - CLI @@ -227,4 +234,7 @@ vhs demo.tape Renders as: -![Claude Code](https://img.shields.io/badge/Claude-Code-blueviolet) ![Agents](https://img.shields.io/badge/Agents-50+-green) ![MCPs](https://img.shields.io/badge/MCPs-35+-blue) ![Hooks](https://img.shields.io/badge/Hooks-32+-orange) +![Claude Code](https://img.shields.io/badge/Claude-Code-blueviolet) +![Agents](https://img.shields.io/badge/Agents-50+-green) +![MCPs](https://img.shields.io/badge/MCPs-35+-blue) +![Hooks](https://img.shields.io/badge/Hooks-32+-orange) diff --git a/docs/guides/getting-started-tutorial.md b/docs/guides/getting-started-tutorial.md index b4ad151..338f6af 100644 --- a/docs/guides/getting-started-tutorial.md +++ b/docs/guides/getting-started-tutorial.md @@ -2,7 +2,9 @@ > A complete walkthrough of building a project with Claude Code Sidekick -This guide walks you through the entire Claude Code Sidekick workflow from start to finish. By the end, you'll understand how to use each command and agent to build production-ready projects. +This guide walks you through the entire Claude Code Sidekick workflow from start +to finish. By the end, you'll understand how to use each command and agent to +build production-ready projects. --- @@ -25,6 +27,7 @@ Claude Code Sidekick follows a structured, 4-step workflow: ``` Each step builds on the previous one. This structure ensures: + - Clear requirements before coding starts - Organized phases and milestones - Trackable tasks with progress @@ -34,7 +37,8 @@ Each step builds on the previous one. This structure ensures: ## Step 1: Fill Out PROJECT_STARTER.md -The `PROJECT_STARTER.md` file is your project's blueprint. It tells Claude exactly what you want to build. +The `PROJECT_STARTER.md` file is your project's blueprint. It tells Claude +exactly what you want to build. ### Open the File @@ -58,17 +62,21 @@ Here's what each section means: ## Project Information ### Project Name + My Awesome Blog -### Project Description -A personal blog with dark theme, SEO optimization, and a -content management system for markdown posts. +### Project Description + +A personal blog with dark theme, SEO optimization, and a content management +system for markdown posts. ### Project Type + web-app ``` **Tips:** + - Be specific in the description - Mention key features you want - Project type helps Claude choose the right tools @@ -79,22 +87,26 @@ web-app ## Goals & Objectives ### Primary Goal -Create a fast, SEO-optimized blog that ranks well in search -engines and provides an excellent reading experience. + +Create a fast, SEO-optimized blog that ranks well in search engines and provides +an excellent reading experience. ### Success Criteria + - Lighthouse score above 95 - All pages have meta tags and structured data - Mobile responsive design - Blog post pages with proper heading hierarchy ### Non-Goals + - User authentication (this is a static site) - Comments system (will add later) - E-commerce features ``` **Tips:** + - Non-goals are important! They prevent scope creep - Success criteria should be measurable @@ -106,29 +118,30 @@ EARS notation makes requirements clear and testable: ## Requirements ### Functional Requirements + 1. WHEN user visits homepage THE SYSTEM SHALL display recent posts 2. WHEN user clicks a post THE SYSTEM SHALL navigate to the post page 3. THE SYSTEM SHALL generate an RSS feed at /feed.xml 4. WHILE page is loading THE SYSTEM SHALL show a loading indicator ### Non-Functional Requirements + - Load time under 2 seconds on 3G - WCAG 2.1 AA accessible - Works without JavaScript enabled ``` -**EARS Keywords:** -| Keyword | Meaning | Example | -|---------|---------|---------| -| WHEN | Triggered by event | WHEN user clicks... | -| THE SYSTEM SHALL | Required behavior | ...SHALL show menu | -| WHILE | During a state | WHILE loading... | -| WHERE | Specific conditions | WHERE user is admin... | +**EARS Keywords:** | Keyword | Meaning | Example | +|---------|---------|---------| | WHEN | Triggered by event | WHEN user +clicks... | | THE SYSTEM SHALL | Required behavior | ...SHALL show menu | | +WHILE | During a state | WHILE loading... | | WHERE | Specific conditions | +WHERE user is admin... | #### Technical Stack ```markdown ## Technical Stack + - Framework: Astro 5 - Styling: Modern CSS (no framework) - Content: Markdown with frontmatter @@ -143,7 +156,8 @@ Once filled out, save the file. You're ready for step 2. ## Step 2: Run /project-planner -The `/project-planner` command reads your PROJECT_STARTER.md and generates a structured project plan. +The `/project-planner` command reads your PROJECT_STARTER.md and generates a +structured project plan. ### Run the Command @@ -156,6 +170,7 @@ In Claude Code (Terminal or VS Code), type: ### What Happens Claude will: + 1. Read your PROJECT_STARTER.md 2. Analyze the requirements 3. Break the project into phases @@ -164,6 +179,7 @@ Claude will: ### Output Location The plan is saved to: + ``` .claude/project-plan/phase_1.md ``` @@ -174,6 +190,7 @@ The plan is saved to: # Phase 1: Core Blog Setup ## Objectives + 1. Project scaffolding with Astro 2. Base layout and navigation 3. Blog post collection setup @@ -181,6 +198,7 @@ The plan is saved to: 5. Individual post pages ## Deliverables + - [ ] package.json with dependencies - [ ] src/layouts/BaseLayout.astro - [ ] src/components/Nav.astro @@ -189,6 +207,7 @@ The plan is saved to: - [ ] src/content/config.ts ## Technical Approach + - Use Astro content collections for posts - CSS custom properties for theming - Mobile-first responsive design @@ -197,6 +216,7 @@ The plan is saved to: ### Review the Plan Read through the generated plan. If something's wrong: + - Edit `.claude/project-plan/phase_1.md` directly - Or update PROJECT_STARTER.md and re-run @@ -215,6 +235,7 @@ The `/task-planner` command converts the project plan into actionable tasks. ### What Happens Claude will: + 1. Read the project plan (phase_1.md) 2. Break each objective into tasks 3. Estimate time for each task @@ -223,6 +244,7 @@ Claude will: ### Output Location Tasks are saved to: + ``` .claude/tasks/phase-1-tasks.md ``` @@ -233,7 +255,7 @@ Tasks are saved to: # Phase 1 Tasks | ID | Agent | Task | Est. | Status | -|----------|-------|--------------------------|--------|--------| +| -------- | ----- | ------------------------ | ------ | ------ | | TASK-001 | init | Project scaffolding | 5 min | ⬜ | | TASK-002 | dev | Create BaseLayout.astro | 15 min | ⬜ | | TASK-003 | dev | Create Nav component | 10 min | ⬜ | @@ -245,15 +267,16 @@ Tasks are saved to: ## TASK-001: Project Scaffolding -**Agent:** init -**Estimated Time:** 5 minutes +**Agent:** init **Estimated Time:** 5 minutes ### Instructions + 1. Initialize Astro project 2. Add TypeScript configuration 3. Create folder structure ### Acceptance Criteria + - [ ] package.json exists - [ ] tsconfig.json configured - [ ] src/ directory structure created @@ -263,19 +286,20 @@ Tasks are saved to: Each task is assigned an agent: -| Agent | Purpose | -|-------|---------| -| init | Project setup, dependencies | -| dev | Feature development, code | -| test | Testing, validation | -| docs | Documentation | -| review | Code review, refactoring | +| Agent | Purpose | +| ------ | --------------------------- | +| init | Project setup, dependencies | +| dev | Feature development, code | +| test | Testing, validation | +| docs | Documentation | +| review | Code review, refactoring | --- ## Step 4: Run /task-runner -The `/task-runner` command executes tasks one by one using the appropriate agent. +The `/task-runner` command executes tasks one by one using the appropriate +agent. ### Run the Command @@ -286,6 +310,7 @@ The `/task-runner` command executes tasks one by one using the appropriate agent ### What Happens Claude will: + 1. Find the first incomplete task 2. Load the assigned agent 3. Execute the task @@ -326,6 +351,7 @@ If a task produces broken code: ### Manual Fixes You can also: + - Edit files directly in your editor - Mark tasks complete manually in the tasks file - Skip tasks by marking them as "skipped" @@ -349,27 +375,33 @@ cd my-blog ## Project Information ### Project Name + Developer Blog ### Project Description -A technical blog for sharing programming tutorials. -Dark theme with syntax highlighting. + +A technical blog for sharing programming tutorials. Dark theme with syntax +highlighting. ### Project Type + static-site ## Goals & Objectives ### Primary Goal + Create a fast, beautiful blog with excellent SEO. ### Success Criteria + - Lighthouse 95+ on all pages - Blog posts with code syntax highlighting - RSS feed - Sitemap ### Non-Goals + - User accounts - Comments - Newsletter signup @@ -377,6 +409,7 @@ Create a fast, beautiful blog with excellent SEO. ## Requirements ### Functional + 1. WHEN user visits / THE SYSTEM SHALL show latest 5 posts 2. WHEN user visits /blog THE SYSTEM SHALL show all posts 3. WHEN user visits /blog/[slug] THE SYSTEM SHALL show post content @@ -384,6 +417,7 @@ Create a fast, beautiful blog with excellent SEO. 5. THE SYSTEM SHALL generate feed.xml ### Non-Functional + - Dark theme with purple accents - Mobile responsive - WCAG 2.1 AA compliant @@ -421,8 +455,8 @@ npm run dev ### 1. Be Specific in Requirements -❌ Bad: "Make it look good" -✅ Good: "Dark theme with #0a0a0f background, pink (#ec4899) accents" +❌ Bad: "Make it look good" ✅ Good: "Dark theme with #0a0a0f background, pink +(#ec4899) accents" ### 2. Include Non-Goals @@ -461,6 +495,7 @@ Ask Claude: "There are TypeScript errors. Can you fix them?" ```bash npm run build 2>&1 | head -50 ``` + Share the error output with Claude. --- diff --git a/docs/guides/multi-model-setup.md b/docs/guides/multi-model-setup.md new file mode 100644 index 0000000..5032e7a --- /dev/null +++ b/docs/guides/multi-model-setup.md @@ -0,0 +1,351 @@ +# Multi-Model Setup Guide + +> Use Claude, GPT-4, and Gemini together for better results + +Claude Code Sidekick supports multiple AI providers. This guide shows you how to +configure and use them together for cross-validation, cost optimization, and +specialized tasks. + +--- + +## Why Use Multiple Models? + +### 1. Cross-Validation + +Different models have different strengths. Getting a second opinion can catch +issues: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ │ +│ Claude plans architecture │ +│ ↓ │ +│ Gemini reviews the plan │ +│ ↓ │ +│ Differences are highlighted │ +│ ↓ │ +│ You make the final decision │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 2. Independent Code Review + +Have one model write code, another review it: + +``` +Claude writes code → GPT-4 reviews it → Issues caught early +``` + +### 3. Cost Optimization + +Use cheaper/faster models for simple tasks: + +| Task | Model | Why | +| ------------------ | ------------ | ------------------------ | +| Documentation | Gemini Flash | Fast, cheap, good enough | +| Architecture | Claude Opus | Complex reasoning needed | +| Code review | GPT-4o | Independent perspective | +| Simple refactoring | Gemini Flash | Cost-effective | + +--- + +## Setup + +### Step 1: Get API Keys + +You need API keys from the providers you want to use: + +| Provider | Get Key From | Env Variable | +| --------- | ------------------------------------------------------ | ------------------- | +| Anthropic | [console.anthropic.com](https://console.anthropic.com) | `ANTHROPIC_API_KEY` | +| OpenAI | [platform.openai.com](https://platform.openai.com) | `OPENAI_API_KEY` | +| Google | [aistudio.google.com](https://aistudio.google.com) | `GOOGLE_API_KEY` | + +### Step 2: Set Environment Variables + +```bash +# Add to ~/.bashrc, ~/.zshrc, or .env +export ANTHROPIC_API_KEY="sk-ant-..." +export OPENAI_API_KEY="sk-..." +export GOOGLE_API_KEY="AIza..." +``` + +### Step 3: Configure Models + +Edit `.claude/config/models.yml`: + +```yaml +providers: + anthropic: + enabled: true + openai: + enabled: true # ← Enable if you have the key + google: + enabled: true # ← Enable if you have the key +``` + +--- + +## Configuration + +### Basic: Default Models Per Task + +```yaml +# .claude/config/models.yml + +defaults: + primary: + planning: 'claude-sonnet-4-20250514' + development: 'claude-sonnet-4-20250514' + review: 'claude-sonnet-4-20250514' +``` + +### Cross-Validation: Second Opinion + +```yaml +defaults: + secondary: + planning: 'gemini-2.5-pro' # Gemini reviews Claude's plans + review: 'gpt-4o' # GPT-4 reviews Claude's code +``` + +### Per-Agent Configuration + +```yaml +agent_overrides: + planner: + primary: 'claude-sonnet-4-20250514' + secondary: 'gemini-2.5-pro' + cross_validate: true # ← Enable cross-validation + + review: + primary: 'gpt-4o' # ← Use GPT-4 as primary reviewer + secondary: 'claude-sonnet-4-20250514' + cross_validate: true +``` + +--- + +## Usage + +### Planning with Cross-Validation + +When you run `/project-planner` with cross-validation enabled: + +``` +> /project-planner + +┌──────────────────────────────────────────────────────────────────┐ +│ PROJECT PLANNER │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Primary Model: Claude Sonnet 4 │ +│ ▶ Analyzing PROJECT_STARTER.md... │ +│ ▶ Generating project plan... │ +│ ✅ Plan generated │ +│ │ +│ Cross-Validation: Gemini 2.5 Pro │ +│ ▶ Reviewing plan... │ +│ ✅ Review complete │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ 📊 CROSS-VALIDATION RESULTS │ │ +│ ├────────────────────────────────────────────────────────────┤ │ +│ │ │ │ +│ │ ✅ Agreement: 8/10 decisions │ │ +│ │ │ │ +│ │ ⚠️ Differences: │ │ +│ │ │ │ +│ │ 1. Database Choice │ │ +│ │ Claude: SQLite for simplicity │ │ +│ │ Gemini: PostgreSQL for scalability │ │ +│ │ │ │ +│ │ 2. Auth Approach │ │ +│ │ Claude: Session-based │ │ +│ │ Gemini: JWT tokens │ │ +│ │ │ │ +│ │ → Review differences and choose your approach │ │ +│ │ │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### Code Review with Second Opinion + +``` +> /review src/components/Auth.tsx + +┌──────────────────────────────────────────────────────────────────┐ +│ CODE REVIEW │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ Primary Review: Claude Sonnet 4 │ +│ ├─ Security: ✅ No issues found │ +│ ├─ Performance: ⚠️ Consider memoization │ +│ └─ Accessibility: ✅ ARIA labels present │ +│ │ +│ Secondary Review: GPT-4o │ +│ ├─ Security: ⚠️ Token stored in localStorage (XSS risk) │ +│ ├─ Performance: ✅ Looks good │ +│ └─ Accessibility: ⚠️ Missing focus management │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ Combined Issues (deduplicated): │ │ +│ │ │ │ +│ │ 1. [HIGH] Token in localStorage - XSS risk (GPT-4) │ │ +│ │ 2. [MED] Add React.memo for performance (Claude) │ │ +│ │ 3. [MED] Add focus management on modal (GPT-4) │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Best Practices + +### 1. Use Cross-Validation for Important Decisions + +Enable for: + +- Architecture planning +- Security-sensitive code +- API design +- Database schema + +Skip for: + +- Simple bug fixes +- Documentation updates +- Formatting changes + +### 2. Match Model to Task + +| Model | Best For | +| ------------- | ------------------------------------ | +| Claude Opus | Complex reasoning, nuanced decisions | +| Claude Sonnet | General development, balanced | +| GPT-4o | Fast iteration, multimodal | +| GPT-4 Turbo | Instruction following | +| o1 | Math, algorithms, complex logic | +| Gemini Flash | Speed, large contexts, docs | +| Gemini Pro | Balanced, large codebase analysis | + +### 3. Cost-Conscious Configuration + +```yaml +cost_optimization: + enabled: true + + # Cheap model for simple stuff + use_budget_model: + - 'documentation-updates' + - 'code-formatting' + - 'simple-tests' + budget_model: 'gemini-2.0-flash' + + # Premium model only when needed + use_premium_model: + - 'architecture-decisions' + - 'security-reviews' + premium_model: 'claude-opus-4-20250514' +``` + +--- + +## Commands + +### Check Available Models + +```bash +/models status +``` + +Output: + +``` +Available Models: + +✅ Anthropic (ANTHROPIC_API_KEY set) + - claude-sonnet-4-20250514 + - claude-opus-4-20250514 + +✅ OpenAI (OPENAI_API_KEY set) + - gpt-4o + - gpt-4-turbo + - o1 + +❌ Google (GOOGLE_API_KEY not set) + - gemini-2.0-flash (unavailable) + - gemini-2.5-pro (unavailable) +``` + +### Switch Primary Model + +```bash +/models set-primary planning gemini-2.5-pro +``` + +### Enable/Disable Cross-Validation + +```bash +/models cross-validate on +/models cross-validate off +``` + +### One-Time Second Opinion + +```bash +/review --cross-validate src/auth.ts +``` + +--- + +## Troubleshooting + +### "API key not found" + +Check your environment: + +```bash +echo $OPENAI_API_KEY +echo $GOOGLE_API_KEY +``` + +If empty, set them and restart your terminal. + +### "Model not available" + +The model ID may have changed. Check provider documentation for current model +IDs. + +### "Cross-validation taking too long" + +Disable for non-critical tasks: + +```yaml +cross_validation: + triggers: + planning: + always: false + on_request: true # Only when you ask +``` + +--- + +## Security Notes + +- API keys are never logged or committed +- Cross-validation sends code to multiple providers +- Review `.claude/config/models.yml` before enabling providers +- For sensitive code, limit to trusted providers only + +--- + +## Related + +- [Getting Started Tutorial](./getting-started-tutorial.md) +- [Agent Configuration](../.claude/agents.yml) +- [Model Configuration](../.claude/config/models.yml) diff --git a/docs/guides/real-world-example-ssg.md b/docs/guides/real-world-example-ssg.md index 7a10ddb..5485924 100644 --- a/docs/guides/real-world-example-ssg.md +++ b/docs/guides/real-world-example-ssg.md @@ -1,14 +1,16 @@ # Real-World Example: Building an SSG with Claude Code Sidekick -> A complete walkthrough of using Claude Code Sidekick to build a production static site generator project. +> A complete walkthrough of using Claude Code Sidekick to build a production +> static site generator project. --- ## The Project: Rise3 Recovery Platform We'll rebuild a live production site (rise3.org) as a proper SSG with: + - Blog support via markdown -- SEO meta tags and JSON-LD structured data +- SEO meta tags and JSON-LD structured data - Modern CSS (layers, custom properties, glass effects) - Content collections for easy updates @@ -64,14 +66,17 @@ Edit `PROJECT_STARTER.md` with your project specs: ## Project Information ### Project Name + Rise3 - Recovery Platform Website ### Project Description -A static site for Rise3, a blockchain-powered recovery incentives platform. -Must match the existing deployed site at rise3.org exactly, but rebuilt -as a proper SSG with blog support and content management. + +A static site for Rise3, a blockchain-powered recovery incentives platform. Must +match the existing deployed site at rise3.org exactly, but rebuilt as a proper +SSG with blog support and content management. ### Project Type + static-site --- @@ -79,13 +84,16 @@ static-site ## Goals & Objectives ### Primary Goal + Rebuild rise3.org as an Astro SSG with: + - Exact design match (dark theme, glass effects, pink/purple gradients) - Blog system using markdown content collections - SEO optimization (meta tags, JSON-LD structured data) - Modern CSS architecture (@layer, custom properties) ### Success Criteria + - Visual parity with production site - Lighthouse SEO score > 95 - Blog posts render from markdown @@ -100,12 +108,13 @@ Rebuild rise3.org as an Astro SSG with: 1. WHEN user visits /blog THE SYSTEM SHALL display list of posts 2. WHEN user visits /blog/[slug] THE SYSTEM SHALL render markdown content 3. THE SYSTEM SHALL include Open Graph and Twitter meta tags -4. THE SYSTEM SHALL include JSON-LD structured data for Organization and Articles +4. THE SYSTEM SHALL include JSON-LD structured data for Organization and + Articles ### Non-Functional Requirements - CSS: Use @layer for organization -- CSS: Use namespaced custom properties (--r3-*) +- CSS: Use namespaced custom properties (--r3-\*) - Accessibility: WCAG 2.1 AA compliant - Performance: Static HTML, minimal JavaScript ``` @@ -149,11 +158,10 @@ Rebuild rise3.org as an Astro SSG with: ### Generated Output: `.claude/project-plan/phase_1.md` -```markdown +````markdown # Phase 1: Foundation & Design System -Generated: 2026-02-21T16:00:00Z -Source: PROJECT_STARTER.md +Generated: 2026-02-21T16:00:00Z Source: PROJECT_STARTER.md ## Objectives @@ -173,6 +181,7 @@ Source: PROJECT_STARTER.md ## Technical Approach ### CSS Architecture + ```css @layer reset, base, tokens, layout, components, utilities; @@ -185,7 +194,9 @@ Source: PROJECT_STARTER.md } } ``` -``` +```` + +```` --- @@ -237,7 +248,7 @@ Source: PROJECT_STARTER.md 📁 Created tasks/phase-1-tasks.md ✅ 5 tasks generated -``` +```` --- @@ -282,8 +293,8 @@ export default defineConfig({ site: 'https://rise3.org', output: 'static', adapter: cloudflare({ - platformProxy: { enabled: true } - }) + platformProxy: { enabled: true }, + }), }); ``` @@ -454,16 +465,16 @@ export const collections = { posts }; ```markdown --- -title: "Welcome to Rise3" -description: "Introducing our blockchain-powered recovery platform" +title: 'Welcome to Rise3' +description: 'Introducing our blockchain-powered recovery platform' publishedAt: 2024-02-21 -tags: ["announcement", "recovery"] +tags: ['announcement', 'recovery'] --- # Welcome to Rise3 -We're excited to introduce Rise3, a revolutionary platform -designed to support and reward your recovery journey. +We're excited to introduce Rise3, a revolutionary platform designed to support +and reward your recovery journey. ## Why We Built Rise3 @@ -484,7 +495,7 @@ const posts = await getCollection('posts');

Rise3 Blog

- +
{posts.map(post => (
@@ -508,13 +519,13 @@ const posts = await getCollection('posts'); # Build static site $ pnpm build - prerendering static routes + prerendering static routes ▶ src/pages/blog/[slug].astro - └─ /blog/welcome/index.html (+7ms) + └─ /blog/welcome/index.html (+7ms) ▶ src/pages/blog/index.astro - └─ /blog/index.html (+5ms) + └─ /blog/index.html (+5ms) ▶ src/pages/index.astro - └─ /index.html (+12ms) + └─ /index.html (+12ms) ✓ Completed in 44ms. [build] Complete! @@ -530,14 +541,14 @@ $ pnpm deploy ## Key Sidekick Features Used -| Feature | How It Helped | -|---------|---------------| +| Feature | How It Helped | +| ---------------------- | ------------------------------------------- | | **PROJECT_STARTER.md** | Defined exact requirements in EARS notation | -| **/project-planner** | Analyzed requirements, created phased plan | -| **/task-planner** | Generated specific implementation tasks | -| **/task-runner** | Executed tasks with specialized agents | -| **CSS Rules** | Enforced modern CSS standards | -| **Hooks** | Auto-formatted on save, validated on commit | +| **/project-planner** | Analyzed requirements, created phased plan | +| **/task-planner** | Generated specific implementation tasks | +| **/task-runner** | Executed tasks with specialized agents | +| **CSS Rules** | Enforced modern CSS standards | +| **Hooks** | Auto-formatted on save, validated on commit | --- @@ -576,14 +587,16 @@ rise3-webapp/ ## Summary -Claude Code Sidekick transformed this from a vague request ("rebuild as SSG") into: +Claude Code Sidekick transformed this from a vague request ("rebuild as SSG") +into: 1. **Structured requirements** via PROJECT_STARTER.md 2. **Phased plan** via /project-planner 3. **Actionable tasks** via /task-planner 4. **Executed implementation** via /task-runner -The result: A production-ready static site with blog support, SEO optimization, and modern CSS architecture—built systematically instead of ad-hoc. +The result: A production-ready static site with blog support, SEO optimization, +and modern CSS architecture—built systematically instead of ad-hoc. --- diff --git a/examples/crypto-dashboard/.claude/project-plan/phase_1.md b/examples/crypto-dashboard/.claude/project-plan/phase_1.md index 14c53ff..d6e7cd3 100644 --- a/examples/crypto-dashboard/.claude/project-plan/phase_1.md +++ b/examples/crypto-dashboard/.claude/project-plan/phase_1.md @@ -1,16 +1,19 @@ # Phase 1: Core Web3 Dashboard -Generated: 2024-02-22T12:00:00Z -Source: PROJECT_STARTER.md +Generated: 2024-02-22T12:00:00Z Source: PROJECT_STARTER.md --- ## Project Summary ### Overview -Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, signature verification, and elaborate dashboard UI. Dark neon aesthetic inspired by GigaBrain and modern DeFi platforms. + +Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, +signature verification, and elaborate dashboard UI. Dark neon aesthetic inspired +by GigaBrain and modern DeFi platforms. ### Goals + - Privy wallet connection - Signature verification flow - Elaborate dashboard post-auth @@ -22,6 +25,7 @@ Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, ## Analysis ### Complexity Assessment + - **Overall:** Medium - **Challenges:** - Privy integration with signature flow @@ -29,6 +33,7 @@ Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, - Neon/glass CSS effects ### Dependencies + - **External:** Privy SDK, Google Fonts - **Internal:** Auth state flows through all components @@ -37,6 +42,7 @@ Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, ## Phase 1 Scope ### Objectives + 1. Project setup (Vite + React + TypeScript) 2. Privy provider configuration 3. Global CSS with neon dark theme @@ -46,6 +52,7 @@ Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, 7. Demo mode for testing ### Deliverables + - [ ] `package.json` with dependencies - [ ] `vite.config.ts` + TypeScript config - [ ] `src/styles/globals.css` - Complete theme @@ -92,11 +99,9 @@ Nexus Protocol Dashboard - A Web3 landing page with Privy wallet authentication, ### Color System ```css ---color-bg: #0a0a0f /* Deep dark */ ---color-cyan: #00f5ff /* Primary accent */ ---color-purple: #a855f7 /* Secondary */ ---color-pink: #ec4899 /* Tertiary */ ---gradient-hero: linear-gradient(135deg, cyan → purple → pink) +--color-bg: #0a0a0f /* Deep dark */ --color-cyan: #00f5ff /* Primary accent */ + --color-purple: #a855f7 /* Secondary */ --color-pink: #ec4899 /* Tertiary */ + --gradient-hero: linear-gradient(135deg, cyan → purple → pink); ``` --- diff --git a/examples/crypto-dashboard/.claude/tasks/phase-1-tasks.md b/examples/crypto-dashboard/.claude/tasks/phase-1-tasks.md index 4231d83..e000591 100644 --- a/examples/crypto-dashboard/.claude/tasks/phase-1-tasks.md +++ b/examples/crypto-dashboard/.claude/tasks/phase-1-tasks.md @@ -1,24 +1,23 @@ # Phase 1 Tasks -Generated: 2024-02-22T12:15:00Z -Source: .claude/project-plan/phase_1.md +Generated: 2024-02-22T12:15:00Z Source: .claude/project-plan/phase_1.md --- ## Task Overview -| ID | Agent | Task | Est. Time | Status | -|----------|-------|-------------------------|-----------|--------| -| TASK-001 | init | Project Setup | 10 min | ✅ | -| TASK-002 | dev | CSS Theme | 45 min | ✅ | -| TASK-003 | dev | Privy Integration | 20 min | ✅ | -| TASK-004 | dev | Navbar Component | 15 min | ✅ | -| TASK-005 | dev | Hero Component | 20 min | ✅ | -| TASK-006 | dev | Signature Modal | 25 min | ✅ | -| TASK-007 | dev | Dashboard Layout | 20 min | ✅ | -| TASK-008 | dev | Stats Cards | 15 min | ✅ | -| TASK-009 | dev | Token List | 15 min | ✅ | -| TASK-010 | dev | Activity Feed | 15 min | ✅ | +| ID | Agent | Task | Est. Time | Status | +| -------- | ----- | ----------------- | --------- | ------ | +| TASK-001 | init | Project Setup | 10 min | ✅ | +| TASK-002 | dev | CSS Theme | 45 min | ✅ | +| TASK-003 | dev | Privy Integration | 20 min | ✅ | +| TASK-004 | dev | Navbar Component | 15 min | ✅ | +| TASK-005 | dev | Hero Component | 20 min | ✅ | +| TASK-006 | dev | Signature Modal | 25 min | ✅ | +| TASK-007 | dev | Dashboard Layout | 20 min | ✅ | +| TASK-008 | dev | Stats Cards | 15 min | ✅ | +| TASK-009 | dev | Token List | 15 min | ✅ | +| TASK-010 | dev | Activity Feed | 15 min | ✅ | **Total Time:** ~3.5 hours @@ -29,6 +28,7 @@ Source: .claude/project-plan/phase_1.md **Status:** ✅ Complete ### Files Created + - `package.json` - React, Vite, Privy dependencies - `vite.config.ts` - Vite configuration - `tsconfig.json` - TypeScript strict mode @@ -42,7 +42,9 @@ Source: .claude/project-plan/phase_1.md **Status:** ✅ Complete ### Implementation + 13,000+ lines of modern CSS: + - CSS custom properties for colors, spacing, typography - Glassmorphism `.glass` class with backdrop-filter - Glow button `.btn--glow` with animated pseudo-element @@ -52,11 +54,10 @@ Source: .claude/project-plan/phase_1.md - Modal overlay with blur ### Key Tokens + ```css ---color-cyan: #00f5ff ---color-purple: #a855f7 ---color-pink: #ec4899 ---gradient-hero: linear-gradient(135deg, cyan, purple, pink) +--color-cyan: #00f5ff --color-purple: #a855f7 --color-pink: #ec4899 + --gradient-hero: linear-gradient(135deg, cyan, purple, pink); ``` --- @@ -66,6 +67,7 @@ Source: .claude/project-plan/phase_1.md **Status:** ✅ Complete ### Implementation + ```tsx Step-by-step walkthrough of building a Web3 dApp with Claude Code Sidekick -This example shows how to build a crypto landing page with wallet authentication using the Sidekick workflow. +This example shows how to build a crypto landing page with wallet authentication +using the Sidekick workflow. --- @@ -68,6 +69,7 @@ Open [PROJECT_STARTER.md](./PROJECT_STARTER.md) to see the requirements. See [.claude/project-plan/phase_1.md](./.claude/project-plan/phase_1.md) The plan identifies: + - Authentication flow (connect → sign → dashboard) - Component hierarchy - CSS architecture decisions @@ -88,15 +90,15 @@ See [.claude/tasks/phase-1-tasks.md](./.claude/tasks/phase-1-tasks.md) Tasks are broken down by component: -| ID | Agent | Task | Status | -|----|-------|------|--------| -| TASK-001 | init | Project setup | ✅ | -| TASK-002 | dev | CSS theme | ✅ | -| TASK-003 | dev | Privy integration | ✅ | -| TASK-004 | dev | Navbar | ✅ | -| TASK-005 | dev | Hero section | ✅ | -| TASK-006 | dev | Signature modal | ✅ | -| TASK-007 | dev | Dashboard | ✅ | +| ID | Agent | Task | Status | +| -------- | ----- | ----------------- | ------ | +| TASK-001 | init | Project setup | ✅ | +| TASK-002 | dev | CSS theme | ✅ | +| TASK-003 | dev | Privy integration | ✅ | +| TASK-004 | dev | Navbar | ✅ | +| TASK-005 | dev | Hero section | ✅ | +| TASK-006 | dev | Signature modal | ✅ | +| TASK-007 | dev | Dashboard | ✅ | --- @@ -168,6 +170,7 @@ npm run dev ``` Demo mode simulates: + - Wallet connection - Signature flow - Full dashboard @@ -234,7 +237,7 @@ const handleSign = async () => { const message = `Welcome to Nexus Protocol! Timestamp: ${Date.now()} Nonce: ${crypto.randomUUID()}`; - + // In real app: await signMessage(message) // Then verify signature onSuccess(); @@ -375,6 +378,7 @@ const tokens = [ ### Real Blockchain Data Replace mock data with: + - Alchemy/Infura for balances - CoinGecko for prices - The Graph for history @@ -392,6 +396,7 @@ Replace mock data with: ## Next Steps -- Read the [Getting Started Tutorial](../../docs/guides/getting-started-tutorial.md) +- Read the + [Getting Started Tutorial](../../docs/guides/getting-started-tutorial.md) - Try the [SSG Starter Example](../ssg-starter/) - Learn about [Available Agents](../../.claude/agents/) diff --git a/examples/crypto-dashboard/index.html b/examples/crypto-dashboard/index.html index 0e50f1d..42d957d 100644 --- a/examples/crypto-dashboard/index.html +++ b/examples/crypto-dashboard/index.html @@ -1,4 +1,4 @@ - + @@ -6,9 +6,12 @@ Nexus Protocol | Dashboard - - - + + +
diff --git a/examples/crypto-dashboard/src/App.tsx b/examples/crypto-dashboard/src/App.tsx index c1ce784..1f5a8f7 100644 --- a/examples/crypto-dashboard/src/App.tsx +++ b/examples/crypto-dashboard/src/App.tsx @@ -23,16 +23,13 @@ function AppContent() { return ( <> - + {!authenticated ? ( ) : needsSignature ? ( <> - setSignatureVerified(true)} - onClose={() => {}} - /> + setSignatureVerified(true)} onClose={() => {}} /> ) : ( @@ -76,13 +73,16 @@ function DemoApp() { return ( <> - setConnected(true)} - onDisconnect={() => { setConnected(false); setVerified(false); }} + onDisconnect={() => { + setConnected(false); + setVerified(false); + }} /> - + {!connected ? ( setConnected(true)} /> ) : !verified ? ( diff --git a/examples/crypto-dashboard/src/components/ActivityFeed.tsx b/examples/crypto-dashboard/src/components/ActivityFeed.tsx index 6c91b30..ed4faf1 100644 --- a/examples/crypto-dashboard/src/components/ActivityFeed.tsx +++ b/examples/crypto-dashboard/src/components/ActivityFeed.tsx @@ -1,33 +1,33 @@ const activities = [ - { + { type: 'stake', title: 'Staked 1,000 NEXUS', time: '2 hours ago', - icon: '🔒' + icon: '🔒', }, - { + { type: 'claim', title: 'Claimed 42.5 NEXUS rewards', time: '5 hours ago', - icon: '🎁' + icon: '🎁', }, - { + { type: 'swap', title: 'Swapped 0.5 ETH → 2,100 NEXUS', time: '1 day ago', - icon: '🔄' + icon: '🔄', }, - { + { type: 'vote', title: 'Voted on Proposal #47', time: '2 days ago', - icon: '🗳️' + icon: '🗳️', }, - { + { type: 'stake', title: 'Staked 5,000 NEXUS', time: '3 days ago', - icon: '🔒' + icon: '🔒', }, ]; diff --git a/examples/crypto-dashboard/src/components/Dashboard.tsx b/examples/crypto-dashboard/src/components/Dashboard.tsx index d946009..0b53066 100644 --- a/examples/crypto-dashboard/src/components/Dashboard.tsx +++ b/examples/crypto-dashboard/src/components/Dashboard.tsx @@ -53,13 +53,13 @@ export function Dashboard() { {/* Chart Placeholder */}

📈 Performance (30d)

-
diff --git a/examples/crypto-dashboard/src/components/Hero.tsx b/examples/crypto-dashboard/src/components/Hero.tsx index d2e1cda..6927bdb 100644 --- a/examples/crypto-dashboard/src/components/Hero.tsx +++ b/examples/crypto-dashboard/src/components/Hero.tsx @@ -12,21 +12,19 @@ export function Hero({ demoMode, onConnect }: HeroProps) { return (
- +
- - ⚡ Powered by Web3 - - + ⚡ Powered by Web3 +

NEXUS
PROTOCOL

- +

- The Future of Decentralized Intelligence. Stake, earn, and govern - the next generation of AI-powered DeFi infrastructure. + The Future of Decentralized Intelligence. Stake, earn, and govern the next generation of + AI-powered DeFi infrastructure.

+ + - -
diff --git a/examples/crypto-dashboard/src/styles/globals.css b/examples/crypto-dashboard/src/styles/globals.css index f32bfea..0426682 100644 --- a/examples/crypto-dashboard/src/styles/globals.css +++ b/examples/crypto-dashboard/src/styles/globals.css @@ -8,7 +8,9 @@ /* ============================================ Reset & Base ============================================ */ -*, *::before, *::after { +*, +*::before, +*::after { box-sizing: border-box; margin: 0; padding: 0; @@ -17,42 +19,48 @@ :root { /* Background */ --color-bg: #0a0a0f; - --color-bg-gradient: radial-gradient(ellipse at 50% 0%, rgba(0, 245, 255, 0.05) 0%, transparent 50%), - radial-gradient(ellipse at 80% 100%, rgba(168, 85, 247, 0.05) 0%, transparent 50%); + --color-bg-gradient: + radial-gradient(ellipse at 50% 0%, rgba(0, 245, 255, 0.05) 0%, transparent 50%), + radial-gradient(ellipse at 80% 100%, rgba(168, 85, 247, 0.05) 0%, transparent 50%); --color-surface: #12121a; --color-surface-elevated: #1a1a24; --color-card: rgba(18, 18, 26, 0.8); --color-border: rgba(255, 255, 255, 0.06); - + /* Accent Colors */ --color-cyan: #00f5ff; --color-purple: #a855f7; --color-pink: #ec4899; --color-blue: #3b82f6; - + /* Status */ --color-green: #10b981; --color-red: #ef4444; --color-yellow: #f59e0b; - + /* Text */ --color-text: #ffffff; --color-text-secondary: #a1a1aa; --color-text-muted: #52525b; - + /* Gradients */ - --gradient-hero: linear-gradient(135deg, var(--color-cyan) 0%, var(--color-purple) 50%, var(--color-pink) 100%); + --gradient-hero: linear-gradient( + 135deg, + var(--color-cyan) 0%, + var(--color-purple) 50%, + var(--color-pink) 100% + ); --gradient-card: linear-gradient(135deg, rgba(0, 245, 255, 0.1) 0%, rgba(168, 85, 247, 0.1) 100%); - + /* Glows */ --glow-cyan: 0 0 30px rgba(0, 245, 255, 0.4); --glow-purple: 0 0 30px rgba(168, 85, 247, 0.4); --glow-pink: 0 0 30px rgba(236, 72, 153, 0.4); - + /* Typography */ --font-sans: 'Inter', system-ui, -apple-system, sans-serif; --font-mono: 'JetBrains Mono', monospace; - + /* Spacing */ --space-xs: 0.25rem; --space-sm: 0.5rem; @@ -61,7 +69,7 @@ --space-xl: 2rem; --space-2xl: 3rem; --space-3xl: 4rem; - + /* Border Radius */ --radius-sm: 0.375rem; --radius-md: 0.75rem; @@ -89,16 +97,29 @@ body { /* ============================================ Typography ============================================ */ -h1, h2, h3, h4, h5, h6 { +h1, +h2, +h3, +h4, +h5, +h6 { font-weight: 700; line-height: 1.2; letter-spacing: -0.02em; } -h1 { font-size: 3rem; } -h2 { font-size: 2rem; } -h3 { font-size: 1.5rem; } -h4 { font-size: 1.25rem; } +h1 { + font-size: 3rem; +} +h2 { + font-size: 2rem; +} +h3 { + font-size: 1.5rem; +} +h4 { + font-size: 1.25rem; +} .text-gradient { background: var(--gradient-hero); @@ -119,9 +140,15 @@ h4 { font-size: 1.25rem; } color: var(--color-text-secondary); } -.text-green { color: var(--color-green); } -.text-red { color: var(--color-red); } -.text-cyan { color: var(--color-cyan); } +.text-green { + color: var(--color-green); +} +.text-red { + color: var(--color-red); +} +.text-cyan { + color: var(--color-cyan); +} /* ============================================ Layout @@ -167,12 +194,20 @@ h4 { font-size: 1.25rem; } } @media (max-width: 1024px) { - .grid-4 { grid-template-columns: repeat(2, 1fr); } - .grid-3 { grid-template-columns: repeat(2, 1fr); } + .grid-4 { + grid-template-columns: repeat(2, 1fr); + } + .grid-3 { + grid-template-columns: repeat(2, 1fr); + } } @media (max-width: 640px) { - .grid-4, .grid-3, .grid-2 { grid-template-columns: 1fr; } + .grid-4, + .grid-3, + .grid-2 { + grid-template-columns: 1fr; + } } /* ============================================ @@ -348,8 +383,13 @@ h4 { font-size: 1.25rem; } } @keyframes pulse { - 0%, 100% { opacity: 1; } - 50% { opacity: 0.5; } + 0%, + 100% { + opacity: 1; + } + 50% { + opacity: 0.5; + } } /* ============================================ @@ -382,8 +422,15 @@ h4 { font-size: 1.25rem; } } @keyframes glow-pulse { - 0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 0.15; } - 50% { transform: translate(-50%, -50%) scale(1.1); opacity: 0.2; } + 0%, + 100% { + transform: translate(-50%, -50%) scale(1); + opacity: 0.15; + } + 50% { + transform: translate(-50%, -50%) scale(1.1); + opacity: 0.2; + } } .hero__tag { @@ -467,11 +514,15 @@ h4 { font-size: 1.25rem; } } @media (max-width: 1024px) { - .stats-row { grid-template-columns: repeat(2, 1fr); } + .stats-row { + grid-template-columns: repeat(2, 1fr); + } } @media (max-width: 640px) { - .stats-row { grid-template-columns: 1fr; } + .stats-row { + grid-template-columns: 1fr; + } } .stat-card { @@ -497,8 +548,12 @@ h4 { font-size: 1.25rem; } gap: var(--space-xs); } -.stat-card__change.positive { color: var(--color-green); } -.stat-card__change.negative { color: var(--color-red); } +.stat-card__change.positive { + color: var(--color-green); +} +.stat-card__change.negative { + color: var(--color-red); +} /* Token List */ .token-list { @@ -666,16 +721,38 @@ h4 { font-size: 1.25rem; } /* ============================================ Utilities ============================================ */ -.mt-sm { margin-top: var(--space-sm); } -.mt-md { margin-top: var(--space-md); } -.mt-lg { margin-top: var(--space-lg); } -.mt-xl { margin-top: var(--space-xl); } - -.mb-sm { margin-bottom: var(--space-sm); } -.mb-md { margin-bottom: var(--space-md); } -.mb-lg { margin-bottom: var(--space-lg); } -.mb-xl { margin-bottom: var(--space-xl); } - -.gap-sm { gap: var(--space-sm); } -.gap-md { gap: var(--space-md); } -.gap-lg { gap: var(--space-lg); } +.mt-sm { + margin-top: var(--space-sm); +} +.mt-md { + margin-top: var(--space-md); +} +.mt-lg { + margin-top: var(--space-lg); +} +.mt-xl { + margin-top: var(--space-xl); +} + +.mb-sm { + margin-bottom: var(--space-sm); +} +.mb-md { + margin-bottom: var(--space-md); +} +.mb-lg { + margin-bottom: var(--space-lg); +} +.mb-xl { + margin-bottom: var(--space-xl); +} + +.gap-sm { + gap: var(--space-sm); +} +.gap-md { + gap: var(--space-md); +} +.gap-lg { + gap: var(--space-lg); +} diff --git a/examples/ssg-starter/.claude/project-plan/phase_1.md b/examples/ssg-starter/.claude/project-plan/phase_1.md index b40a766..15f7473 100644 --- a/examples/ssg-starter/.claude/project-plan/phase_1.md +++ b/examples/ssg-starter/.claude/project-plan/phase_1.md @@ -1,16 +1,18 @@ # Phase 1: Foundation & Core Components -Generated: 2024-02-21T10:00:00Z -Source: PROJECT_STARTER.md +Generated: 2024-02-21T10:00:00Z Source: PROJECT_STARTER.md --- ## Project Summary ### Overview -SSG Starter is a production-ready static site template with blog support, SEO optimization, and modern CSS architecture. Built using Astro with static output. + +SSG Starter is a production-ready static site template with blog support, SEO +optimization, and modern CSS architecture. Built using Astro with static output. ### Goals + - Create reusable SSG template - Blog system with markdown content collections - Comprehensive SEO (meta tags, JSON-LD) @@ -18,6 +20,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op - Dark theme with glass morphism effects ### Success Criteria + - Lighthouse SEO score > 95 - Lighthouse Accessibility score > 95 - Blog posts render from markdown @@ -28,6 +31,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op ## Analysis ### Complexity Assessment + - **Overall Complexity:** Medium - **Key Challenges:** - CSS architecture with @layer requires careful organization @@ -35,10 +39,12 @@ SSG Starter is a production-ready static site template with blog support, SEO op - JSON-LD schemas must be valid ### Dependencies + - **External:** Astro 5, Google Fonts - **Internal:** SEO → BaseLayout → Pages ### Risks + - Browser support for backdrop-filter (mitigated with fallbacks) - Content collection type generation (handled by Astro) @@ -47,6 +53,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op ## Phase 1 Scope ### Objectives + 1. Set up Astro project with static output 2. Create CSS design system with @layer 3. Build SEO component with meta tags @@ -56,6 +63,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op 7. Create blog listing and post pages ### Deliverables + - [ ] `astro.config.mjs` - Static output configuration - [ ] `public/styles.css` - Complete CSS design system - [ ] `src/components/SEO.astro` - Meta tags component @@ -69,6 +77,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op - [ ] `src/pages/blog/[slug].astro` - Post pages ### Out of Scope + - Server-side functionality - Database integration - Authentication @@ -115,6 +124,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op ``` ### Technology Stack + - Astro 5 (static output) - Modern CSS (no preprocessors) - Markdown with frontmatter @@ -138,6 +148,7 @@ SSG Starter is a production-ready static site template with blog support, SEO op ## Next Steps After Phase 1 completion: + 1. Run Lighthouse audits 2. Test on multiple browsers 3. Add more blog posts diff --git a/examples/ssg-starter/.claude/tasks/phase-1-tasks.md b/examples/ssg-starter/.claude/tasks/phase-1-tasks.md index 14f6445..c484aed 100644 --- a/examples/ssg-starter/.claude/tasks/phase-1-tasks.md +++ b/examples/ssg-starter/.claude/tasks/phase-1-tasks.md @@ -1,27 +1,25 @@ # Phase 1 Tasks -Generated: 2024-02-21T10:15:00Z -Source: .claude/project-plan/phase_1.md +Generated: 2024-02-21T10:15:00Z Source: .claude/project-plan/phase_1.md --- ## Task Overview -| ID | Agent | Task | Est. Time | Status | -|----------|-------|-------------------------|-----------|--------| -| TASK-001 | init | Astro Configuration | 10 min | ✅ | -| TASK-002 | dev | CSS Design System | 30 min | ✅ | -| TASK-003 | dev | SEO Component | 20 min | ✅ | -| TASK-004 | dev | JSON-LD Component | 20 min | ✅ | -| TASK-005 | dev | Navigation Component | 15 min | ✅ | -| TASK-006 | dev | Footer Component | 10 min | ✅ | -| TASK-007 | dev | Base Layout | 15 min | ✅ | -| TASK-008 | dev | Content Collections | 15 min | ✅ | -| TASK-009 | dev | Homepage | 20 min | ✅ | -| TASK-010 | dev | Blog System | 30 min | ✅ | - -**Total Estimated Time:** ~3 hours -**Actual Time:** ~2.5 hours +| ID | Agent | Task | Est. Time | Status | +| -------- | ----- | -------------------- | --------- | ------ | +| TASK-001 | init | Astro Configuration | 10 min | ✅ | +| TASK-002 | dev | CSS Design System | 30 min | ✅ | +| TASK-003 | dev | SEO Component | 20 min | ✅ | +| TASK-004 | dev | JSON-LD Component | 20 min | ✅ | +| TASK-005 | dev | Navigation Component | 15 min | ✅ | +| TASK-006 | dev | Footer Component | 10 min | ✅ | +| TASK-007 | dev | Base Layout | 15 min | ✅ | +| TASK-008 | dev | Content Collections | 15 min | ✅ | +| TASK-009 | dev | Homepage | 20 min | ✅ | +| TASK-010 | dev | Blog System | 30 min | ✅ | + +**Total Estimated Time:** ~3 hours **Actual Time:** ~2.5 hours --- @@ -32,21 +30,24 @@ Source: .claude/project-plan/phase_1.md **Status:** ✅ Complete ### Description + Configure Astro for static site generation. ### Implementation + ```javascript // astro.config.mjs export default defineConfig({ site: 'https://example.com', output: 'static', build: { - inlineStylesheets: 'auto' - } + inlineStylesheets: 'auto', + }, }); ``` ### Files Created + - `astro.config.mjs` - `package.json` @@ -59,9 +60,11 @@ export default defineConfig({ **Status:** ✅ Complete ### Description + Create comprehensive CSS with @layer architecture. ### Implementation + ```css @layer reset, base, tokens, layout, components, utilities; @@ -77,9 +80,11 @@ Create comprehensive CSS with @layer architecture. ``` ### Files Created + - `public/styles.css` (400+ lines) ### Notes + - Used fluid typography with `clamp()` - Glass effect uses `backdrop-filter: blur(12px)` - Dark theme with pink/purple accent gradient @@ -93,9 +98,11 @@ Create comprehensive CSS with @layer architecture. **Status:** ✅ Complete ### Description + Create reusable SEO component with comprehensive meta tags. ### Implementation + ```astro --- interface Props { @@ -115,9 +122,11 @@ interface Props { ``` ### Files Created + - `src/components/SEO.astro` ### Meta Tags Included + - Primary (title, description, keywords) - Open Graph (og:title, og:image, etc.) - Twitter Cards @@ -134,9 +143,11 @@ interface Props { **Status:** ✅ Complete ### Description + Create JSON-LD structured data component. ### Implementation + ```astro --- const schema = { @@ -153,9 +164,11 @@ const schema = { ``` ### Files Created + - `src/components/JsonLD.astro` ### Schemas Included + - Organization - WebSite (with SearchAction) - Article (for blog posts) @@ -169,12 +182,15 @@ const schema = { **Status:** ✅ Complete ### Description + Create fixed navigation with glass effect on scroll. ### Files Created + - `src/components/Nav.astro` ### Features + - Fixed position - Glass effect on scroll (JavaScript) - Mobile-responsive @@ -188,6 +204,7 @@ Create fixed navigation with glass effect on scroll. **Status:** ✅ Complete ### Files Created + - `src/components/Footer.astro` --- @@ -199,12 +216,15 @@ Create fixed navigation with glass effect on scroll. **Status:** ✅ Complete ### Description + Create main layout that combines all components. ### Files Created + - `src/layouts/BaseLayout.astro` ### Structure + ``` BaseLayout ├── @@ -225,9 +245,11 @@ BaseLayout **Status:** ✅ Complete ### Description + Configure Astro content collections for blog posts. ### Implementation + ```typescript const posts = defineCollection({ schema: z.object({ @@ -240,6 +262,7 @@ const posts = defineCollection({ ``` ### Files Created + - `src/content/config.ts` - `src/content/posts/hello-world.md` - `src/content/posts/modern-css-architecture.md` @@ -253,12 +276,15 @@ const posts = defineCollection({ **Status:** ✅ Complete ### Description + Create homepage with hero and features sections. ### Files Created + - `src/pages/index.astro` ### Sections + - Hero (title, subtitle, CTAs) - Features (6 glass cards) - CTA section @@ -272,13 +298,16 @@ Create homepage with hero and features sections. **Status:** ✅ Complete ### Description + Create blog listing and individual post pages. ### Files Created + - `src/pages/blog/index.astro` - `src/pages/blog/[slug].astro` ### Features + - Sorted by date (newest first) - Draft support - Dynamic routes for posts @@ -290,7 +319,7 @@ Create blog listing and individual post pages. ``` ═══════════════════════════════════════════════════════════════════ - ⛔ PHASE 1 COMPLETE + ⛔ PHASE 1 COMPLETE ═══════════════════════════════════════════════════════════════════ Summary: diff --git a/examples/ssg-starter/CLAUDE.md b/examples/ssg-starter/CLAUDE.md index 8c78078..91bed52 100644 --- a/examples/ssg-starter/CLAUDE.md +++ b/examples/ssg-starter/CLAUDE.md @@ -4,9 +4,11 @@ ## Project Overview -**SSG Starter** is a production-ready static site template built with Astro. It demonstrates the Claude Code Sidekick workflow for building modern web projects. +**SSG Starter** is a production-ready static site template built with Astro. It +demonstrates the Claude Code Sidekick workflow for building modern web projects. ### Tech Stack + - **Framework:** Astro 5 (static output) - **Styling:** Modern CSS (@layer, custom properties) - **Content:** Markdown with frontmatter @@ -64,14 +66,14 @@ All design values are CSS custom properties: ### Key Classes -| Class | Purpose | -|-------|---------| -| `.glass` | Glass morphism card effect | -| `.container` | Max-width centered container | -| `.section` | Vertical padding for sections | -| `.grid` | CSS grid with responsive columns | -| `.btn` | Button base styles | -| `.prose` | Blog post content styling | +| Class | Purpose | +| ------------ | -------------------------------- | +| `.glass` | Glass morphism card effect | +| `.container` | Max-width centered container | +| `.section` | Vertical padding for sections | +| `.grid` | CSS grid with responsive columns | +| `.btn` | Button base styles | +| `.prose` | Blog post content styling | ## Content Collections @@ -94,10 +96,10 @@ Create `src/content/posts/my-post.md`: ```markdown --- -title: "My Post Title" -description: "Brief description" +title: 'My Post Title' +description: 'Brief description' publishedAt: 2024-02-21 -tags: ["tag1", "tag2"] +tags: ['tag1', 'tag2'] --- Content here... @@ -116,16 +118,19 @@ Every page includes: ## Coding Standards ### HTML + - Semantic elements (`
`, `
`, `