Claude Code — Team Onboarding Kit

Get your team from zero to productive with Claude Code in under 30 minutes.

This repository is a pre-configured starter kit packed with agents, skills, slash commands, and MCP integrations — ready to go for the following tech stack:

Clone it, install Claude Code, and start building.

Table of Contents

• Claude Code — Team Onboarding Kit
  • Table of Contents
  • What is Claude Code?
  • 1. Prerequisites
  • 2. Clone This Repo
  • 3. Set Up Your Editor (Install VS Code)
  • 4. Install Claude Code
    • Native Binary (Recommended)
  • 5. First-time Using Claude Code
  • 6. Install Claude-Mem (Persistent Memory) (Optional)
    • What Claude-Mem Does
    • 6a. Set Up Team Memory Sharing (Optional)
  • 7. Enable Voice Mode (Optional)
    • One-Prompt Setup
    • Manual Setup
      • Prerequisites
      • Quick Install
      • What Each Step Does
      • OpenAI API Configuration
      • Usage
      • How It Works
      • Auto-Approve Voice Tools
      • Platform-Specific Dependencies
      • Troubleshooting
  • 8. Try It Out — Your First 5 Minutes
    • Ask about the project
    • Scaffold something
    • Use a sub-agent
    • Pull live docs with MCP
    • Check what's loaded
    • A note on permissions
  • 9. Understanding Claude Code Components
    • How They Fit Together
    • Decision Matrix - When to Use What
    • CLAUDE.md (Project Context)
    • Slash Commands — Reusable Prompt Shortcuts
    • Agents (Subagents) — Specialist AI Personas
    • Subagent-Driven Development (SDD) — Plan-to-PR Pipeline
    • Skills — Auto-Activated Knowledge
    • MCP Servers — External Tool Integrations
    • settings.json Configuration
    • Hooks — Automated Guardrails
    • Lessons Log — Self-Improvement Loop
    • Model Selection & Cost Awareness
  • 10. Cheaper Alternative: MiniMax M2.5
    • Why Choose MiniMax M2.5?
    • Overview of MiniMax M2.5 for Coding
    • Step-by-Step Configuration
  • 11. Multiple Sub Agents
  • 12. Agent Teams — Coordinated Multi-Agent Collaboration
    • How to Enable
  • 13. Claude Code Desktop — GUI with Live Preview
    • What It Can Do
    • Testing Frontend SPAs (Angular, React)
    • Testing Backend REST APIs (Spring Boot, NestJS)
    • Testing Flutter Apps (Canvas Limitation)
    • CI/CD & PR Workflow
    • Remote SSH Debugging
    • Desktop vs CLI — When to Use What
    • Quick Start
  • 14. What Gets Sent to the LLM?
    • Context Window Anatomy
    • What Each Layer Contains
    • Key Takeaways
  • 15. What's in This Repo
    • MCP Servers (.mcp.json)
    • Browser Automation
      • Sample Prompts
  • 16. iOS App Store Release Pipeline
  • 17. Android Google Play Release Pipeline
  • 16. Hands-On Exercises
    • Exercise 1: Scaffold a Flutter Fitness App
    • Exercise 2: Build a Weather REST API (Java)
    • Exercise 3: Build a Todo API (NestJS)
    • Exercise 4: Build an Analytics API (Python)
    • Exercise 5: Design a Full-Stack E-Commerce System
    • Exercise 6: Pull Live Docs with Context7 (MCP)
    • Exercise 7: Design & Review Architecture
    • Exercise 8: Build an AI Agent Service (Agentic AI)
    • Exercise 9: Domain-Driven Design with DDD Architect
    • Exercise 10: Add a Feature End-to-End
    • Exercise 11: Build an A2UI Renderer (Agent-to-User Interface)
    • Exercise 12: Build a Google ADK Agent Service
    • What's Next?
  • 17. Development Workflow — Putting It All Together
    • How Components Interact
    • Phase 1: Design & Architecture
    • Phase 2: Scaffold & Bootstrap
    • Phase 3: Feature Development
    • Phase 4: Review & Enforce Quality
    • Phase 5: Evolve Your Setup
  • 17a. AI-DLC — Full Development Lifecycle Workflow (Optional)
    • How It Works
    • How It Fits With This Kit
  • 18. Security Considerations
    • What Goes to Anthropic's API
    • MCP Server Credentials
    • The --dangerously-skip-permissions Flag
    • Pre-configured Guardrails in This Kit
    • Checklist Before Using Claude Code on a Real Project
  • 19. Customizing the Kit
    • Adding a New Agent
    • Adding a New Slash Command
    • Adding a New Skill
    • Adding a New Hook
    • Removing Components You Don't Need
    • Version Update Guide
  • 20. Claude Code Power Features
    • Keyboard Shortcuts (Inside Claude Code)
    • Essential CLI Flags
    • Core Tools
    • Permission Model
  • 21. Tips & Best Practices
    • Prompting Best Practices
    • Common Pitfalls — Avoid These
    • @ File References
    • Context Window Management
    • Parallel Workflows
    • Team Collaboration Patterns
    • Plugins Ecosystem
    • Skills — Best Practices
    • Writing a Good CLAUDE.md
      • The Basics: WHAT → WHY → HOW
      • Key Principles
      • Progressive Disclosure Example
      • Quick Rules of Thumb
    • When Claude Ignores Its Rules
      • Start-of-Task Prompt
      • When Claude Guesses Instead of Verifying
      • When Claude Flip-Flops
      • When Challenging Claude's Analysis
  • 22. Troubleshooting
    • command not found: claude
    • "Context too large" error
    • Edit tool fails with "string not found"
    • MCP server not connecting
    • Claude isn't using skills or agents
    • Background task not responding
    • Permission errors
    • Windows-Specific Setup
    • Run diagnostics
  • 23. Quick Reference Card
    • Commands You'll Use Every Day
    • Scaffolding
    • Design & Review
    • Agents (use @name)
    • Keyboard Shortcuts
    • MCP Tips
  • 24. Resources

What is Claude Code?

Claude Code is an agentic AI coding assistant that lives in your terminal. It understands your codebase, edits files, runs commands, and writes code — all through natural language.

Think of it as a senior developer pair-programming with you who knows your entire project, follows your team's conventions, and never gets tired.

1. Prerequisites

Before you begin, make sure you have:

• A Claude subscription — Claude Pro or Max at claude.ai, or an Anthropic API key from the Console

Optional for Quick Start (required for MCP servers):

• Node.js v24+
• Python v3.14+

2. Clone This Repo

This repo is your playground — use it to learn and practice Claude Code (Agentic AI coding assistant) and get familiar with its components (agents, skills, slash commands, hooks, MCP servers, memory) so you can automate your development workflow.

Option A: Learn & Explore (recommended for first-timers)

Clone the full repo and work through the exercises:

git clone https://github.com/kumaran-is/claude-code-onboarding.git
cd claude-code-onboarding

Option B: Adopt into an Existing Project

Already have a project? Copy just the Claude Code configuration into it:

# From the cloned repo, copy the config into your project
cp -r claude-code-onboarding/.claude/ your-project/.claude/
cp claude-code-onboarding/CLAUDE.md your-project/
cp claude-code-onboarding/.mcp.json your-project/

# Then customize for your project
cd your-project

After copying, you'll want to:

1. Edit CLAUDE.md — replace the tech stack and conventions with your project's
2. Edit .claude/settings.json — adjust permissions.allow for your build tools (e.g., remove flutter if you don't use it)
3. Edit .mcp.json — remove MCP servers you don't need, add project-specific ones
4. Remove agents/skills/commands for stacks you don't use
5. Run chmod +x .claude/hooks/*.sh to make hooks executable
6. Install the git pre-commit secrets hook (blocks commits containing API keys, tokens, and credentials):

   cp git-hooks/pre-commit-secrets.sh .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit
   

Customize for your tech stack and team. This kit ships with skills, agents, rules, and commands covering Java, NestJS, Python, Angular, Flutter, iOS, Android, and more — but you don't need all of them. Keep only what matches your stack and workflow:

Component	Where	What to trim
Skills	.claude/skills/	Delete skill folders for stacks you don't use (e.g. remove java-spring-api/ if you're Python-only)
Agents	.claude/agents/	Remove agent .md files for domains outside your stack — each one adds ~150 tokens to every session
Rules	.claude/rules/	Keep core-behaviors.md, lessons.md, and code-standards.md as a minimum. Add team-specific rules as new files in this folder — they are always loaded
Commands	.claude/commands/	Keep slash commands your team will actually use; delete the rest
Hooks	.claude/hooks/ + settings.json	Disable hooks you don't need by removing their entry from settings.json under hooks:
MCP servers	.mcp.json	Remove servers for tools you don't use — each connected server adds to session startup time

The goal is a lean, focused setup: fewer agents means less context overhead per session, fewer rules means clearer signal, and fewer commands means less noise in / autocomplete. Start minimal and add back what you find yourself needing.

3. Set Up Your Editor (Install VS Code)

We recommend open source Visual Studio Code as your IDE, though Claude Code works from any terminal — no specific editor is required. Download and install Visual Studio Code from the official site:

After installing, open the cloned project claude-code-onboarding with Visual Studio Code and use the integrated terminal for the remaining steps.

4. Install Claude Code

Open the Visual Studio Code integrated terminal and run the following:

Native Binary (Recommended)

1. For macOS / Linux

curl -fsSL https://claude.ai/install.sh | bash

2. Reload your shell

source ~/.bashrc   # or: source ~/.zshrc

3. After installation, restart VS Code(Close and reopen VS Code) so the terminal picks up the new PATH, then verify installation

claude --version

For Windows, see the official installation docs.

5. First-time Using Claude Code

Note: First-time users will be prompted to authenticate with a Claude Pro/Max subscription or an Anthropic API key.

From the VS Code terminal, launch the CLI:

claude

Follow the on-screen prompts to log in. Once authenticated with your Claude Pro/Max subscription or Anthropic Console API key. Claude Code automatically detects and loads the project configuration:

That's it! Claude Code will automatically detect and load:

Try these right away:

> /project-status
> What agents and skills are available in this project?
> Explain the tech stack from CLAUDE.md

🔗 Official Docs: https://code.claude.com/docs/en/quickstart

6. Install Claude-Mem (Persistent Memory) (Optional)

Claude Code forgets everything between sessions. Claude-Mem gives Claude persistent memory across sessions.

Inside a Claude Code CLI session, run:

> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem

Then restart Claude Code (/exit) or restart (close and reopen) the vscode.

What Claude-Mem Does

• Automatically captures what Claude Code does (file edits, decisions, tool usage)
• Compresses sessions into searchable memory using AI
• Injects relevant context at the start of new sessions
• Web viewer at http://localhost:37777 to browse memory

Verify with: Inside a Claude Code CLI session, run:

> Do you have any memory from previous sessions?

6a. Set Up Team Memory Sharing (Optional)

Once each developer has claude-mem installed individually, claude-mem-sync lets the team share selected observations (decisions, bug fixes, discoveries) across a shared GitHub repo — so your team's collective knowledge grows over time.

Run the one-shot setup command inside a Claude Code session:

> /setup-team-memory

This command:

• Installs and configures claude-mem-sync
• Creates .claude/memories/ folder structure in the repo
• Adds a GitHub Actions workflow that auto-merges contributions on push
• Updates .gitignore to keep raw contributions local
• Schedules weekly exports (Fridays 4pm) and imports (Saturdays 9am)
• Prints a full pass/fail verification table at the end

Safe to re-run — skips any step already completed. Each developer runs it once on their machine; the shared infrastructure files (workflow, memories folder) are committed once and shared via the repo.

7. Enable Voice Mode (Optional)

Claude Code does not support voice mode by default. VoiceMode is a community MCP server that adds this capability, letting you talk to Claude Code instead of typing, using OpenAI Whisper for STT (speech-to-text) and OpenAI TTS for speech output.

Note: VoiceMode supports any OpenAI-compatible STT/TTS service, not just OpenAI's Whisper/TTS.

One-Prompt Setup

Open a Claude Code session and paste this prompt — it handles the full installation (macOS, Linux, and Windows WSL2):

Set up VoiceMode for Claude Code using OpenAI Whisper (STT) and OpenAI TTS (speech output). Do the following steps in order:
1. Check if UV is installed (uv --version). If not, install it: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Run: uvx voice-mode-install
3. Run: claude mcp add --scope user voicemode -- uvx --refresh voice-mode
4. Create or update ~/.voicemode/voicemode.env with these two lines:
   VOICEMODE_TTS_BASE_URLS=https://api.openai.com/v1
   VOICEMODE_STT_BASE_URLS=https://api.openai.com/v1
5. Check if OPENAI_API_KEY is set in the environment. If not, remind me to add it to ~/.zshrc and re-source it.
Tell me when each step completes and flag any errors before moving to the next step.

After setup, restart Claude Code so the MCP server loads.

Manual Setup

Prerequisites

• Python 3.14+
• A microphone and speakers (or headphones)
• An OpenAI API key (for Whisper STT and OpenAI TTS)

Quick Install

# 1. Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install VoiceMode
uvx voice-mode-install

# 3. Register VoiceMode MCP server with Claude Code
claude mcp add --scope user voicemode -- uvx --refresh voice-mode

What Each Step Does

OpenAI API Configuration

VoiceMode uses OpenAI Whisper for speech-to-text (STT) and OpenAI TTS for speech output — two separate services under the same API key:

# 1. Set your OpenAI key (add to ~/.zshrc to persist)
export OPENAI_API_KEY=your-openai-key

# 2. Configure voicemode to use OpenAI for both STT and TTS
# Add to ~/.voicemode/voicemode.env:
VOICEMODE_TTS_BASE_URLS=https://api.openai.com/v1
VOICEMODE_STT_BASE_URLS=https://api.openai.com/v1

# 3. Restart Claude Code so the MCP server picks up the new key
claude converse

Important: The MCP server reads OPENAI_API_KEY from the environment at startup. If you set the key after Claude Code is already running, you must restart it for the change to take effect.

Usage

# Start Claude Code with voice mode
claude converse

# Or combine with auto-approved permissions (learning/playground only ⚠️)
claude --dangerously-skip-permissions converse

Once running, just speak into your mic — Claude will listen, process, and respond through your speakers. Say "stop" or press Ctrl+C to exit.

How It Works

              OpenAI Cloud API (same key, separate models)
  ┌─────────────────────────────────────────────────────┐
  │  Whisper (whisper-1)       /v1/audio/transcriptions  │
  │  You speak ──────────────────────────► Claude Code  │
  │                                              │       │
  │  OpenAI TTS (tts-1)        /v1/audio/speech  │       │
  │  You hear  ◄─────────────────────────────────┘       │
  └─────────────────────────────────────────────────────┘

Auto-Approve Voice Tools

To avoid permission prompts every time voice mode activates, the kit's .claude/settings.json includes:

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service",
      "Bash(voicemode *)"
    ]
  }
}

Platform-Specific Dependencies

brew install portaudio ffmpeg

sudo apt update
sudo apt install -y ffmpeg libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev python3-dev

sudo dnf install alsa-lib-devel ffmpeg portaudio portaudio-devel python3-dev

sudo apt install -y ffmpeg libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev

Troubleshooting

8. Try It Out — Your First 5 Minutes

You're set up. Before diving into components and theory, take Claude Code for a spin. Run these inside your Claude Code session:

Ask about the project

> What is this project? Summarize the tech stack and structure

> /project-status

Scaffold something

> /scaffold-spring-api hello-world

Watch how Claude creates the full project structure, files, and boilerplate — all from a single command.

Or, if you're not sure which scaffold command to use, describe what you want to build and let /new-project figure it out:

> /new-project flutter fitness tracker with Firebase
> /new-project python REST API for invoices
> /new-project angular dashboard for analytics

/new-project reads your description, maps it to the right tech stack, and routes to the correct scaffold command — including running the Mobile Design checkpoint and plan gate for Flutter projects. Supported stacks: Spring Boot, NestJS, Python/FastAPI, Agentic AI, Angular, Flutter, PostgreSQL schema, vector database.

Use a sub-agent

> @architect What improvements would you suggest for this project's structure?

Notice how the agent runs in its own context without cluttering your main conversation.

Pull live docs with MCP

> Explain how to set up Spring Security with JWT. use context7

The context7 MCP server fetches current, version-specific documentation instead of relying on training data.

Check what's loaded

> What agents, skills, and slash commands are available in this project?

> /mcp

> /agents

That's the core workflow: slash commands to scaffold, agents for expertise, MCP servers for external tools, and skills that activate automatically in the background. The next section breaks down each component in detail.

A note on permissions

Claude Code will ask for permission before accessing files or running commands. You'll see prompts like:

Do you want to proceed?
  1. Yes
❯ 2. Yes, allow reading from claude-code-onboarding/ from this project
  3. No

This can feel repetitive at first. The kit ships with pre-configured allow rules in .claude/settings.json that auto-approve common operations (build tools, git, Docker) — so most prompts you'll see are for operations that genuinely deserve a second look.

⚠️ For this learning playground only, you can skip all permission prompts:

claude --dangerously-skip-permissions

Do not use this in real projects. It disables all guardrails including the hooks and deny rules this kit ships with. For real projects, add frequently-used commands to the allow list in settings.json instead — see the Settings Configuration section for the full reference.

9. Understanding Claude Code Components

Knowing when to use what is the key to being productive with Claude Code. Here's a quick reference:

How They Fit Together

┌──────────────────────────────────────────────────────────────┐
│  CLAUDE.md          → What Claude knows about your project   │
│  settings.json      → What Claude can / can't do             │
│  Skills             → How Claude handles recurring tasks     │
│  Commands           → Quick actions you trigger manually     │
│  Sub-agents         → Specialists for complex work           │
│  Hooks              → Automatic formatting / validation      │
│  MCP Servers        → External tool connections              │
└──────────────────────────────────────────────────────────────┘

Decision Matrix - When to Use What

CLAUDE.md (Project Context)

What: A Markdown file at the project root that gives Claude Code, context about your project — tech stack, conventions, common commands, architecture, and rules.

When to use: Every project should have one. It's the first thing Claude reads at startup.

Where: ./CLAUDE.md (project root) or ~/.claude/CLAUDE.md (global, all projects)

You can auto-generate one by running /init inside a Claude Code session. This repo already includes one, so you can skip this step.

# Auto-generate one from your codebase
claude
> /init

Tips:

• Keep it under 40KB — too much context overloads the LLM's 200K token window
• Put the most important rules at the top
• Use imports for large docs: @docs/api-reference.md

File Locations & Priority

Slash Commands — Reusable Prompt Shortcuts

What: Prompts you trigger with /command-name. Think of them as reusable prompt shortcuts.

When to use: When you have a repeatable workflow you run often — scaffolding, reviewing, deploying.

Where: .claude/commands/my-command.md (project) or ~/.claude/commands/ (global)

Examples: Try running below commands inside Claude Code Session

> /scaffold-spring-api weather-service
> /scaffold-flutter-app fitness-tracker
> /design-database fitness tracking with users, workouts, and goals

Use $ARGUMENTS in the command file (.claude/commands/scaffold-spring-api.md) to accept parameters.

Agents (Subagents) — Specialist AI Personas

What: Specialized AI with isolated context for complex tasks with their own system prompt and tool restrictions. They run in a separate context window, so they don't pollute your main conversation.

When to use: When you need deep expertise in a specific domain — a dedicated backend developer, database architect, or codereviewer.

Where: .claude/agents/my-agent.md (project) or ~/.claude/agents/ (global)

Examples: Try running below commands inside Claude Code Session

> @java-spring-api Create a CRUD API for a Product entity with name, price, and category
> @flutter-mobile Build a login screen with Firebase Auth
> @database-designer Design the schema for an e-commerce platform
> @architect Design the system architecture for a real-time chat feature

Subagent-Driven Development (SDD) — Plan-to-PR Pipeline

What: A 3-role autonomous pipeline that turns an approved plan file into reviewed, committed code — without you shepherding each step.

Pipeline: Research (optional) → Implementer → Spec Reviewer → Quality Reviewer → PR

When to use: A plan file exists at docs/plans/YYYY-MM-DD-<feature>.md (created via /plan-review) and the work spans 3+ tasks.

Research phase — when it helps: When the feature touches an external API or service your team hasn't integrated before (e.g., Stripe Connect, a new compliance standard, an unfamiliar third-party SDK). The research agent produces a committed docs/research/<feature>.md artifact that the spec reviewer uses to validate API usage in Step 2. Skip it when the stack is familiar.

Two dispatch modes:

• Subagent mode — Agent tool, general-purpose agents, sequential. Best for ≤5 tasks.
• Team mode — TeamCreate with tech-specific agents running concurrently. Best for 6+ tasks.

How to trigger:

> Run the SDD pipeline for docs/plans/2026-03-01-payments.md
> Use subagent-driven-development to implement the auth feature plan

Or Claude auto-activates the subagent-driven-development skill when it detects a plan file and 3+ tasks.

Skill: .claude/skills/subagent-driven-development/

Skills — Auto-Activated Knowledge

What: Markdown files with domain knowledge, templates, and code patterns. Unlike commands, Skills are lazy-loaded and only brought into context when needed. Claude decides when to use them based on the task context — you don't invoke them explicitly.

When to use: When you want Claude to automatically apply certain patterns whenever a matching task comes up (e.g., always use your team's DTO pattern when creating Spring entities).

Where: .claude/skills/my-skill/SKILL.md

The skills in this repo auto-activate based on context:

MCP Servers — External Tool Integrations

What: The Model Context Protocol connects Claude Code to external services (GitHub, databases, documentation servers, gmail, slack, APIs) so Claude can use them as tools.

When to use: When Claude needs to interact with services beyond the local filesystem — creating GitHub PRs, querying live databases, fetching up-to-date documentation, invoking APIs.

Where: .mcp.json (project root)

This repo comes pre-configured with:

Weaviate Docs MCP Server

Gives Claude Code instant access to Weaviate documentation inside your editor.

Configuration

Add the following to your .mcp.json:

{
  "mcpServers": {
    "weaviate-docs": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://weaviate-docs.mcp.kapa.ai"
      ],
      "timeout": 60000,
      "env": {}
    }
  }
}

Authentication

The server requires a one-time OAuth login. Run the following command and follow the browser prompt to sign in with Google or GitHub:

npx mcp-remote https://weaviate-docs.mcp.kapa.ai

Your session will be cached at ~/.mcp-remote/ — you won't need to re-authenticate on subsequent uses.

Verify the server is connected:

claude mcp get weaviate-docs

You should see Status: ✓ Connected.

settings.json Configuration

Purpose: Permissions, environment variables, hooks, and tool behavior.

File Locations & Priority

Permission Rule Syntax

Key design decisions: This kit ships with a pre-configured settings.json that balances safety with productivity.

Note: This uses the array-style permission syntax (e.g., "Bash(npm *)") which is the current format. If you see older examples with object-style syntax ("Bash": ["npm *"]), those are outdated.

To add your own project-specific permissions, modify .claude/settings.json or create a personal .claude/settings.local.json for overrides that aren't committed to git.

Hooks — Automated Guardrails

What: Shell scripts that run automatically at specific lifecycle events (before/after tool use, on session start/end). Think of them as middleware for Claude Code — deterministic, always execute the same way.

When to use: When you need hard rules enforced every time, like run linter before commit or block commits without passing tests or block destructive commands or auto-format after every edit.

Where: .claude/settings.json → hooks section, scripts in .claude/hooks/

Note: SessionStart, SessionEnd, SubagentStop, PreCompact, and PermissionRequest hooks were added in recent Claude Code releases. If a hook event doesn't fire, verify your Claude Code version with claude --version and update if needed. The core events (PreToolUse, PostToolUse, Stop) are available in all versions.

This repo includes 4 hooks out of the box:

After cloning: chmod +x .claude/hooks/*.sh

Two-Layer Hook System

This repo implements a two-layer hook architecture:

Shell hooks are the baseline — always active, no way to disable them. Hookify sits on top and adds rules you can toggle without touching shell code.

Layer 2: Hookify Rule Engine

Rules live in .claude/hookify.*.local.md files with YAML frontmatter:

---
name: warn-console-log
enabled: true            # false to disable without deleting the file
event: file              # bash | file | stop | prompt | all
pattern: console\.log\(  # regex matched against the relevant field
action: warn             # warn (show message) | block (deny the tool call)
---

console.log detected — use the centralized logger instead.

To add a custom rule (slash command — no file editing needed):

/hookify Warn me when I write console.log in a TypeScript file
/hookify Block force-push to main
/hookify                    # scan conversation for behaviors to prevent

Or manage existing rules:

/hookify-list               # show all rules and their enabled/disabled status
/hookify-configure          # interactive toggle — enable or disable rules

Hookify never crashes Claude — it always exits 0. If Python is unavailable, a rule file is malformed, or any error occurs, Claude continues normally and the error is shown as a systemMessage.

Rule fields reference:

Blackbox — Session Decision Log

The blackbox is a persistent, append-only log of every session where decisions were made, code was written, or user constraints were stated. Think of it as a flight data recorder for your AI sessions — you don't look at it every day, but when something goes wrong or you need to trace a decision, it's invaluable.

How it works:

Each log entry looks like this:

## 2026-02-28T09:00Z
### Decisions
- Used PostgreSQL per user constraint (not AI default)
### Constraints Stated by User
- No mobile app — web only
### Files Modified
- src/db/config.ts — switched connection pool to postgres
### Deferred
- Rate limiting — explicitly deferred to post-launch
---

Key design principles:

• Never bloats context — blackbox/session-log.md lives outside .claude/ so it's never auto-loaded into every session
• Auto-created — hook creates the blackbox/ directory and log file on first session end if missing
• Monthly rotation — on month boundary, hook auto-renames to archive-YYYY-MM.md and starts fresh
• Two-layer logging — Claude writes decisions (policy rule); hook writes git facts (mechanical backup)
• Committed to git — full history preserved, team-visible

When to read it:

# "What did we decide last week?"
cat blackbox/session-log.md

# "Why was this file changed?"
grep -A 10 "2026-02-20" blackbox/session-log.md

# Read archived months
cat blackbox/archive-2026-01.md

Diagram Staleness Detection:

The blackbox also tracks when source code changes may have made an architecture diagram stale. The hook checks if any modified files match a known diagram by folder name and appends a warning automatically:

⚠️  Diagrams that may need updating:
  - docs/diagrams/auth-flow.md (auth/ was modified)

Naming convention: src/auth/ → docs/diagrams/auth-flow.md (folder prefix = diagram prefix). The policy rule instructs Claude to update or create diagrams during the session; the hook warns if it was missed.

docs/
└── diagrams/
    ├── auth-flow.md       ← generated after auth feature, updated when auth/ changes
    ├── payment-flow.md    ← generated after payments feature
    └── api-contracts.md   ← generated after API layer work

Reference a diagram in any session with @docs/diagrams/auth-flow.md to give Claude instant architectural context without codebase exploration.

Ralph Loop — Autonomous Iteration

The ralph loop is a Stop hook that keeps Claude working on a task autonomously — when Claude tries to exit, the hook intercepts, checks if the task is done, and if not, feeds the same prompt back to start another iteration. Each iteration can see all file changes from previous iterations.

Named after Ralph Wiggum (The Simpsons) — persistent iteration despite setbacks. High risk. Use deliberately. Adapted from the ralph-wiggum plugin in the Anthropic claude-code-samples repository.

Start

/ralph-loop "Your task" --max-iterations 10 --completion-promise "DONE"

Monitor progress:

head -5 .claude/ralph-loop.local.md   # iteration: 3, max_iterations: 10, ...

Stop

/cancel-ralph   # deletes state file — loop exits on next turn

Regular use

# Fix all TypeScript errors — loop until clean
/ralph-loop "Run: npx tsc --noEmit. Fix all errors. Repeat until zero errors." \
  --max-iterations 15 --completion-promise "ZERO ERRORS"

# Implement all unchecked items in a plan file
/ralph-loop "Read docs/plans/feature.md. Implement the next unchecked item. Repeat." \
  --max-iterations 20 --completion-promise "ALL ITEMS DONE"

With sub-agents

Sub-agents work naturally inside a ralph loop. Each iteration spawns fresh sub-agents; their file changes persist into the next iteration.

/ralph-loop "Run /review-pr. Fix all CRITICAL findings using specialist agents.
When zero CRITICAL findings remain, output <promise>ALL CRITICAL RESOLVED</promise>" \
  --max-iterations 10 --completion-promise "ALL CRITICAL RESOLVED"

With Agent teams

Teams are recreated each iteration (previous team sessions end, but TaskList entries and file changes persist). Write prompts that check TaskList state first:

/ralph-loop "Check TaskList for pending tasks. If tasks remain, create a team and dispatch them.
When all tasks complete and tests pass, output <promise>TEAM DONE</promise>" \
  --max-iterations 5 --completion-promise "TEAM DONE"

When to use / avoid

Always set --max-iterations. Without it, the loop runs until the completion promise is satisfied or you run /cancel-ralph. Uncontrolled loops = uncontrolled API costs.

Autoresearch — Metric-Gated Improvement Loop

Autoresearch is an autonomous loop that improves code quality by measuring, changing, and deciding — mathematically. Unlike /ralph-loop (which runs blind), autoresearch only keeps changes that move the metric in the right direction. Every regression is automatically rolled back with git reset --hard.

Inspired by Andrej Karpathy's autoresearch pattern — a self-improving loop that applies ML-style evaluation (keep if better, discard if worse) to codebase quality.

Start

/autoresearch                                    # measure all stacks, fix top issues
/autoresearch --metric nestjs                    # focus on NestJS only
/autoresearch --metric flutter --max-iterations 5
/autoresearch --metric all --target 10           # aim to cut 10 issues per iteration

What it measures

How a single iteration works

Measure baseline score (e.g. 47 issues)
        ↓
Pick highest-impact category (e.g. console.log → Logger)
        ↓
Implementer agent fixes 3–5 easiest instances
        ↓
Re-measure score (e.g. 41 issues)
        ↓
41 < 47? ✅ git commit — keep changes, continue
41 ≥ 47? ❌ git reset --hard — discard, try different category next iteration

Example — NestJS type safety pass

# Before: 34 `: any` types in src/
/autoresearch --metric nestjs --target 5 --max-iterations 8

# Iteration 1: finds easy fetch responses with `as any` → adds proper types → 34 → 29 ✅ committed
# Iteration 2: tries a complex service, breaks a test → git reset → rollback
# Iteration 3: finds console.log calls → replaces with Logger → 29 → 24 ✅ committed
# ...continues until max-iterations or score hits 0

Stop

/cancel-ralph   # autoresearch shares the same cancel mechanism as ralph-loop

How it differs from /ralph-loop

Rule of thumb: Use /ralph-loop when success is defined by a behaviour ("all tests pass", "feature works"). Use /autoresearch when success is defined by a number ("zero console.log", "zero as any").

When to use / avoid

Lessons Log — Self-Improvement Loop

The lessons log is the team's shared record of corrections — mistakes Claude made that you corrected, expressed as rules to prevent recurrence.

Unlike the blackbox (which is never auto-loaded), lessons.md lives in .claude/rules/ so it is always active in every session.

How it works:

1. Claude makes a mistake. You correct it.
2. Before proceeding, Claude writes a 4-line lesson entry to lessons.md.
3. You commit and push. All teammates get the lesson on next git pull.
4. From that session forward, every Claude instance on the team avoids the same mistake.

Bloat prevention — three-tier lifecycle:

lessons.md (max 15 entries)
    |
    | lesson recurs 3x across sessions
    v
Promoted to matching rules file (core-behaviors.md, code-standards.md, etc.)
    + deleted from lessons.md

lessons.md stays lean (~60 lines max). Repeated lessons become permanent rules. One-off mistakes that never recur get pruned at the 15-entry cap.

Difference from blackbox:

Model Selection & Cost Awareness

Claude Code supports three Anthropic models, each optimized for different use cases:

Pricing details:

• Opus 4.6: $5 per million input tokens, $25 per million output tokens. Source
• Sonnet 4.5: $3 per million input tokens, $15 per million output tokens. Source
• Haiku 4.5: $1 per million input tokens, $5 per million output tokens. Source
• Long context (>200K tokens): Premium rates apply — Opus: $10/$37.50, Sonnet: $6/$22.50 per million tokens. Source

Recommended default: Sonnet 4.5

Sonnet balances high performance with efficient response times for coding tasks. Set it as your persistent default in .claude/settings.json:

{
  "permissions": {},
  "model": "sonnet"
}

Switching models:

Inside a Claude Code session:

/model sonnet              # Switch to Sonnet (default)
/model haiku               # Switch to Haiku (fast, cheap)
/model opus                # Switch to Opus (complex reasoning)

Or use the --model flag when starting:

claude --model sonnet
claude --model haiku
claude --model opus

Cost monitoring:

/cost                      # Token usage and estimated cost for this session
/stats                     # Usage stats over 7/30 days or all-time
/usage                     # Plan limits and remaining usage

Cost-saving tips:

• Use Sonnet for 80% of work — code generation, debugging, refactoring
• Use Haiku for docs — README updates, comments, non-critical tasks
• Use Opus sparingly — complex architecture, critical security reviews (burns tokens quickly)
• Use /compact regularly in long sessions — stale context wastes tokens
• Use @file references instead of pasting file contents
• Disable unused MCP servers (/mcp to check)

10. Cheaper Alternative: MiniMax M2.5

MiniMax M2.5 is a cost-effective alternative to Claude for agentic coding workflows.

Why Choose MiniMax M2.5?

MiniMax M2.5 (released February 12, 2026) delivers near-frontier coding performance — matching or approaching Claude Opus 4.6 on key benchmarks like SWE-Bench Verified (80.2%), while being 10-20x cheaper and often faster in real agentic workflows. It excels at full-stack development across 10+ languages, task decomposition, planning, and tool use via its Forge Framework.

For heavy users of Claude Code CLI, the MiniMax Coding Plan turns this into an ultra-cost-effective setup with predictable prompt-based limits instead of per-token bills that can explode during long sessions. Many developers report switching from Claude Max and handling 90%+ of daily coding/agentic work at a fraction of the cost, with seamless integration and built-in extras like MCP server with web search and image understanding.

Overview of MiniMax M2.5 for Coding

MiniMax M2.5 is a 230B-parameter model (10B active) built for coding and agentic tasks. It supports 10+ languages, handles the full dev lifecycle—from system design to testing—and works across Web, Android, iOS, and Windows. Powered by its Forge Framework for agentic workflows.

• The MiniMax M2.5 Coding Plan subscription provides a dedicated API key (exclusive to the plan, not interchangeable with pay-as-you-go keys).
• It uses the same Anthropic-compatible endpoint (https://api.minimax.io/anthropic).
• The model remains MiniMax-M2.5 (or just MiniMax-M2.5 in most configs).
• It includes extras like built-in tools (e.g., web_search, understand_image) via MCP (MiniMax Coding Plan tools), which you can enable in Claude Code.
• Billing is subscription-based with prompt/hour limits (rolling 5-hour window: e.g., Starter = 100 prompts/5h, Plus = 300, Max = 1000), much cheaper and more predictable for heavy coding use than pay-as-you-go or Claude Max.

Step-by-Step Configuration

1. Subscribe to the Coding Plan

• Go to: https://platform.minimax.io/subscribe/coding-plan
• Choose a plan
• After subscription activates, go to your account: https://platform.minimax.io/user-center/payment/coding-plan (or API Keys section).
• Generate/copy your Coding Plan API Key (it looks like a standard sk-... or similar key, but it's plan-exclusive). Protect it—don't share or commit it.

2. Clear Any Conflicting Anthropic Variables (important to avoid your Claude Max auth leaking in)

In your terminal:

unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_BASE_URL

3. Configure Claude Code

Update the settings.local.json file (~/.claude/settings.local.json) as below.

Paste this (replace <YOUR_CODING_PLAN_API_KEY> with your actual key):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<MINIMAX_CODING_PLAN_KEY>",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "ANTHROPIC_MODEL": "MiniMax-M2.5",
    "ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.5"
  }
}

4. (Optional but Highly Recommended) Enable MCP Tools (web search + image understanding — included in Coding Plan)

MiniMax provides an official MCP server for Claude Code to get these tools working seamlessly.

Install/run it (requires uvx/pipx or similar for Python tools):

claude mcp add -s user MiniMax --env MINIMAX_API_KEY=<YOUR_CODING_PLAN_API_KEY> --env MINIMAX_API_HOST=https://api.minimax.io -- uvx minimax-coding-plan-mcp -y

Or manually add to ~/.mcp.json:

{
  "mcpServers": {
    "MiniMax": {
      "command": "uvx",
      "args": ["minimax-coding-plan-mcp", "-y"],
      "env": {
        "MINIMAX_API_KEY": "<YOUR_CODING_PLAN_API_KEY>",
        "MINIMAX_API_HOST": "https://api.minimax.io"
      }
    }
  }
}

• In Claude Code session, type /mcp — you should see web_search and understand_image listed if successful.

5. Test It

• Run: claude
• Type /model inside the session — it should show MiniMax-M2.5.
• Try a coding task: "Plan and implement a full-stack Todo app with Angular + Java Spring boot".
• Test tools: Ask something needing search, like "Search latest Angular features and update this component".

11. Multiple Sub Agents

Spwaning Multiple agents that run inside main Claude Code session to handle specific subtasks (like research or verification). They work independently, then report results back to main Claude Code session.

Example:

> Spawn a multiple sub-agents to implement Authentication service 

12. Agent Teams — Coordinated Multi-Agent Collaboration

Agent Teams is a new experimental feature for Claude Code where multiple Claude Code sessions working in parallel. One lead coordinates and assigns tasks. Multiple Teammates work independently with separate context windows and communicate via shared tasks and messages.

Architecture:

Team Lead Session (Main Claude)
    ↓
Spawns 3 teammate sessions (separate Claude Code instances)
    ↓
Teammate 1 ←→ Shared Task Board ←→ Teammate 2
    ↑                ↕                    ↑
    └────────→ Teammate 3 ←──────────────┘
              (Direct P2P messaging)

Key Capabilities:

• Teammates communicate directly with each other
• Shared task list all teammates can read/write
• Each teammate = separate Claude Code session
• You can interact with individual teammates directly
• Parallel + autonomous coordination

Key Difference from Sub-Agents:

When to Use Agent Teams:

• Parallel code reviews (security, performance, testing)
• Multi-layer features (frontend + backend + database in parallel)

How to Enable

Agent Teams are disabled by default. Enable by setting the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable.

settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

tmux Setup:

Agent Teams work best with tmux mode, which gives you real-time visibility of all teammates in split panes.

Step 1: Install tmux

brew install tmux

Step 2: Verify installation

tmux -V

Step 3: Start Claude Code in tmux

Start tmux session

tmux

Launch Claude Code inside tmux session

claude

Step 4: Spawn teammates

> Spawn 3 teammates to refactor authentication module:
> 1. Frontend: Refactor authentication UI components
> 2. Backend: Update JWT token validation in auth service
> 3. Database: Add user session tracking table

What you'll see:

• Lead in main pane (top)
• Teammate 1 in split pane
• Teammate 2 in split pane
• Teammate 3 in split pane

Known Limitations:

Use Agent Teams when parallelization justifies the cost. For sequential tasks, stick with sub-agents.

13. Claude Code Desktop — GUI with Live Preview

Claude Code Desktop is a desktop GUI that wraps the same Claude Code engine you use in the terminal — same CLAUDE.md, same .claude/agents, skills, slash commands, settings.json, hooks, and MCP servers. Everything in this kit works in Desktop without changes.

What Desktop adds on top of CLI: an embedded browser preview with interactive testing, visual diff review, parallel sessions with Git worktree isolation, background PR monitoring with auto-merge, and the ability to seamlessly switch between Desktop ↔ CLI ↔ VS Code at any time.

What It Can Do

Note: Agent Teams are not supported in Claude Code Desktop — they are a CLI-only feature that requires tmux for split-pane visibility. Agent Teams need the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable and spawn multiple independent Claude Code CLI sessions, which the Desktop GUI doesn't support. Sub-agents (single-session task delegation) work fine in Desktop. If you need Agent Teams, use the CLI.

Testing Frontend SPAs (Angular, React)

Sample repo: kumaran-is/shopping-list-demo — Angular 21 shopping list app pre-configured with agents, skills, and slash commands. Open in Claude Code Desktop and start testing.

Start the dev server and test interactively — Claude can click, type, navigate, and verify DOM changes in the embedded preview with HMR hot-reload:

> Start ng serve and open the preview. Add an item "Milk" with quantity 2.
  Verify it appears in the list and the counter updates.

> Mark "Milk" as picked up. Switch to Pending filter. Confirm it's hidden.

> Add localStorage persistence. Refresh the preview and verify items persist.

Claude takes screenshots, reads the DOM, identifies errors, and fixes them — all within the embedded browser.

Testing Backend REST APIs (Spring Boot, NestJS)

Sample repo: kumaran-is/claude-desktop-springboot-demo — Spring Boot 3.5 WebFlux REST API with H2, Swagger UI, and full CRUD. Open in Desktop, launch Swagger UI in preview, and test endpoints.

Launch Swagger UI in the embedded preview and test endpoints using plain English:

> Run mvn spring-boot:run and open Swagger UI in the preview.

> In Swagger UI, POST a product: name "Laptop", price 999.99, category "Electronics".
  Then GET /api/v1/products and verify it returns.

> Test full CRUD in Swagger UI: POST two products, PUT to rename one,
  DELETE the other, GET to confirm final state.

Claude expands endpoints, clicks "Try it out", fills JSON bodies, executes requests, and reads responses — all in the embedded browser, no curl needed.

Testing Flutter Apps (Canvas Limitation)

Sample repo: kumaran-is/claude-desktop-flutter-demo — Flutter notes app with Riverpod, GoRouter, and Device Preview. Includes the full canvas limitation workaround guide and code-assisted test prompts.

Flutter web renders to a <canvas> element, not DOM nodes. This means preview_fill and JavaScript text input do not work on Flutter TextFields. Button clicks via the semantics tree work fine.

Workaround — code-assisted testing: For any step requiring text input, temporarily modify source code (provider state, controller initial text), restart the server, verify via screenshot + accessibility snapshot, then revert.

> Modify notes_provider.dart to pre-populate with 4 test notes. Restart the
  preview server. Verify all notes appear via screenshot and accessibility tree.

> Click the star button for "Meeting Notes" in the semantics tree. Verify it
  shows as important.

> Revert provider to empty state. Restart and confirm empty list.

See the Flutter Web Canvas Limitation doc in the Flutter demo repo for the full interaction patterns reference.

XcodeBuildMCP — iOS Build, Debug & Test from Claude

XcodeBuildMCP is an MCP server by Sentry that gives Claude direct access to Xcode's build system. It provides 79 tools across build, debug, test, simulator management, device deployment, and UI automation — making it a complete iOS/macOS development companion.

Why it matters for Flutter: Flutter generates an Xcode project (ios/Runner.xcworkspace). XcodeBuildMCP lets Claude build it, run it on a simulator or device, attach a debugger, capture logs, and inspect the UI — all without opening Xcode.

Install

brew tap getsentry/xcodebuildmcp
brew install xcodebuildmcp

Requirements: macOS 14.5+, Xcode 16+

Configure (.mcp.json)

Already configured in this repo. The entry:

"xcodebuild": {
  "type": "stdio",
  "disabled": false,
  "description": "Xcode build, run, debug, and test for iOS simulator, device, and macOS targets.",
  "command": "xcodebuildmcp",
  "args": ["mcp", "--disable-telemetry"],
  "timeout": 60000
}

Note: --disable-telemetry opts out of Sentry's crash reporting. Remove it if you want to help the project with error telemetry.

Key Tool Groups

Sample Prompts

> Build the Flutter iOS app for simulator and launch it

> Attach the debugger to the running app, set a breakpoint in AppDelegate,
  and show me the variables when it hits

> Capture simulator logs while I test the login flow, then show me any errors

> List available Xcode schemes for the ios/Runner.xcworkspace

> Build for my connected iPhone and install the app

Maestro — Mobile E2E Testing (iOS + Android)

Maestro is a cross-platform mobile E2E testing framework with an MCP server. Claude generates and runs test flows from natural language — no YAML writing required. Completely free for local use (Apache 2.0, no API key needed).

Prerequisites

Note: You only need Xcode for iOS testing and Android Studio for Android testing. Install whichever platforms you target — or both for full cross-platform E2E.

Step 1: Install Java 21

brew install openjdk@21

After Homebrew finishes, create the system symlink so macOS can find it:

sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk

Step 2: Set PATH in your shell

Add these lines to ~/.zshrc (default macOS shell) or ~/.bashrc:

# Java 21
export JAVA_HOME="/opt/homebrew/opt/openjdk@21"
export PATH="$JAVA_HOME/bin:$PATH"

# Maestro
export PATH="$PATH:$HOME/.maestro/bin"

Reload your shell:

source ~/.zshrc   # or source ~/.bashrc

Step 3: Install Maestro CLI

curl -fsSL "https://get.maestro.mobile.dev" | bash

Step 4: Verify both

java -version      # Should show: openjdk 21.x.x
maestro --version  # Should show: Maestro [version number]

Troubleshooting: If maestro --version shows "Unable to locate a Java Runtime", the symlink step was missed — run the sudo ln command from Step 1. If java -version shows nothing, run source ~/.zshrc or open a new terminal.

How It Works

You describe tests in plain English. Claude generates the YAML flow, runs it via Maestro MCP, and reports results:

You:     "Test the login flow with email test@example.com and password secret123"
Claude:  1. Generates login-flow.yaml
         2. Runs it on the active simulator/emulator
         3. Reports: PASS (5/5 steps) or FAIL (step 3: "Dashboard" not visible)

The generated YAML flows are saved to test/e2e/ — reusable by your team and runnable in CI without Claude.

Configure (.mcp.json)

Already configured in this repo:

"maestro": {
  "type": "stdio",
  "disabled": false,
  "description": "Maestro MCP server for cross-platform mobile E2E testing on iOS and Android.",
  "command": "maestro",
  "args": ["mcp"],
  "timeout": 60000
}

Sample Prompts

Test on iOS Simulator:

> Build the fitness app with XcodeBuildMCP, then run Maestro E2E tests
  on the login screen — try valid and invalid credentials

> Test the full workout flow: navigate to Exercises, filter by CHEST,
  tap Bench Press, add it to a workout, complete the workout

> Generate Maestro test flows for all screens in the fitness app
  and save them to test/e2e/

Test on Android Emulator:

> Start the Android emulator, install the fitness app APK,
  then run the login E2E test with Maestro

> Run the same login-flow.yaml on Android to verify cross-platform parity

Test on Connected Device:

> Run the checkout E2E flow on my connected iPhone

> Run all test flows in test/e2e/ on the connected Android device

Generate + Save Flows for CI:

> Create Maestro test flows for login, registration, and workout creation.
  Save each as a separate YAML file in test/e2e/

> Run all Maestro flows in test/e2e/ and give me a pass/fail summary

XcodeBuildMCP + Maestro Together

These two MCP servers complement each other for a complete iOS testing workflow:

XcodeBuildMCP                              Maestro
─────────────                              ───────
build_run_sim → build & launch app    →    Run E2E test suite
debug_attach_sim → diagnose crash     ←    Test failure found
screenshot → quick visual check            Structured pass/fail assertions

What a Generated Flow Looks Like

Claude generates this automatically — you never write it by hand:

# test/e2e/login-flow.yaml
appId: com.example.fitnessApp
---
- launchApp
- tapOn: "Email"
- inputText: "test@example.com"
- tapOn: "Password"
- inputText: "secret123"
- tapOn: "Sign In"
- assertVisible: "Welcome"
- assertVisible: "Workout"

Run it anytime without Claude: maestro test test/e2e/login-flow.yaml

CI/CD & PR Workflow

Claude Desktop monitors PRs in the background and auto-fixes CI failures:

> Stage all changes, commit, push to feature/shopping-list, and create a PR.

> Create a GitHub Actions CI workflow that runs lint, test, and build on PRs.
  Push it and verify the action runs.

> Check the GitHub Actions status on our PR. If it failed, show me the error
  and fix it.

Claude watches the PR, catches CI failures, pushes fixes, and can auto-merge when green — all while you continue working on the next task.

For CLI users, the same loop is available as a slash command: /iterate-pr — see After Opening a PR.

Remote SSH Debugging

Connect to any remote server (EC2, GCP VM, Azure VM, dev containers) and debug directly from the Desktop GUI. Claude Code must be installed on the remote machine.

Setup: Environment dropdown → + Add SSH connection → enter Host + Identity File

> Check why the Spring Boot app is failing on the EC2 instance.
  Read logs, test endpoints, fix the config, restart the service.

Full capabilities on SSH: file access, bash commands, connectors, plugins, MCP servers, git, and embedded preview (with SSH port forwarding for visual preview).

Desktop vs CLI — When to Use What

You can switch between them at any time — start in CLI, run /desktop to bring the session into Desktop, or move a local Desktop session to the web with "Continue with Claude Code on the web."

Quick Start

1. Download Claude Desktop from claude.ai/download
2. Open the app → Code tab → select your project folder
3. Pick a model and permission mode → start chatting
4. Desktop auto-detects dev servers and stores config in .claude/launch.json

Docs: Claude Code Desktop · Desktop Quickstart · Preview, Review, and Merge

14. What Gets Sent to the LLM?

Every time you send a prompt in Claude Code, it assembles a context window — the complete package of information sent to the LLM for that turn. Understanding what goes into this window helps you manage it effectively.

Context Window Anatomy

What Each Layer Contains

Key Takeaways

Everything competes for the same 200K tokens. A bloated CLAUDE.md, 20 MCP servers, and a long conversation history all eat from the same pool. When the window fills up, Claude's output quality degrades.

MCP tools are the biggest variable cost. Each connected server adds tool schemas to every turn. With 20+ servers, you can lose 50K+ tokens before typing anything. Claude Code now has Tool Search that loads MCP tools on-demand (auto-activates when tools exceed 10% of context), but keeping unused servers disabled is still best practice.

Skills and commands load selectively. Unlike CLAUDE.md (always loaded), skills only load when Claude determines they're relevant, and slash commands only load when you invoke them. This is why skills are preferred over stuffing everything into CLAUDE.md.

Monitor your usage:

> /context              # Visual breakdown of token usage
> /cost                 # Token and cost statistics
> /compact              # Manually compress conversation history

15. What's in This Repo

79 components — 21 skills, 14 commands, 21 agents, 4 rules, 4 hooks, 12 MCP servers, 2 settings files, 1 CLAUDE.md.

claude-code-onboarding/
├── CLAUDE.md                            # Project instructions — tech stack, conventions, rules
├── .mcp.json                            # 12 MCP servers (see table below)
├── .gitignore
├── README.md                            # ← You are here
│
└── .claude/
    ├── settings.json                    # Permissions (allow/ask/deny) and hook configs
    ├── settings.local.json              # Personal overrides (gitignored)
    │
    ├── rules/                            # Always-loaded behavioral guidelines
    │   ├── code-standards.md             # Error handling, DRY, logging, output quality
    │   ├── core-behaviors.md             # Assumptions, confusion management, simplicity
    │   ├── first-principles.md           # Hard Constraints, Quality Thresholds, Workflow Invariants, AI anti-pattern detection
    │   ├── leverage-patterns.md          # Task protocol, test-first, naive-then-optimize
    │   └── verification-and-reporting.md # Verify before claiming, honest status reporting
    │
    ├── hooks/                            # Lifecycle hook scripts (chmod +x after cloning)
    │   ├── pre-bash-guard.sh             # Block destructive bash commands (rm -rf, DROP, etc.)
    │   ├── pre-edit-protect-sensitive.sh  # Block edits to .env, keys, lock files
    │   ├── post-edit-format.sh           # Auto-format TS/JS/Dart/Python after edits
    │   └── stop-secret-scan.sh           # Scan changed files for leaked secrets on stop
    │
    ├── agents/                           # 20 specialist AI personas (invoke with @name)
    │   │
    │   │  # — Development agents (model: sonnet) —
    │   ├── java-spring-api.md            # Spring Boot WebFlux expert
    │   ├── nestjs-api.md                 # NestJS / Fastify / Prisma expert
    │   ├── python-dev.md                 # Python / FastAPI expert
    │   ├── agentic-ai-dev.md             # LangChain / LangGraph AI agent builder
    │   ├── google-adk.md                 # Google ADK (Gemini agents) builder
    │   ├── angular-spa.md                # Angular frontend expert
    │   ├── a2ui-angular.md              # A2UI renderer developer (Angular)
    │   ├── flutter-mobile.md             # Flutter mobile expert
    │   ├── frontend-design.md            # Creative UI/UX design specialist
    │   ├── database-designer.md          # PostgreSQL + Firestore architect
    │   ├── architect.md                  # Solution architect
    │   ├── flutter-security-expert.md    # Mobile security & privacy compliance
    │   │
    │   │  # — Review agents (model: opus) —
    │   ├── code-reviewer.md              # General code quality & review
    │   ├── nestjs-reviewer.md            # NestJS code review specialist
    │   ├── spring-reactive-reviewer.md   # Spring WebFlux review specialist
    │   ├── agentic-ai-reviewer.md        # Agentic AI code review specialist
    │   ├── security-reviewer.md          # Security vulnerability reviewer
    │   ├── postgresql-database-reviewer.md # PostgreSQL performance & schema reviewer
    │   │
    │   │  # — Specialist agents —
    │   ├── accessibility-auditor.md      # WCAG / a11y compliance auditor
    │   ├── riverpod-reviewer.md          # Flutter Riverpod state management reviewer
    │   ├── dedup-code-agent.md           # Dead code & duplication detector
    │   └── ui-standards-expert.md        # UI consistency & design system enforcement
    │   │
    │   │  # — CI/CD agents (model: haiku) —
    │   ├── deployment-engineer.md        # GitHub Actions, Docker, Cloud Run, Flutter CI, Firebase deploy
    │   │
    │   │  # — Infrastructure agents (model: opus) —
    │   └── terraform-specialist.md       # GCP IaC: Cloud Run, Cloud SQL, Artifact Registry, IAM, WIF
    │
    ├── commands/                          # 13 slash commands (triggered with /name)
    │   │
    │   │  # — Scaffolding —
    │   ├── scaffold-spring-api.md        # /scaffold-spring-api <name>
    │   ├── scaffold-nestjs-api.md        # /scaffold-nestjs-api <name>
    │   ├── scaffold-python-api.md        # /scaffold-python-api <name>
    │   ├── scaffold-agentic-ai.md        # /scaffold-agentic-ai <name>
    │   ├── scaffold-google-adk.md        # /scaffold-google-adk <name>
    │   ├── scaffold-angular-app.md       # /scaffold-angular-app <name>
    │   ├── scaffold-a2ui.md             # /scaffold-a2ui <name> — A2UI renderer module
    │   ├── scaffold-flutter-app.md       # /scaffold-flutter-app <name>
    │   │
    │   │  # — Design —
    │   ├── design-database.md            # /design-database <domain description>
    │   ├── design-architecture.md        # /design-architecture <system description>
    │   │
    │   │  # — Workflow —
    │   ├── add-feature.md                # /add-feature <feature description>
    │   ├── review-code.md                # /review-code [focus area]
    │   ├── audit-security.md             # /audit-security [scope]
    │   ├── iterate-pr.md                 # /iterate-pr [PR#] — fix CI + feedback loop until green
    │   ├── status-check.md               # /status-check — binary works/broken report
    │   └── project-status.md             # /project-status — codebase summary
    │
    └── skills/                            # 20 auto-activated domain knowledge skills
        │
        │  # — Backend skills —
        ├── java-spring-api/              # Spring Boot 3.5.x: entity patterns, resilience (Resilience4j),
        │                                 # testing (WebTestClient, Testcontainers), security hardening,
        │                                 # reactive debugging, Redis/SSE patterns (9 reference files)
        ├── java-coding-standard/         # Java naming, immutability, records, sealed types (1 reference file)
        ├── nestjs-api/                   # NestJS 11.x: module structure, Prisma 7.x, config management,
        │                                 # circuit breakers, feature flags, messaging (BullMQ/RabbitMQ/Kafka),
        │                                 # REST controllers, security, debugging, testing (23 reference files)
        ├── nestjs-coding-standard/       # NestJS naming, module patterns, DTO conventions (1 reference file)
        ├── python-dev/                   # Python 3.14: FastAPI patterns, Pydantic v2, async SQLAlchemy,
        │                                 # pytest fixtures, ruff/mypy config (1 reference file)
        │
        │  # — Agentic AI skills —
        ├── agentic-ai-dev/               # LangChain/LangGraph: ReAct agents, RAG (standard/agentic/self-RAG),
        │                                 # tool definitions, multi-provider LLM routing, guardrails,
        │                                 # prompt injection detection, PII redaction (17 reference files)
        ├── agentic-ai-coding-standard/   # Agentic AI naming, TypedDict state, async patterns (1 reference file)
        ├── google-adk/                   # Google ADK (Agent Development Kit): Agent, SequentialAgent,
        │                                 # ParallelAgent, LoopAgent, FunctionTool, McpToolset, callbacks,
        │                                 # session management, memory, artifacts, FastAPI integration (8 reference files)
        │
        │  # — Frontend & mobile skills —
        ├── angular-spa/                  # Angular 21.x: standalone components, signals, control flow,
        │                                 # TailwindCSS 4.x + daisyUI 5.x setup, zoneless testing,
        │                                 # accessibility checklist, troubleshooting (12 reference files)
        ├── a2ui-angular/                 # A2UI (Agent-to-User Interface): recursive renderer,
        │                                 # component catalog allowlist, agent service (REST/SSE),
        │                                 # security validation, streaming support (5 reference files)
        ├── flutter-mobile/               # Flutter 3.41.x: clean architecture layers, Riverpod 3.x,
        │                                 # Freezed models, GoRouter, Firebase integration (2 reference files)
        ├── riverpod-patterns/            # Riverpod: AsyncNotifier, AsyncValue.when, ref.watch vs ref.read,
        │                                 # family providers, lifecycle management (1 reference file)
        ├── ui-standards-tokens/          # Design tokens: spacing scale, color system, typography,
        │                                 # elevation, touch targets, responsive breakpoints (2 reference files)
        │
        │  # — Architecture & design skills —
        ├── architecture-design/          # C4 diagrams, API contracts, sequence diagrams,
        │                                 # deployment topology, ADR templates (1 reference file)
        ├── architecture-decision-records/ # ADR lifecycle, templates, status tracking (3 reference files)
        ├── database-schema-designer/     # PostgreSQL schema: normalization, Flyway migrations,
        │                                 # Firestore collections, indexing strategy, ERDs (7 reference files)
        ├── ddd-architect/                # Domain-Driven Design: bounded contexts, aggregates,
        │                                 # context mapping, event storming, strategic/tactical design (4 reference files)
        ├── openapi-spec-generation/      # OpenAPI 3.1: schema generation, path definitions,
        │                                 # security schemes, examples, validation (5 reference files)
        │
        │  # — Tooling skills —
        ├── mcp-builder/                  # MCP server development: Python (FastMCP) and Node.js (MCP SDK),
        │                                 # tool definitions, transport config (18 reference files + scripts)
        ├── browser-testing/              # Browser automation & testing: Chrome DevTools MCP (inspection,
        │                                 # performance, network) + Browser-Use MCP (E2E flows, form filling) (3 reference files)
        ├── domain-finder/                # Domain name availability checking via WHOIS (1 reference file)
        └── changelog-generator/          # Git history parsing, semantic versioning,
                                          # release notes generation (1 reference file)
│
└── docs/
    └── workflows/                        # 43 multi-phase workflow guides (humans + Claude Code)
        └── README.md                     # ← Index of all workflows by category

Workflow guides: docs/workflows/README.md — covers every development process from ideation to deployment, organized by phase (Feature Dev, Testing, Security, Shipping, Ops, Tooling).

MCP Servers (.mcp.json)

Browser Automation

We use a three-tool stack for complete browser testing:

Install playwright-cli

# Package name is @playwright/mcp; binary installed is playwright-cli
npm install -g @playwright/mcp@latest
playwright-cli install    # download browsers
playwright-cli --version  # verify

Quick sanity check

playwright-cli open https://example.com
playwright-cli snapshot     # accessibility tree — should show page structure
playwright-cli network      # should show GET https://example.com → 200
playwright-cli close-all

playwright-cli vs Browser-Use decision rule

• Know the exact steps? → playwright-cli (scripted, inspectable, network/console visible)
• Describe a goal and let Claude figure out the steps? → Browser-Use MCP

Sample Prompts

Quick health check:

Open localhost:4200, check for any console errors or failed network requests

Scripted login test:

Use playwright-cli to test the login flow at localhost:4200/login — fill the form,
submit, check network for POST /api/auth/login → 200, take a screenshot of the result

Autonomous flow:

Use Browser-Use to sign up at localhost:4200/signup with a test email and confirm
the welcome email screen appears

Performance trace:

Run a playwright-cli tracing-start/stop on localhost:4200, then open the trace
to identify render-blocking resources

Claude automatically picks the right tool based on the task. See .claude/skills/browser-testing/SKILL.md and .claude/agents/browser-testing.md for the full workflow guide.

Verify Maestro MCP

maestro mcp          # should start without error (Ctrl+C to exit)
maestro list-devices # confirm simulator/emulator visibility

16. iOS App Store Release Pipeline

Flutter developers build the app — but the journey doesn't end at the IPA. This section covers the full pipeline from Xcode build to App Store review, powered by two complementary tools in this kit.

How the Tools Fit Together

Flutter Development          XcodeBuildMCP                  ASC Skills
──────────────────           ──────────────────             ───────────────────────────
Write Dart/Flutter code  ->  Build iOS project         ->  Upload IPA to App Store Connect
flutter build ios        ->  Archive & export IPA       ->  Distribute to TestFlight groups
Riverpod + Freezed       ->  Debug on simulator         ->  Submit to App Store review
Widget tests             ->  Capture screenshots        ->  Monitor review status
                         ->  Inspect signing config     ->  Triage crash reports

XcodeBuildMCP (xcodebuild in .mcp.json) handles everything that requires a live Xcode environment: building, archiving, running on simulator, attaching a debugger, and capturing logs.

ASC Skills handle everything that happens after the IPA is built: uploading, TestFlight distribution, signing asset management, App Store submission, and post-release monitoring.

Step 1 — Build the IPA (XcodeBuildMCP)

The xcodebuild MCP server executes these steps natively. Load the flutter-mobile skill and use XcodeBuildMCP tools:

1. discover_projs -> finds ios/Runner.xcworkspace
2. list_schemes   -> identifies the Runner scheme
3. build_sim      -> builds for simulator (development)
4. build_run_sim  -> builds + launches on simulator
5. show_build_settings -> verifies signing config

For a release build that produces an IPA for upload:

# Run once to generate Xcode project and Pods
flutter build ios --release

# XcodeBuildMCP then handles archive + export
# (or use xcodebuild directly via asc-xcode-build skill)

Step 2 — Set Up Signing (asc-signing-setup skill)

Before uploading, ensure signing assets are in place:

asc bundle-ids list --paginate
asc certificates list --certificate-type IOS_DISTRIBUTION
asc profiles create --name "AppStore Profile" --profile-type IOS_APP_STORE \
  --bundle "BUNDLE_ID" --certificate "CERT_ID"
asc profiles download --id "PROFILE_ID" --output "./profiles/"

Load skill: .claude/skills/asc-signing-setup/

Step 3 — Upload & Distribute (asc-release-flow skill)

# Preferred: single command for TestFlight
asc publish testflight --app APP_ID --ipa ./build/ios/ipa/MyApp.ipa --group GROUP_ID --wait

# Preferred: single command for App Store
asc publish appstore --app APP_ID --ipa ./build/ios/ipa/MyApp.ipa --version 1.2.3 --wait --submit --confirm

Load skill: .claude/skills/asc-release-flow/

Step 4 — Manage Beta (asc-testflight-orchestration skill)

asc testflight beta-groups list --app APP_ID --paginate
asc testflight beta-testers add --app APP_ID --email tester@example.com --group "Beta"
asc builds add-groups --build BUILD_ID --group GROUP_ID
asc builds test-notes create --build BUILD_ID --locale en-US --whats-new "Bug fixes"

Load skill: .claude/skills/asc-testflight-orchestration/

Step 5 — Preflight & Submit (asc-submission-health skill)

Run all 7 preflight checks before submitting. See reference/submission-preflight-checklist.md for the full checklist.

asc builds info --build BUILD_ID                        # Must be VALID
asc encryption declarations list --app APP_ID           # Must exist + assigned
asc submit create --app APP_ID --version 1.2.3 --build BUILD_ID --confirm
asc submit status --id SUBMISSION_ID

Load skill: .claude/skills/asc-submission-health/

Step 6 — Monitor & Triage (asc-crash-triage skill)

After release, monitor crashes and beta feedback:

asc crashes --app APP_ID --sort -createdDate --limit 10
asc feedback --app APP_ID --sort -createdDate --limit 10
asc performance diagnostics list --build BUILD_ID

Load skill: .claude/skills/asc-crash-triage/

ASC Skills in This Kit

These skills were adapted from the open-source app-store-connect-cli-skills repository by @rudrankriyam, and enhanced to match this kit's skill standards (Iron Law, progressive disclosure, metadata blocks, Documentation Sources).

Prerequisites

# Install the asc CLI
brew install rudrankriyam/tap/app-store-connect-cli

# Authenticate (keychain — recommended)
asc auth login

# Or set environment variables
export ASC_KEY_ID="your-key-id"
export ASC_ISSUER_ID="your-issuer-id"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"

Example Prompts

Copy any of these directly into Claude Code to trigger the iOS release skills:

Upload & TestFlight distribution

Upload the IPA at ./build/ios/ipa/MyApp.ipa to TestFlight for app APP_ID and distribute it to the "Internal Testers" group.

Full App Store release

Run all preflight submission checks for my iOS app APP_ID version 2.1.0, then submit it to App Store review.

Signing setup

Create a new App Store distribution certificate and provisioning profile for bundle ID com.example.myapp on iOS.

Check review status

What is the current App Store review status for my app APP_ID? Show me if there are any active submissions.

Crash triage

Show me the top 10 TestFlight crash reports for app APP_ID sorted by most recent, grouped by crash signature.

Resolve IDs

Find the app ID, latest build ID, and Internal Testers group ID for my app with bundle ID com.example.myapp.

Rotate expired certificate

My iOS distribution certificate is expiring. Check what exists, revoke the old one, and create a new certificate and provisioning profile for com.example.myapp.

TestFlight What to Test notes

Set the What to Test notes for build BUILD_ID in en-US locale to "Fixed login crash on iOS 18. Please test the onboarding flow."

Skills used by these prompts: asc-cli-usage → asc-id-resolver → asc-signing-setup → asc-release-flow → asc-testflight-orchestration → asc-submission-health → asc-crash-triage

Source: github.com/rudrankriyam/app-store-connect-cli-skills

17. Android Google Play Release Pipeline

Flutter developers build Android apps — but the journey doesn't end at the AAB. This section covers the full pipeline from Android build to Google Play production, powered by the GPD skills in this kit.

How the Tools Fit Together

Flutter Development          flutter CLI / Maestro MCP       GPD Skills
──────────────────           ──────────────────────────      ────────────────────────────────
Write Dart/Flutter code  →   Build Android AAB           →   Upload AAB to Google Play
flutter build appbundle  →   Run E2E tests (Maestro)     →   Release to internal/beta track
Riverpod + Freezed       →   Inspect on emulator         →   Staged rollout to production
Widget tests             →   Cross-platform E2E flows     →   Monitor vitals and reviews

Flutter CLI handles the Android build: flutter build appbundle produces the .aab file.

Maestro MCP (maestro in .mcp.json) runs cross-platform E2E test flows on Android emulator before release.

GPD Skills handle everything after the AAB is built: uploading to Google Play, track management, staged rollouts, submission health checks, and post-release monitoring.

Step 1 — Build the AAB (Flutter CLI)

# Build release AAB
flutter build appbundle --release

# Output: build/app/outputs/bundle/release/app-release.aab

Then run E2E flows on Android emulator via Maestro MCP before uploading.

Step 2 — Resolve IDs (gpd-id-resolver skill)

Before running any release commands, resolve your package name and track names:

gpd publish tracks --package com.example.app
gpd publish status --package com.example.app --track production

Load skill: .claude/skills/gpd-id-resolver/

Step 3 — Upload & Release (gpd-release-flow skill)

# Upload AAB to Google Play
gpd publish upload app.aab --package com.example.app

# Release to internal track
gpd publish release --package com.example.app --track internal --status completed

# Promote to beta
gpd publish promote --package com.example.app --from-track internal --to-track beta

# Staged rollout to production: 5% → 50% → 100%
gpd publish release --package com.example.app --track production --status inProgress --version-code 123
gpd publish rollout --package com.example.app --track production --percentage 5
gpd publish rollout --package com.example.app --track production --percentage 50
gpd publish rollout --package com.example.app --track production --percentage 100

Load skill: .claude/skills/gpd-release-flow/

Step 4 — Manage Beta Testers (gpd-betagroups skill)

gpd publish testers list --package com.example.app --track internal
gpd publish testers add --package com.example.app --track internal --group testers@example.com
gpd publish release --package com.example.app --track beta --status completed

Load skill: .claude/skills/gpd-betagroups/

Step 5 — Preflight Before Production (gpd-submission-health skill)

Run all 5 preflight checks before releasing to production. See reference/submission-preflight-checklist.md for full commands.

gpd publish edit validate EDIT_ID --package com.example.app   # Must pass
gpd publish status --package com.example.app --track production
gpd publish listing get --package com.example.app             # Metadata complete
gpd publish images list phoneScreenshots --package com.example.app --locale en-US

Load skill: .claude/skills/gpd-submission-health/

Step 6 — Monitor Build State (gpd-build-lifecycle skill)

gpd publish status --package com.example.app --track production
gpd publish tracks --package com.example.app

# Emergency: halt bad rollout
gpd publish halt --package com.example.app --track production --confirm
gpd publish rollback --package com.example.app --track production --confirm

Load skill: .claude/skills/gpd-build-lifecycle/

GPD Skills in This Kit

These skills were adapted from the open-source gpd-cli-skills repository by @rudrankriyam, and enhanced to match this kit's skill standards (Iron Law, progressive disclosure, metadata blocks, Documentation Sources).

Prerequisites

# Install the gpd CLI
brew install rudrankriyam/tap/google-play-developer-cli

# Set service account credentials
export GPD_SERVICE_ACCOUNT_KEY="/path/to/service-account.json"

# Validate access
gpd auth check --package com.example.app

Example Prompts

Copy any of these directly into Claude Code to trigger the Android release skills:

Upload AAB and release to internal track

Upload ./build/app/outputs/bundle/release/app-release.aab to Google Play for package com.example.myapp and release it to the internal testing track.

Staged rollout to production

Promote my app com.example.myapp from beta to production with a staged rollout — start at 5%, then 50%, then 100%.

Full preflight check before production

Run all preflight submission checks for com.example.myapp version code 123 before I release to the production track.

Add beta testers

Add tester@example.com to the internal testing track for com.example.myapp and distribute the latest build to them.

Check release status

What is the current release status of com.example.myapp on the production track? Show version code and rollout percentage.

Halt a bad rollout

Halt the production rollout for com.example.myapp immediately — there's a critical crash in the latest release.

Resolve IDs before release

List all available tracks and the current version codes for com.example.myapp on Google Play.

Manage store listing

Export the current Play Store listing for com.example.myapp to a local Fastlane metadata folder, then validate it.

Skills used by these prompts: gpd-cli-usage → gpd-id-resolver → gpd-build-lifecycle → gpd-release-flow → gpd-betagroups → gpd-submission-health

Source: github.com/rudrankriyam/gpd-cli-skills

16. Hands-On Exercises

Work through these exercises to get familiar with Claude Code. Each one uses different components from this kit. These exercises follow a deliberate progression to help you understand which component to use for and when:

Exercises 1–4 are independent — do them in any order based on your stack. Exercises 5+ build on concepts from earlier exercises, so work through them sequentially.

Exercise 1: Scaffold a Flutter Fitness App

Components used: Slash Command → Skill (auto) → Sub-agent

How it works: The slash command kicks off scaffolding. Based on task context, Claude automatically activates relevant skills and sub-agents as needed — you just keep prompting naturally.

> /scaffold-flutter-app fitness tracker

Then iterate:

> Add a workout logging feature with Firestore integration
> Create the database schema for tracking workouts, exercises, and user stats
> Add a dashboard screen showing weekly workout summary with charts

Exercise 2: Build a Weather REST API (Java)

Components used: Slash Command → Sub-agent → Skill (auto)

Scaffold first, then use the @java-spring-api agent for domain-specific implementation:

> /scaffold-spring-api weather-service
> @java-spring-api Add a WeatherController that accepts a city name and returns mock weather data with temperature, humidity, and condition
> Add integration tests for the weather endpoint

Exercise 3: Build a Todo API (NestJS)

Components used: Slash Command → Sub-agent

> /scaffold-nestjs-api todo-service
> @nestjs-api Add a Todo feature module with CRUD endpoints, Prisma model, DTO validation, and service
> Add Vitest integration tests for create and list endpoints
> Add a PATCH endpoint to mark todos as complete

Exercise 4: Build an Analytics API (Python)

Components used: Slash Command → Sub-agent

> /scaffold-python-api analytics-service
> @python-dev Add an async endpoint that accepts event data and stores it with timestamps
> Create a Pydantic model for events with type, payload, and metadata
> Add pytest tests for the event endpoints

Exercise 5: Design a Full-Stack E-Commerce System

Components used: Slash Command → Sub-agent → Skill (auto) → MCP Server

This exercise chains multiple components together — architecture design, database schema, API scaffolding, and implementation:

> /design-architecture An e-commerce platform with product catalog, shopping cart, checkout, and order tracking. Angular SPA for web, Flutter for mobile, Spring Boot backend.
> /design-database e-commerce platform with products, categories, users, orders, order items, payments, and shipping
> /scaffold-spring-api ecommerce-api
> @java-spring-api Create CRUD endpoints for Products with name, description, price, category, and image URL

Exercise 6: Pull Live Docs with Context7 (MCP)

Components used: MCP Server (Context7)

Append use context7 to any prompt to fetch up-to-date, version-specific documentation instead of relying on Claude's training data:

> Create a Spring Boot WebFlux endpoint that uses Spring Security with JWT. use context7
> Build an Angular component using the new Angular signals API. use context7
> Set up Firebase App Check in Flutter. use context7
> Create a FastAPI endpoint with async SQLAlchemy. use context7
> Create a NestJS guard with JWT validation using @nestjs/passport. use context7

Exercise 7: Design & Review Architecture

Components used: Sub-agents (@architect, @database-designer)

Use specialized agents for design and review tasks that benefit from isolated, focused context:

> @architect Review the current project structure and suggest improvements
> @architect Design a real-time notification system that works across Angular web and Flutter mobile using Firebase Cloud Messaging
> @database-designer Design the notification schema with PostgreSQL for persistence and Firestore for real-time delivery

Exercise 8: Build an AI Agent Service (Agentic AI)

Components used: Slash Command → Sub-agent → Skill (auto) → MCP Server

Scaffold a production AI agent service, then build out a ReAct agent with RAG and tools:

> /scaffold-agentic-ai research-agent
> @agentic-ai-dev Add a web search tool and a database query tool with Pydantic input validation
> @agentic-ai-dev Build an Agentic RAG system with query routing, document grading, and web search fallback
> @agentic-ai-dev Add guardrails — prompt injection detection, PII redaction, and output validation
> @agentic-ai-dev Write tests for the ReAct agent: basic invoke, tool usage, iteration limit, and error recovery

Then review your work:

> @agentic-ai-reviewer Review the agent service for graph correctness, safety, cost, and production readiness

Exercise 9: Domain-Driven Design with DDD Architect

Components used: Skill (ddd-architect) → Sub-agents (@architect, @database-designer)

Use the DDD Architect skill to decompose a complex domain into bounded contexts, aggregates, and integration patterns — then hand off to implementation agents:

> Perform a full DDD analysis for an online food delivery platform. The system handles restaurant menus, customer ordering, real-time delivery tracking, payments, ratings and reviews, and a loyalty program. Tech stack: Spring Boot microservices, Angular web, Flutter mobile, PostgreSQL, Firebase for real-time.

Claude activates the ddd-architect skill automatically and walks through strategic → tactical → technical phases. Follow up to drill deeper:

> Show me the context map with all integration patterns between Order, Delivery, and Payment contexts
> Design the Order aggregate with invariants — what rules must hold when placing, modifying, or cancelling an order?
> Which contexts should communicate via domain events vs. synchronous API calls? Justify each.
> Generate the implementation roadmap — which bounded contexts should we build first and why?

Then use the outputs to drive implementation:

> @database-designer Design the PostgreSQL schema for the Order bounded context based on the DDD tactical design
> @architect Design the event-driven integration between Order, Payment, and Delivery contexts using the context map

Exercise 10: Add a Feature End-to-End

Components used: Slash Command → all components in action

This is the real-world workflow — a single command that triggers scaffolding, skills, agents, and MCP servers working together:

> /add-feature User profile management — users can update their name, avatar, and preferences. Backend API + Angular settings page + Flutter profile screen

Exercise 11: Build an A2UI Renderer (Agent-to-User Interface)

Components used: Slash Command + Agent + Skill + MCP

A2UI is Google's declarative protocol (v0.8) that lets AI agents describe rich, interactive UIs as structured JSONL instead of generating executable code. The agent sends four message types (surfaceUpdate, dataModelUpdate, beginRendering, deleteSurface); your Angular app validates each component type against an approved catalog and renders it with native daisyUI components.

Official component types: Row, Column, Text, Image, Icon, Button, TextField, CheckBox, DateTimeInput, Card, Modal, Tabs, List. Components reference their children via {"explicitList": ["id1", "id2"]} and all text fields use typed value objects: {"literalString": "value"} or {"path": "/data/pointer"} for reactive data binding.

Scaffold with the slash command:

> /scaffold-a2ui travel-assistant

This creates a complete A2UI feature module: models (SurfaceState, A2UIMessage, A2UIAgentAction), catalog service, sanitizer, recursive renderer, agent service (REST + SSE/JSONL), chat page, routes, and tests.

Or use the specialist agent for custom work:

> @a2ui-angular Build an A2UI renderer that supports flight cards, hotel listings, and booking forms. The agent backend is at /api/travel/chat and streams via SSE as JSONL.

> @a2ui-angular Add a "table" component type (Angular extension, not in core spec) to our existing A2UI catalog and renderer. Use daisyUI table classes.

> @a2ui-angular Review our A2UI renderer for security issues — make sure all component types are validated against the catalog allowlist and property values use the literalString/path format.

Key concept: A2UI payloads are untrusted. Every component type from the agent is validated against a client-side catalog allowlist before rendering. Unknown types are silently skipped. Agent-provided code is never executed. Actions use a structured format {"name": "...", "context": [...]} — never executable strings.

Exercise 12: Build a Google ADK Agent Service

Components used: Slash Command + Agent + Skill + MCP (Context7)

Google ADK (Agent Development Kit) is Google's framework for building Gemini-powered agents. Unlike LangGraph's graph-based state machines, ADK uses composable agent primitives: SequentialAgent for pipelines, ParallelAgent for concurrent analysis, LoopAgent for iterative refinement, and transfer_to_agent for multi-agent routing. Tools are plain Python functions — no decorators needed.

Scaffold a new ADK service with the slash command:

> /scaffold-google-adk travel-agent

This creates a complete ADK project: Agent with gemini-2.5-flash, FunctionTool examples, InMemorySessionService, FastAPI /chat and /stream (SSE) endpoints, InMemoryRunner-based tests, .env template, and Dockerfile.

Or build directly with the specialist agent:

> @google-adk Build a research pipeline using SequentialAgent: researcher → writer → editor. Each agent should pass its output via output_key so the next stage can read it from session state.

> @google-adk Add a ParallelAgent that runs technical_analyst, market_analyst, and risk_analyst concurrently. Wire it into a SequentialAgent so a synthesizer receives all three analyses and produces a final report.

> @google-adk Expose the agent via FastAPI — POST /chat returns the final response, GET /stream returns SSE. Use InMemorySessionService. Close the runner in the lifespan shutdown.

> @google-adk Add a before_model_callback to enforce rate limiting (max 100 calls per session) and an on_tool_error_callback that returns a structured error dict instead of raising.

> @google-adk Write tests for the pipeline using InMemoryRunner — basic response, tool invoked, output_key passed between agents, LoopAgent exits within max_iterations, FastAPI /chat returns 200.

Key concepts:

• Tools are plain Python functions — full docstring (Args + Returns) required for schema auto-generation
• ToolContext is auto-injected when typed tool_context: ToolContext — access session state via tool_context.state
• output_key="key" stores an agent's final output into session state; downstream agents read it as {key} in instruction
• InMemoryRunner for tests — never call real Gemini API in unit tests
• Always await runner.close() in FastAPI lifespan shutdown to release MCP connections

Review your work:

> @agentic-ai-reviewer Review the ADK agent service for correctness, safety guardrails, and production readiness
> @security-reviewer Check tool input validation and session state handling in the ADK service

What's Next?

You've used every component in the kit — agents, skills, commands, hooks, and MCP servers. Now apply it to your own project:

1. Copy the config into your project (Option B from Section 2):

   cp -r .claude/ your-project/.claude/
   cp CLAUDE.md your-project/
   cp .mcp.json your-project/
   

2. Trim what you don't need — remove agents, skills, and commands for stacks you don't use. See Removing Components You Don't Need in the Customization section
3. Write your own CLAUDE.md — replace the tech stack, conventions, and rules with your project's. See Writing a Good CLAUDE.md for principles
4. Set up credentials — copy .env.example to .env, configure MCP server tokens as environment variables
5. Verify — run Claude Code and check that everything loads:

   > /project-status
   > /mcp
   > What agents and skills are available?
   

6. Iterate — your CLAUDE.md and skills will evolve as you discover what works for your team. Treat them like living documentation — PR-reviewed and version-controlled

17. Development Workflow — Putting It All Together

You've learned each component individually. Here's how they work together across a real development lifecycle. Every phase uses the same interaction model: slash commands trigger, agents execute, skills supply knowledge, MCP servers provide ground truth, hooks guard, and rules enforce — the mix just shifts per phase.

How Components Interact

No component works alone. Slash commands without agents are just prompts. Agents without skills lose institutional knowledge. Skills without MCP servers drift to outdated patterns. Code without hooks skips safety checks.

Phase 1: Design & Architecture

Start with slash commands to establish boundaries, then iterate with agents and skills.

Slash commands set the foundation: produces DDD artifacts, Architectural diagrams, API contracts, and ADRs. Generates Database design, ERDs. These commands give you a concrete artifact to iterate on rather than vague conversation.

Agents refine the design: Challenges assumptions, identifies missing NFRs, normalizes schemas, choice of database, tech stack and proposes deployment topology. You go back and forth until the design is solid.

Skills activate silently by Claude based on context and task type and feeds the right templates and patterns into every response without you asking.

MCP servers ground designs in reality — context7 checks current tech stack and framework capabilities so your architecture doesn't depend on deprecated APIs.

Rules (always loaded) enforce behaviors across all phases: no silent failures, surface assumptions before coding, verify before claiming "done."

This is one example mix — swap components to match your team's stack and workflow.

Phase 2: Scaffold & Bootstrap

Slash commands generate the project skeleton to your team's standards. Slash commands like /scaffold-nestjs-api, /scaffold-angular-app, /scaffold-flutter-app — each one produces a buildable project with your design artifacts (Phase 1) and conventions baked in (folder structure, config, dependencies, sample endpoint, test). Each scaffold command delegates to a stack-specific agent backed by coding-standard skills, so the generated code follows your conventions from line one.

Hooks are already active: pre-edit-protect-sensitive.sh blocks accidental edits to lock files and credentials during setup.

Verify immediately: run the build command (mvn verify, ng build, flutter build) before moving on. Never trust scaffold output blindly.

Phase 3: Feature Development

This is where agents and skills do the heavy lifting.

Agents bring stack-specific expertise: @java-spring-api for backend endpoints, @angular-spa for UI components, @flutter-mobile for mobile screens. Each agent runs as a focused sub-task with its own context, so it doesn't consume your main conversation window. You can run multiple agents in parallel — backend and frontend simultaneously.

Skills auto-activate based on what you're touching. Edit a .dart file and flutter-mobile + riverpod-patterns kick in. Touch a Spring controller and java-spring-api + java-coding-standard apply. You don't invoke them — they just work.

MCP servers connect to external tools as needed: context7 for live docs (append use context7 to any prompt), dart-mcp-server for Flutter tooling, postgres for schema queries, github for PR creation.

Hooks run automatically on every edit: post-edit-format.sh auto-formats your code (Prettier for TS, dart format for Dart, ruff for Python), pre-bash-guard.sh blocks destructive commands before they execute.

Tip: Append use context7 to any prompt to force live documentation lookup — this prevents deprecated API usage before it happens.

Phase 4: Review & Enforce Quality

Slash commands trigger multi-agent reviews; hooks catch what slips through.

/review-code auto-detects the stack and delegates to the right reviewer (spring-reactive-reviewer, nestjs-reviewer, agentic-ai-reviewer, riverpod-reviewer). /audit-security runs security-reviewer across the scope. /status-check gives you an honest binary works/broken report — no "95% done" hedging.

Hooks run automatically and act as deterministic guardrails you never have to think about:

• post-edit-format.sh — auto-formats after every edit
• pre-bash-guard.sh — blocks rm -rf, force pushes, DROP DATABASE
• pre-edit-protect-sensitive.sh — blocks edits to .env, credentials, private keys
• stop-secret-scan.sh — scans for leaked keys at session end

Every commands and hook below is customizable — add, remove, or replace them to fit your review process.

/audit-skills scans all 107 skills and outputs a PASS/WARN/FAIL report across 7 dimensions: Iron Law presence, last-reviewed staleness (WARN at 90 days, FAIL at 180), description quality, allowed-tools declaration, body line count, reference directory existence, and name/directory match. Run it monthly or after adding a batch of new skills to catch drift before it affects code generation quality.

Before Opening a PR — Two Commands, Always in This Order

These are manual — run them yourself before pushing.

/pr-risk [main..HEAD]   # 1st — quantitative risk score across 5 dimensions
/review-pr              # 2nd — 6-role qualitative review by specialist agents

/pr-risk runs git commands and scores the diff across: size, complexity, test coverage, dependency changes, and security-sensitive files. Output is a scored table (0–10 per factor) plus a risk level:

• 🟢 Low — open the PR
• 🟡 Medium — fix the flagged drivers first, then open
• 🟠 High / 🔴 Critical — split the PR or get a second reviewer before touching GitHub

/review-pr dispatches 6 specialist agents in parallel: comment accuracy, test coverage gaps, silent failures, type design, code quality, and unnecessary complexity. Findings are aggregated by severity — CRITICAL / IMPORTANT / SUGGESTIONS.

Run /pr-risk first. If the score is High or Critical, fix the structural issues before spending 6 agents on a review that will change anyway.

After Opening a PR — Autonomous CI + Feedback Loop

/iterate-pr          # current branch PR
/iterate-pr 123      # specific PR number

/iterate-pr runs a continuous loop until all checks are green:

1. Fetches review feedback and classifies it by LOGAF scale — auto-fixes high/medium, asks you about low
2. Polls CI via gh; for each failure reads the actual log snippet and traces the root cause
3. Fixes, verifies locally, commits, pushes — restarting the CI run
4. Repeats until all checks pass and no unaddressed high/medium feedback remains

It also posts reply comments on inline review threads (via GitHub GraphQL) so reviewers see what was changed.

Trigger naturally: Say "fix the CI failures" or "address the review comments" — Claude auto-activates the skill without the slash command.

When not to use: Before a PR exists (use /pr-risk + /review-pr first), or when failures are infrastructure-level flakiness that code changes can't fix.

Phase 5: Evolve Your Setup

Over time, customize everything based on what you learn.

• Add skills when you see recurring patterns Claude keeps getting wrong
• Add agents when a domain needs specialized expertise beyond what existing agents cover
• Add slash commands for workflows your team repeats often
• Add hooks for rules that must be enforced deterministically (no human memory required)
• Remove components you don't use — fewer MCP servers and skills means more context budget for actual work

The setup is a living product. Treat it like code: version-controlled, PR-reviewed, continuously improved.

17a. AI-DLC — Full Development Lifecycle Workflow (Optional)

Credit: Adapted from awslabs/aidlc-workflows by AWS Labs — an open-source AI-assisted development methodology originally built for Amazon Q Developer, Cursor, Cline, and Kiro IDE.

For non-trivial features, /aidlc gives Claude a structured, approval-gated development lifecycle instead of jumping straight to code.

> /aidlc

How It Works

AI-DLC runs three phases — Inception (plan), Construction (build), Operations (future):

Inception gathers requirements, writes user stories, and plans which stages to run. Construction works through each unit of work: functional design → NFR requirements → infrastructure design → code generation. Every phase ends with an explicit approval gate — Claude won't advance until you confirm.

The workflow is adaptive: a simple bug fix skips most stages and goes straight to code. A new multi-service feature runs the full lifecycle. Claude proposes the execution plan at the Workflow Planning gate and you can override any stage.

An append-only aidlc-docs/audit.md logs every interaction verbatim with ISO timestamps. aidlc-docs/aidlc-state.md tracks stage progress so sessions resume exactly where they left off.

How It Fits With This Kit

/aidlc doesn't replace skills, agents, or rules — it orchestrates on top of them. CLAUDE.md project constraints always win. During Construction, the same stack agents and skills this kit ships with are activated per stage — architect for design, security-reviewer for NFR, the appropriate stack agent (flutter-mobile, nestjs-api, etc.) for code generation.

Two opt-in extensions ship in .aidlc-rule-details/extensions/:

• security/baseline — enforces security constraints at every construction stage
• testing/property-based — adds property-based testing patterns to code generation

Full reference: docs/workflows/aidlc.md

18. Security Considerations

Before using Claude Code with real projects, understand the security boundaries.

What Goes to Anthropic's API

Every prompt, file content pulled via @file references, and tool outputs are sent to Anthropic's API for processing. This means:

• Never paste real API keys, passwords, or tokens into prompts — they'll be transmitted to Anthropic's servers
• Be cautious with @file references to sensitive files — the file contents are sent as part of the prompt
• Tool outputs (Bash, Read, etc.) are included in context — if a command outputs secrets, they're sent too

MCP Server Credentials

MCP servers like postgres and github require connection strings or tokens. Handle these safely:

# ✅ GOOD — credentials from environment variables
# .mcp.json
"args": ["${POSTGRES_CONNECTION_STRING}"]

# ❌ BAD — credentials hardcoded in .mcp.json
"args": ["postgresql://admin:password123@localhost:5432/mydb"]

Always use environment variable references (${VAR_NAME}) in .mcp.json — never hardcode credentials.

The --dangerously-skip-permissions Flag

This flag disables all permission prompts. Rules for safe usage:

Pre-configured Guardrails in This Kit

This repo includes Claude Code hooks (.claude/hooks/) and a git pre-commit hook (.git/hooks/pre-commit) that enforce security automatically:

Claude Code hooks — fire on Claude Code lifecycle events:

Git pre-commit hook — fires on every git commit, before the commit is created:

The git hook is the last line of defence before secrets enter git history. It complements stop-secret-scan.sh (which catches secrets in Claude's output) by catching secrets in your own edits.

# Install (one-time, after cloning):
cp git-hooks/pre-commit-secrets.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# The hook then runs automatically on every git commit.
# To bypass in an emergency (use with caution):
git commit --no-verify

# To add a false-positive to the allowlist, edit the WHITELIST array in:
git-hooks/pre-commit-secrets.sh   # source (committed)
.git/hooks/pre-commit             # active copy (re-copy after editing)

These hooks are defense-in-depth — they catch mistakes but aren't a substitute for proper secret management. Always use a secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI) for production credentials.

Security Superpowers — AI-Assisted Security Tooling

Beyond the passive guardrails above, this kit ships dedicated security commands, a threat-modeling agent, and SAST skills — adapted from claude-skill-samples/security/ and tailored to the onboarding stack (Java/Spring, NestJS, Python, Angular, Flutter):

Typical security workflow:

Checklist Before Using Claude Code on a Real Project

• No real secrets in .mcp.json — all use ${ENV_VAR} references
• .env files are in .gitignore
• settings.json denies access to credential files (pre-configured in this kit)
• Team members understand what gets sent to Anthropic's API
• CI/CD pipelines do NOT use --dangerously-skip-permissions
• Hook scripts are executable (chmod +x .claude/hooks/*.sh)

19. CI/CD Automation — Deployment Engineer Agent

The deployment-engineer agent generates production-ready GitHub Actions pipelines for every service in this stack. It knows your exact tech versions, branching model (feature/* → develop → main), and pipeline architecture — no generic templates.

Triggers automatically when you mention CI/CD, Docker builds, Cloud Run, Flutter builds, or Firebase deployments. Or invoke directly with @deployment-engineer.

What it covers

All pipelines include: Docker layer caching (~60% faster builds), Trivy CVE scanning (hard-fail on CRITICAL), Workload Identity Federation (no JSON keys in secrets), health check post-deploy, and production approval gate.

Example prompts

Set up GitHub Actions CI/CD for our NestJS payments service to deploy to Cloud Run

Create a Flutter build pipeline — APK to QA via Firebase App Distribution on develop merge

Add Trivy vulnerability scanning to our Python API Docker build

Configure Cloud Run for our LangGraph agent with correct memory and timeout settings

Set up Prisma migrate deploy as a step before NestJS Cloud Run revision goes live

Automate Firestore security rules deployment on every merge to develop

Configure Workload Identity Federation — remove the JSON service account key from our secrets

Your pipeline at a glance

PR merged to develop
  ├── Flutter:     test → APK build → Firebase App Distribution (QA team notified)
  ├── Python API:  Docker build → Trivy scan → Cloud Run staging
  ├── NestJS API:  Docker build → Trivy scan → Cloud Run staging
  └── Firestore:   rules + indexes → Firebase staging project

QA signs off → merge develop to main
  ├── Flutter:     APK + IPA → Google Play / App Store (Fastlane)
  ├── Python API:  Cloud Run production  ← approval gate
  ├── NestJS API:  Cloud Run production  ← approval gate
  ├── Spring Boot: Cloud Run production  ← approval gate
  └── Firestore:   Firebase production project

19b. GCP Infrastructure — Terraform Specialist Agent

The terraform-specialist agent provisions and manages all GCP infrastructure as code. It handles what the deployment-engineer doesn't — creating the platform your services run on.

Rule of thumb: terraform-specialist runs once (or when infra changes). deployment-engineer runs on every merge.

terraform-specialist          deployment-engineer
─────────────────────────────────────────────────
Creates Cloud Run service  →  Deploys image to it
Creates Artifact Registry  →  Pushes Docker images
Creates Secret Manager     →  Reads secrets at runtime
Sets up Workload Identity  →  Uses it in CI pipeline
Runs rarely                   Runs on every PR merge

What it provisions for your stack

Example prompts

Provision complete GCP infra for our project — Cloud Run services, Artifact Registry,
Cloud SQL, Secret Manager, Workload Identity, GCS state bucket, staging + prod tfvars

Create a reusable Terraform module for Cloud Run used by all our services

Set up Workload Identity Federation so GitHub Actions deploys without JSON keys

Configure Cloud Run for our LangGraph agent with 4Gi memory and 300s timeout

Import our existing Cloud Run services into Terraform state management

Add tfsec and Checkov security scanning to our Terraform CI pipeline

The only workflow you need

terraform init
terraform workspace new staging        # or: select staging
terraform plan -var-file=staging.tfvars   # always review before apply
terraform apply -var-file=staging.tfvars

If plan shows # will be destroyed on Cloud SQL or Cloud Run — stop and ask the agent why before applying.

20. Customizing the Kit

This kit is a starting point — customize it for your team's stack and workflows.

Adding a New Agent

Create a file in .claude/agents/ with YAML frontmatter:

---
name: my-agent
description: One-line description of when to use this agent. Claude reads this to decide when to activate it.
model: sonnet
tools: Bash, Read, Write, Edit, Glob, Grep
skills:
  - my-related-skill
---

# My Agent Name

You are a [role] specializing in [domain].

## Your Responsibilities
1. First responsibility
2. Second responsibility

## How to Work
1. Read the `my-related-skill` skill before writing code
2. Follow [specific conventions]

## Key Rules
- Rule 1
- Rule 2

Usage: @my-agent Do something specific

Adding a New Slash Command

Create a file in .claude/commands/ with YAML frontmatter:

---
description: What this command does (shown in /help)
argument-hint: "[parameter description]"
allowed-tools: Bash, Read, Write, Edit
---

# Command Title

**Input:** $ARGUMENTS

## Steps
1. First step — explain what to do
2. Second step — reference skills or agents if needed
3. Final step — verify and report

Use the `my-skill` skill for patterns and templates.

Usage: /my-command some argument here

Key notes:

• $ARGUMENTS is replaced with whatever the user types after the command name
• argument-hint shows up in autocomplete to guide the user
• allowed-tools restricts which tools the command can use
• Add disable-model-invocation: true to prevent the command from using sub-agents

Adding a New Skill

Create a directory in .claude/skills/ with a SKILL.md file:

.claude/skills/my-skill/
├── SKILL.md                    # Entry point (keep under 5KB)
└── reference/                  # Detailed docs loaded on-demand
    ├── templates.md            # Code templates
    ├── patterns.md             # Design patterns
    └── troubleshooting.md      # Common issues and fixes

SKILL.md structure:

---
name: my-skill
description: |
  Use this skill when the user asks about [domain].
  Triggers: [list of keywords or contexts that activate this skill].
---

# My Skill

## Overview
What this skill covers and when it applies.

## Quick Reference
| Task | Pattern |
|------|---------|
| Common task 1 | Brief pattern |
| Common task 2 | Brief pattern |

## Detailed References
When working on [specific task]:
→ Read `reference/templates.md` for code templates

When troubleshooting:
→ Read `reference/troubleshooting.md`

Key notes:

• Keep SKILL.md under 5KB — it loads into context when activated
• Put detailed content in reference/ files — they load on-demand, saving tokens
• The description field is critical — Claude uses it to decide when to activate the skill
• Skills activate automatically based on context. Users don't invoke them directly

Adding a New Hook

1. Create the script in .claude/hooks/:

#!/usr/bin/env bash
# Brief description of what this hook does
set -uo pipefail

# Read tool input from stdin
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // ""' 2>/dev/null) || file=""

# Your logic here
# Exit 0 = allow/pass, Exit 2 = block (message via stderr)

exit 0

2. Make it executable:

chmod +x .claude/hooks/my-hook.sh

3. Register it in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Hook events and matchers:

Removing Components You Don't Need

If your team doesn't use a particular stack, remove the corresponding files to reduce noise:

# Example: Remove Flutter-related components if you don't use Flutter
rm .claude/agents/flutter-mobile.md
rm .claude/agents/flutter-security-expert.md
rm .claude/agents/riverpod-reviewer.md
rm .claude/agents/accessibility-auditor.md
rm .claude/agents/ui-standards-expert.md
rm -rf .claude/skills/flutter-mobile/
rm -rf .claude/skills/riverpod-patterns/
rm -rf .claude/skills/ui-standards-tokens/
rm .claude/commands/scaffold-flutter-app.md

# Update CLAUDE.md to remove Flutter references from the tech stack table

Also disable unused MCP servers in .mcp.json by setting "disabled": true.

Version Update Guide

When a framework releases a new major version, update these files:

Process:

1. Update version numbers in the files above
2. Update any changed API patterns in skill reference/ files
3. Test with a scaffold command to verify the generated code compiles
4. Commit as docs: update [framework] to vX.Y

20. Claude Code Power Features

Keyboard Shortcuts (Inside Claude Code)

Essential CLI Flags

Core Tools

These are the built-in tools Claude Code can use during a session:

Permission Model

Claude Code uses an allow / deny / ask system. Common safe commands run without asking, sensitive files are blocked entirely, and everything else asks for confirmation.

Configure in .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(git status *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(rm *)",
      "Bash(curl *)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /)",
      "Read(./.env)",
      "Read(./**/*.key)"
    ]
  }
}

Permission rule patterns:

This repo's settings.json comes pre-configured with sensible defaults — see Settings Configuration in Section 10 for the full breakdown.

21. Tips & Best Practices

Prompting Best Practices

1. Be specific — The more context you give Claude, the better the output:

2. Use agents for focused work — @java-spring-api gives you a specialized backend expert instead of a generalist

3. Append use context7 to any prompt when you need current library docs — it fetches live documentation and prevents hallucinated APIs

4. Resume sessions — claude -c continues your last conversation, claude --resume lets you pick from recent sessions

5. Chain commands in one prompt — combine slash commands and natural language: /scaffold-spring-api order-service then @java-spring-api add CRUD for Orders with items, totals, and status

Common Pitfalls — Avoid These

These mistakes are common among new Claude Code users and waste significant time:

@ File References

Reference files directly in prompts with @ — Claude reads them into context automatically, which is more token-efficient than reading entire directories:

> Review @src/auth/login.ts for security issues
> Compare @src/api/v1/users.ts and @src/api/v2/users.ts — what changed?
> Generate tests for @src/utils/validator.ts
> This bug is in @src/services/auth.ts, check @logs/error.log for clues

Works in both regular prompts and slash command arguments. Reduces token usage compared to reading entire directories.

Context Window Management

Sonnet 4.6 and Opus 4.6 have a 1M token context window with automatic compaction (GA 2026-03-13, no long-context premium). Mismanaging context still degrades performance and output quality — a larger window just moves the problem further out.

Three principles for long sessions:

Full rules in .claude/rules/leverage-patterns.md §Context Window Management

Check your current state anytime:

> /mcp                  # MCP status and tool count
> /plugins              # Enabled plugins
> /statusline           # Context remaining %
> /context              # Context usage as a colored grid
> /cost                 # Token usage statistics

Parallel Workflows

Don't queue tasks — run them simultaneously:

Note sub-agents iscommonly used light-weight parallelism option — no git setup or terminal multiplexing needed, just spawn agents within the same session.

# Sub-agents — parallel specialists in one session
> @java-spring-api Build the auth endpoints
> @angular-spa Build the login page
> @database-designer Design the user schema
# Claude can run these concurrently without context collision

# /fork — branch the conversation
> /fork
# Fork 1: Add payment processing
# Fork 2: Add email notifications
# Each fork works independently in the same repo

# Git worktrees — parallel Claudes without conflicts
git worktree add ../feature-auth feature/auth
git worktree add ../feature-dashboard feature/dashboard
# Run separate `claude` instances in each directory

# tmux — monitor long-running tasks
tmux new -s dev
# Detach: Ctrl+B, D | Reattach: tmux attach -t dev

Team Collaboration Patterns

When multiple developers use Claude Code on the same codebase:

Shared vs Personal Configuration

Branch Collision Prevention

When two developers use Claude Code simultaneously on the same repo:

# Each developer works on their own feature branch
git checkout -b feature/alice-auth
git checkout -b feature/bob-dashboard

# For tasks that touch the same files, use git worktrees
git worktree add ../project-auth feature/alice-auth
git worktree add ../project-dashboard feature/bob-dashboard
# Run separate Claude Code instances in each worktree

Standardizing Team CLAUDE.md

To keep the team aligned:

1. Project-level CLAUDE.md — committed to git, contains stack info, conventions, commands. PR-reviewed like any other code change
2. Personal CLAUDE.local.md — each developer's preferences (model choice, verbosity, personal shortcuts). Never committed
3. Rules directory .claude/rules/ — committed to git. Breaking rules into files allows teams to own different areas (frontend team owns angular-rules.md, backend team owns spring-rules.md)

Onboarding a New Team Member

# 1. Clone the repo (CLAUDE.md, agents, skills, commands come with it)
git clone <repo-url> && cd <repo>

# 2. Copy the .env template and fill in personal credentials
cp .env.example .env
# Edit .env with your API keys

# 3. Make hooks executable
chmod +x .claude/hooks/*.sh

# 4. Start Claude Code and run the status check
claude
> /project-status

# 5. Try a scaffold exercise to verify everything works
> /scaffold-spring-api hello-world

Plugins Ecosystem

Beyond Claude-Mem, there's a growing plugin ecosystem. Plugins bundle tools, skills, agents, hooks, or MCP integrations for easy install.

# Install a plugin marketplace
> /plugin marketplace add <github-user/repo>

# Browse and install from /plugins menu
> /plugins

Sample plugins:

⚠️ Same context warning as MCPs — each enabled plugin adds tool definitions. Install many, enable few.

Skills — Best Practices

Keep skills lean:

• Target 3–5KB for the SKILL.md file
• If your skill exceeds 10KB, you're probably embedding too much documentation

Use lazy loading for large skills: Instead of embedding all documentation in SKILL.md, put detailed references in separate files and load them on-demand:

.claude/skills/my-skill/
├── SKILL.md                    # 3KB — routing logic only
└── reference/
    ├── use_case_1.md           # Loaded when needed
    ├── use_case_2.md           # Loaded when needed
    └── use_case_3.md           # Loaded when needed

In your SKILL.md, instruct Claude to load the right reference:

**When user asks about use case 1:**
  → Read reference/use_case_1.md, then proceed

This can reduce token usage by 80–95% for complex skills.

SKILL.md frontmatter:

---
name: my-skill                    # Required: hyphen-case, max 64 chars
description: |                    # Required: when to activate (max 1024 chars)
  This skill should be used when the user asks to...
allowed-tools: Read, Bash(npm:*)  # Optional: restrict available tools
---

Writing a Good CLAUDE.md

Your CLAUDE.md is the highest-leverage file in the entire setup — it goes into every session and shapes every task. A bad line here gets into every plan, every implementation, every artifact Claude produces. Invest time crafting it carefully.

The Basics: WHAT → WHY → HOW

Key Principles

Progressive Disclosure Example

Instead of a 500-line CLAUDE.md, keep it short and point to detail docs:

# CLAUDE.md

## Project
E-commerce platform — Spring Boot API + Angular SPA + Flutter mobile.

## Key Docs (read the relevant ones before starting a task)
- `docs/building.md` — how to build, run, and deploy each service
- `docs/testing.md` — test commands, fixtures, CI expectations
- `docs/database.md` — schema overview, migration workflow
- `docs/api-contracts.md` — OpenAPI specs and versioning rules
- `docs/code-conventions.md` — naming, structure, PR standards

## Universal Rules
- All code must pass `mvn verify` before committing
- Use conventional commits: feat|fix|docs|refactor(scope): message
- Never commit secrets or .env files

Quick Rules of Thumb

• < 300 lines or <40 KB is the general rule, shorter is better (some teams use < 60 lines)
• Most important rules go at the top and bottom — LLMs attend most to the start and end of context
• Use CLAUDE.local.md for personal preferences (auto-gitignored)
• Use .claude/rules/ for conditional rules scoped to specific directories

When Claude Ignores Its Rules

The Hard Truth: Why CLAUDE.md Isn't Enough CLAUDE.md and .claude/rules/ tell Claude how to behave — but they're guidance, not enforcement. Three deeply baked in biases from training cause Claude to break its own rules:

The fix: CLAUDE.md is prevention. The prompts below are treatment — copy-paste them when Claude misbehaves.

Start-of-Task Prompt

Paste this at the beginning of any non-trivial task to set expectations:

Before you start, confirm you understand:
1. VERIFY before claiming — read actual code, show file:line evidence
2. No flip-flopping — if you say "missing", verify first, don't change when I push back
3. Implement 100% of the plan — no skipping items
4. Modify existing files — don't create new ones without approval
5. No mock data, no silent errors — failures must be visible
6. Binary status: works or broken — no "95% done"

Say "understood" then proceed.

When Claude Guesses Instead of Verifying

Problem

You ask: "What's implemented so far?"
Claude says: "Auth service is done, payment module is missing"
You check: Auth service has no validations and no tests, payment module exists at src/payments/

WHY? Claude saw auth-service.ts and assumed it was complete.
It didn't see payments/ because it never opened the directory — it guessed from memory.

Solution: Paste below prompt

Before you tell me what's missing or implemented:
1. Actually READ the code files
2. For each claim, show file:line as evidence
3. Don't guess based on file names

If you can't point to specific code, say "I haven't verified this yet."

When Claude Flip-Flops

Problem

Claude says: "Feature X is missing"
You ask: "Are you sure?"  
Claude says: "Actually it IS implemented!"

WHY? Claude didn't actually check. It guessed, then agreed with you to avoid conflict.

Solution: Paste below prompt

STOP. You just flip-flopped.
First you said [X] was missing. Now you say it's implemented.
Which is it? Show me:
1. The exact file and line number
2. The actual code snippet

Don't guess. Don't agree with me to avoid conflict. VERIFY and show evidence.

When Challenging Claude's Analysis

Problem

Claude says: "The validation logic is missing"
You say: "I'm pretty sure it's there"
Claude says: "You're right, it is there!"

WHY? Claude wants to avoid conflict. Instead of re-reading the code,
it just agrees with whatever you say — even if its original claim was correct.

Solution: Paste below prompt

You said [X] is missing. Are you sure?
Don't just agree with me — RE-VERIFY by reading the actual code.
Show me the file you checked and what you found or didn't find.

22. Troubleshooting

command not found: claude

Your shell can't find the Claude binary. Add it to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Context too large" error

> /compact                          # Quick reset
> /compact "keep the auth work"     # Preserves specified context

Prevention: use /compact every ~50 operations in long sessions, or start a fresh session for new features.

Edit tool fails with "string not found"

Claude's Edit tool requires an exact string match including whitespace and indentation. Fix:

> Read the file again to see exact content

If the string appears multiple times, provide more surrounding context for uniqueness.

MCP server not connecting

Run /mcp to check status.

> /mcp

Check the status output. Common fixes:

• Ensure npx is available (requires Node.js)
• For GitHub MCP, set your token: export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token
• Restart Claude Code after changing .mcp.json
• On Windows, MCP servers need a cmd wrapper: "command": "cmd", "args": ["/c", "npx", "-y", "package-name"]

Claude isn't using skills or agents

• Verify the files exist: ls .claude/agents/ and ls .claude/skills/
• Check that each file has valid YAML frontmatter (--- delimiters)
• Try referencing explicitly: "Use the java-spring-api skill"

Background task not responding

> /tasks          # or /bashes — check status
> /kill <id>      # Stop the stuck task

Permission errors

Never use sudo with npm installs. Fix global permissions instead:

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Pre-configure allowed commands in .claude/settings.json to avoid repeated permission prompts.

Windows-Specific Setup

Hooks require a Bash shell. The .claude/hooks/*.sh scripts won't run natively on Windows. Options:

If using WSL 2:

# Install WSL 2 (from PowerShell as admin)
wsl --install

# Clone the repo inside WSL, not on /mnt/c/
cd ~ && git clone <repo-url>

# Run Claude Code from WSL
claude

MCP servers on Windows may need a cmd wrapper in .mcp.json:

"command": "cmd",
"args": ["/c", "npx", "-y", "package-name"]

Run diagnostics

When something isn't working and you're not sure why:

claude doctor              # General health check
claude --debug             # Full debug logging
claude --debug "mcp"       # Debug a specific category

23. Quick Reference Card

Print or bookmark this — it covers 90% of daily Claude Code usage.

Commands You'll Use Every Day

claude                              # Start session
claude --continue                   # Resume last session
claude --resume <name>              # Resume named session
/compact                            # Compress context (do this often)
/context                            # Check context usage
/cost                               # Token usage this session
/exit                               # End session

Scaffolding

/scaffold-spring-api <name>         # Java Spring Boot API
/scaffold-nestjs-api <name>         # NestJS API
/scaffold-python-api <name>         # Python FastAPI
/scaffold-angular-app <name>        # Angular SPA
/scaffold-flutter-app <name>        # Flutter mobile app
/scaffold-agentic-ai <name>         # AI Agent service

Design & Review

/design-architecture <description>  # System architecture with diagrams
/design-database <domain>           # Database schema with ERD + migrations
/pr-risk [main..HEAD]               # 1st — risk score before opening a PR
/review-pr [scope]                  # 2nd — 6-role qualitative review
/review-code [scope]                # Code review (auto-detects stack)
/audit-security [scope]             # Security vulnerability scan
/project-status                     # Codebase summary
/status-check                       # Binary works/broken report

Requirements & Feature Specs Skills (feature-forge)

Skill: .claude/skills/feature-forge/

What it is: A structured requirements gathering skill. Runs a PM + Dev dual-perspective interview before implementation starts, then produces a formal spec saved to specs/{feature}.spec.md.

Why use it: Most implementation mistakes are scoped-in at requirements time, not caught in code review. This skill forces structured elicitation — scope, NFRs, edge cases, and acceptance criteria — before the first line of code is written.

When to use it:

• Starting any new feature, before /scaffold-* commands
• When requirements are vague ("add payments", "improve search")
• When a PM or stakeholder has a feature request to formalise
• When you need a spec document to hand off to another team

How to use it: Say any trigger phrase — Claude runs the interview and produces a spec.

# Trigger phrases
"Define this feature"
"Gather requirements for X"
"Write a spec for X"
"Help me write user stories for X"
"What are the requirements for X?"

# 5-phase workflow
Discover   → AskUserQuestion: goal, target users, business value
Interview  → PM Hat (scope, priority, success metrics) + Dev Hat (security, performance, edge cases)
Document   → EARS-format functional requirements + Given/When/Then acceptance criteria
Validate   → Review spec with stakeholder, confirm scope and trade-offs
Plan       → Implementation checklist: backend, frontend, testing TODOs

# Output saved to
specs/{feature_name}.spec.md

Sample skill library adapted from jeffallan.github.io/claude-skills

Critical Reasoning Skills (the-fool)

Skill: .claude/skills/the-fool/

What it is: An adversarial reasoning skill that stress-tests plans, decisions, and designs using formal methodology — not gut-feel pushback.

Why use it: Most mistakes aren't caught in code review — they're baked in at the decision stage. This skill forces structured challenge before you commit to a design, technology choice, or architecture. It exposes hidden assumptions, failure modes, and weak evidence while there's still time to change course cheaply.

When to use it:

• Before finalising an architecture or tech stack choice
• Before shipping a feature or going live
• When a plan feels right but you want to be sure
• When a stakeholder pushes back and you need to stress-test your own position

How to use it: Say any trigger phrase — no slash command needed. Claude activates the skill and asks you to pick a reasoning mode.

# Say any of these to activate
"Play devil's advocate on this design"
"Pre-mortem this — we ship in 3 days"
"Red team my authentication flow"
"Poke holes in my microservices decision"
"Challenge this"  /  "Stress test this"  /  "What could go wrong?"
"Test my assumptions"

# Then pick a mode
Expose My Assumptions   → Surfaces what you're taking for granted (Socratic)
Argue the Other Side    → Steel-manned counter-argument + synthesis (Dialectic)
Find the Failure Modes  → Ranked failures with mitigations (Pre-mortem)
Attack This             → Adversary profiles, attack vectors, defenses (Red team)
Test the Evidence       → Are your conclusions actually supported? (Falsificationism)

Sample skill library adapted from jeffallan.github.io/claude-skills

Adversarial Plan Review (plan-challenger)

Agent: .claude/agents/plan-challenger.md

What it is: An Opus-powered read-only agent that attacks implementation plans across 5 dimensions — Assumptions, Missing Cases, Security, Architecture, and Complexity Creep — then tries to disprove each challenge before reporting. Only findings that survive self-scrutiny reach the report.

How it differs from the-fool: the-fool is conversational and works on any idea at any stage. plan-challenger is autonomous, plan-specific, reads the actual codebase to ground its claims, and has a built-in refutation step that eliminates false positives before you ever see them. Use the-fool to challenge a strategy; use plan-challenger to vet an implementation plan before coding starts.

Workflow:

1. Produce a plan          /plan-review  →  saved to docs/plans/YYYY-MM-DD-<feature>.md
2. Challenge the plan      Use the plan-challenger agent to review docs/plans/<plan-file>.md
3. Resolve blockers        Fix 🔴 Blockers before writing a line of code
                           Use architect or the-fool to explore alternatives if needed
4. Begin implementation    Only after blockers are resolved

When to use it:

• Before any multi-day implementation effort
• Before irreversible decisions: database schema, public API contract, auth architecture
• When the team can't agree on an approach — challenges surface hidden assumptions

Stack-aware: The agent includes targeted challenge questions for every stack in this kit — Java/WebFlux reactive chains, NestJS/Prisma N+1 risk, Python async/sync mixing, Angular Observable leaks, Flutter/Riverpod lifecycle mismatches, PostgreSQL migration reversibility, Firebase security rules.

# Invoke after saving an approved plan
Use the plan-challenger agent to review docs/plans/2026-03-08-payment-service.md

Security

/security-hardening [scope]         # Full-stack orchestrated hardening (10-step pipeline)
/security-sast [path]               # SAST — Bandit + Semgrep + ESLint + SpotBugs + dart analyze
/security-dependencies [path]       # CVE scan — npm / pip / Maven / pub.dev + SBOM
/xss-scan [path]                    # Angular XSS scan — bypassSecurityTrust*, innerHTML
/audit-security [scope]             # Full security audit (includes dep scan)
@threat-modeling-expert             # STRIDE threat model before any new design

Git Housekeeping

/worktree-sync                      # Sync worktrees for all open PRs (parallel work)
/worktree-sync --new <branch>       # New branch + isolated worktree in one step
/branch-cleanup --dry-run           # Preview stale/merged branches to delete
/branch-cleanup                     # Interactive cleanup (confirm each deletion)
/branch-cleanup --force             # Delete all merged branches without prompts

Hookify — Custom Rules

/hookify <describe behavior>        # Create a rule from plain English description
/hookify                            # Scan conversation for behaviors to prevent
/hookify-list                       # Show all rules and enabled/disabled status
/hookify-configure                  # Interactive toggle — enable or disable rules

Agents (use @name)

@java-spring-api                    # Spring Boot backend expert
@nestjs-api                         # NestJS backend expert
@python-dev                         # Python / FastAPI expert
@angular-spa                        # Angular frontend expert
@flutter-mobile                     # Flutter mobile expert
@agentic-ai-dev                     # AI agent builder
@architect                          # Solution architecture
@database-designer                  # PostgreSQL + Firestore
@security-reviewer                  # Security audit
@code-reviewer                      # General code review

Keyboard Shortcuts

@filename                           # Reference a file in prompt
Tab                                 # Toggle thinking display
Shift+Enter                         # Multi-line input
Esc                                 # Cancel generation
Ctrl+U                              # Delete entire line
/clear                              # Clear conversation
/model                              # Switch model

MCP Tips

use context7                        # Append to any prompt for live docs
/mcp                                # Check MCP server status

24. Resources