# Claude Code Integration

This directory contains Claude Code skills and hooks for the Vibe-Coding workflow.

## Quick Setup

### Option A: Clone the Repository

```bash
# Clone the repo
git clone https://github.com/KhazP/vibe-coding-prompt-template.git
cd vibe-coding-prompt-template

# Start Claude Code
claude
```

### Option B: Install Individual Skills with npx

Install only the skills you need directly into any project:

```bash
# Install master orchestrator skill
npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-workflow

# Install all skills at once
npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-research
npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-prd
npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-techdesign
npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-agents
npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-build
```

> **Browse all skills:** [skills.sh/khazp/vibe-coding-prompt-template](https://skills.sh/khazp/vibe-coding-prompt-template)

That's it! The skills are automatically available.

## Available Skills

| Command | Description | Time | npx Install |
|---------|-------------|------|-------------|
| `/vibe-workflow` | Complete guided workflow from idea to MVP | Full | `npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-workflow` |
| `/vibe-research` | Deep research and market validation | 20 min | `npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-research` |
| `/vibe-prd` | Create Product Requirements Document | 15 min | `npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-prd` |
| `/vibe-techdesign` | Plan technical architecture | 15 min | `npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-techdesign` |
| `/vibe-agents` | Generate AGENTS.md and AI configs | 10 min | `npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-agents` |
| `/vibe-build` | Build your MVP following the plan | 1-3 hrs | `npx skills add https://github.com/khazp/vibe-coding-prompt-template --skill vibe-build` |

## Skill Details

### /vibe-workflow

**Master orchestrator** - Guides you through all 5 steps automatically.

```
> /vibe-workflow
```

Or just say: *"Help me build an MVP"*

The skill will:
1. Check your current progress
2. Identify which step you're on
3. Guide you through remaining steps
4. Track completion across sessions

### /vibe-research

**Market research and idea validation**

Triggers on:
- "research my idea"
- "validate my app"
- "help me start a new project"

Questions are tailored to your experience level:
- **Vibe-coder**: Simple, friendly questions
- **Developer**: Technical, detailed questions
- **In-between**: Balanced approach

Output: `docs/research-[AppName].md`

### /vibe-prd

**Product Requirements Document generator**

Triggers on:
- "create PRD"
- "define my product"
- "write requirements"

Creates a comprehensive PRD with:
- Product overview and goals
- User personas and journeys
- Feature prioritization (MoSCoW)
- Success metrics
- Design direction

Output: `docs/PRD-[AppName]-MVP.md`

### /vibe-techdesign

**Technical architecture planning**

Triggers on:
- "plan technical design"
- "choose tech stack"
- "how should I build this"

Helps you decide:
- Platform (web, mobile, desktop)
- Tech stack with alternatives
- Architecture pattern
- Deployment strategy
- Cost estimates

Output: `docs/TechDesign-[AppName]-MVP.md`

### /vibe-agents

**AI configuration generator**

Triggers on:
- "create AGENTS.md"
- "configure AI assistant"
- "generate agent files"

Creates:
- `AGENTS.md` - Master build plan
- `agent_docs/` - Detailed specifications
- Tool-specific configs (CLAUDE.md, GEMINI.md, `.cursor/rules/` or legacy `.cursorrules`, etc.)

### /vibe-build

**MVP builder**

Triggers on:
- "build my MVP"
- "start coding"
- "implement the project"

Follows Plan → Execute → Verify workflow:
1. Reads AGENTS.md for current phase
2. Proposes implementation plan
3. Builds one feature at a time
4. Tests after each feature
5. Updates progress in AGENTS.md

## Pre-configured Hooks

This project includes hooks that run automatically. They are defined in `.claude/settings.json`, which Claude Code loads on startup.

### PreToolUse Hooks

**File Protection** - Blocks accidental modifications to:
- `.env` files (secrets) — templates like `.env.example` stay editable
- `package-lock.json` (use npm instead)
- Anything inside the `.git/` directory

**Destructive Command Guard** - Blocks catastrophic commands (`rm -rf` at your root/home/project, `git clean -f`, recursive Windows/PowerShell deletes, SQL `DROP`/`TRUNCATE`). It is a safety net, not a sandbox.

### PostToolUse Hooks

**Auto-formatting** - After file edits:
- Runs Prettier on `.ts`, `.tsx`, `.js`, `.jsx` files (only when `node_modules/.bin/prettier` exists)

### Stop Hooks

**Git Status** - When Claude finishes:
- Runs `git status --porcelain` and prints modified files
- Reminds you to review changes before committing
- Shows "No uncommitted changes" if the working tree is clean

### Notification Hooks

**Desktop Notification** - When Claude needs your attention:
- Pops a native notification (Windows, macOS, or Linux) so you know to come back

## Hook Configuration

Hooks are defined in `.claude/settings.json`. To customize, edit that file:

```json
{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  }
}
```

### Disable Hooks

To disable all hooks temporarily, add this to `.claude/settings.json`:

```json
{
  "disableAllHooks": true
}
```

To disable a specific hook, remove its entry from the `hooks` object.

## Directory Structure

```
.claude/
├── README.md              # This file
├── settings.json          # Hook configuration (commit this)
├── settings.local.json    # Your local overrides (gitignored, do not commit)
└── skills/
    ├── vibe-research/
    │   └── SKILL.md
    ├── vibe-prd/
    │   └── SKILL.md
    ├── vibe-techdesign/
    │   └── SKILL.md
    ├── vibe-agents/
    │   └── SKILL.md
    ├── vibe-build/
    │   └── SKILL.md
    └── vibe-workflow/
        └── SKILL.md
```

## Customizing Skills

Skills are Markdown files with YAML frontmatter. To modify a skill:

1. Open the skill's `SKILL.md` file
2. Edit the frontmatter (name, description, tools)
3. Edit the instructions below the frontmatter
4. Changes take effect immediately

### Skill Frontmatter Options

```yaml
---
name: skill-name
description: When to use this skill
allowed-tools: Read, Write, Bash  # Restrict available tools
---
```

## Troubleshooting

### Session continuity first

If your build starts drifting, avoid opening a fresh empty chat. Re-anchor with:

1. `AGENTS.md` current phase
2. Last completed task
3. One short summary of pending tasks

### Skills not appearing

1. Check you're in the project directory
2. Run `claude --debug` to see loading errors
3. Verify SKILL.md files have valid YAML frontmatter

### Hooks not running

1. Check `.claude/settings.json` exists and contains a `hooks` object
2. Verify JSON syntax is valid
3. Run `claude --debug` to see hook loading errors

### Skill not triggering

The skill's `description` determines when it triggers. Include keywords users would naturally say:
- Good: "Use when user says 'create PRD' or 'define product requirements'"
- Bad: "PRD generation utility"

### Plugin/rules troubleshooting

If using plugin-enabled IDE workflows:

1. Confirm plugin/rules package is loaded
2. Confirm required tools are enabled
3. Retry with explicit instruction: "Read AGENTS.md first, then proceed"

### Model naming guidance

Prefer model family names in docs and examples (Claude Sonnet, Claude Opus, Gemini Pro, Gemini Flash) to reduce churn from provider version rotations.

## Contributing

To add a new skill:

1. Create directory: `.claude/skills/your-skill/`
2. Add `SKILL.md` with frontmatter and instructions
3. Test with `/your-skill`
4. Submit PR

## Resources

- [Claude Code Skills Documentation](https://docs.anthropic.com/en/docs/claude-code/skills)
- [Claude Code Hooks Documentation](https://docs.anthropic.com/en/docs/claude-code/hooks)
- [Vibe-Coding Workflow Guide](../README.md)