vibe-assistant

Turn ideas into structured, AI-executable task breakdowns for vibe coding.

Built with love in Auckland

What is this?

vibe-assistant enables "vibe coding" - going from a rough idea to a structured implementation plan that AI coding agents can execute one task at a time. It can either:

1. Create a PRD from scratch - Describe your idea, and vibe-assistant uses Claude to generate a full PRD with your feedback
2. Parse an existing PRD - Already have a PRD? Feed it in and get structured tasks

Either way, you get:

• Phased implementation roadmap with clear task dependencies
• Progress tracking via state.json
• Agent instruction files (CLAUDE.md, AGENTS.md)
• Slash commands for workflow (/next-task, /checkpoint, etc.)
• "Check before fixing" - prevents AI from wasting time on unimplemented features

Note: vibe-assistant generates planning documents and task breakdowns. Your PRD will include deployment recommendations (CI/CD, cloud providers, etc.), but actual deployment scripts are created during task implementation, not by this tool.

Before You Start

Option A: Let vibe-assistant create your PRD (recommended for new projects)

vibe-assistant create

This opens an editor where you describe your idea. Claude will generate a full PRD, ask for your feedback, and refine it until you're happy. Then it formats and parses it automatically.

Option B: Bring your own PRD

If you already have a PRD or prefer to write one manually, here's how to create a great one:

Step 1: Develop Your Idea with an LLM

Use any LLM (ChatGPT, Claude, Gemini, etc.) to flesh out your idea. Iterate multiple times until it's specific and complete.

Things to decide:

• Deployment: On-prem, AWS, Google Cloud, Vercel, etc.
• CI/CD: Fully automated pipelines? GitHub Actions? Manual deploys?
• Tech stack: Specific requirements, or let the AI recommend?
• Architecture: Monolith, microservices, serverless?
• Database: SQL, NoSQL, specific providers?

Just ask the LLM to write your PRD and keep refining it. Don't worry about formatting yet.

Step 2: Validate Your PRD

Start a new LLM session, paste your entire PRD, and ask:

"Assess this PRD for any gaps, inconsistencies, or missing features that should be included."

Repeat this as many times as needed. Each fresh session gives you unbiased feedback.

CRITICAL: Read your PRD yourself. Understand every section. You need to know what you're building.

Step 3: Format Your PRD

Once you're happy with the content, start another new session and format it using our template:

# If vibe-assistant is installed globally
cat $(npm root -g)/vibe-assistant/examples/prd-template.md

Paste the template into your LLM along with your PRD and ask it to reformat your PRD following the template structure.

Step 4: Run vibe-assistant

Save your formatted PRD to a file (e.g., requirements.md) and run:

vibe-assistant init

Quick Start

# Install globally
npm install -g vibe-assistant

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

# Option 1: Create a PRD from your idea
cd your-project
vibe-assistant create

# Option 2: Parse an existing PRD
vibe-assistant init

That's it! Claude generates everything your AI coding agent needs to get started.

What Gets Generated

your-project/
├── raw-prd.md                  <- Original PRD (if using create)
├── docs/
│   ├── prd/
│   │   ├── PRD.md              <- Task breakdown summary
│   │   ├── phases/
│   │   │   ├── phase-1.md      <- Detailed task breakdowns
│   │   │   ├── phase-2.md
│   │   │   └── ...
│   │   ├── research/           <- For research notes (initially empty)
│   │   └── architecture/       <- For architecture docs (initially empty)
│   └── progress/
│       ├── state.json          <- Machine-readable progress
│       └── phase-*-summary.md  <- Created via /checkpoint command
│
├── .claude/                    <- (if target: claude-code or both)
│   └── commands/
│       ├── next-task.md        <- Get next task
│       ├── checkpoint.md       <- Save progress
│       ├── phase-status.md     <- Show completion
│       └── check-issue.md      <- Bug vs not-implemented checker
│
├── CLAUDE.md                   <- (if target: claude-code or both)
└── AGENTS.md                   <- (if target: codex or both)

Want to see example output? Check the examples/sample-output/ directory for a complete example of generated files.

Commands

vibe-assistant create

Create a PRD from a rough project idea. This is the easiest way to get started.

vibe-assistant create

What happens:

1. Opens your editor to describe your project idea
2. Asks which AI agent you'll use (Claude Code, Codex, or both)
3. Asks how you want to deploy (see Deployment Strategies below)
4. Claude generates a comprehensive PRD with appropriate deployment tasks
5. Shows you a summary and asks for feedback
6. Refines the PRD based on your feedback (repeat until approved)
7. Formats the PRD and generates all task files

vibe-assistant init

Parse an existing PRD file into structured tasks.

vibe-assistant init

vibe-assistant status

Check your project's progress.

vibe-assistant status

Project Status

Current Phase: 2
Last Updated: 12/13/2025, 10:30 AM

Overall Progress:
  ████████░░░░░░░░░░░░ 40%
  8 completed, 1 in progress, 11 pending

vibe-assistant update

Re-parse a PRD or regenerate task files.

vibe-assistant update

Options:

• Re-parse PRD (preserves progress for matching task IDs)
• Regenerate from scratch

Deployment Strategies

When creating a PRD, vibe-assistant asks how you want to deploy your project. This ensures the generated tasks include appropriate CI/CD and infrastructure setup.

| Strategy | What's Included | |----------|-----------------| | Local only | Git for version control, no remote. Best for personal projects or learning. | | GitHub repository | GitHub remote, no automated deployment. Deploy manually or separately. | | GitHub + Cloud hosting | GitHub + Vercel/Netlify/Railway/etc. Auto-deploy on push. | | GitHub + AWS | Full AWS infrastructure with Terraform/CDK, staging environments, secrets management. | | GitHub + Google Cloud | Full GCP infrastructure with Terraform/CDK, staging environments. | | GitHub + Azure | Full Azure infrastructure with Terraform/CDK, staging environments. | | Self-hosted | Docker + docker-compose, deploy to VPS with nginx and SSL. |

Cloud Hosting Providers (for GitHub + Cloud)

When you choose "GitHub + Cloud hosting", you'll be asked which provider:

• Vercel - Recommended for Next.js/React apps
• Netlify - Great for static sites and JAMstack
• Railway - Good for full-stack with databases
• Render - Good all-rounder
• Fly.io - Good for global distribution

Infrastructure as Code (for AWS/GCP/Azure)

When you choose enterprise cloud (AWS/GCP/Azure), you'll be asked which IaC tool:

• Terraform - Recommended, cloud-agnostic
• AWS CDK / Pulumi - TypeScript-based, great for developers
• CloudFormation / ARM templates - Native to cloud provider
• None - Manual setup via cloud console

MCP Server Integration

vibe-assistant can run as an MCP (Model Context Protocol) server, allowing Claude Code to call it directly without shell commands.

Setup

Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json or via Claude Code settings):

{
  "mcpServers": {
    "vibe-assistant": {
      "command": "npx",
      "args": ["-y", "vibe-assistant-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "vibe-assistant": {
      "command": "vibe-assistant-mcp"
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | create_prd | Create a PRD from a project idea (with optional self-refinement) | | parse_prd | Parse a PRD file into structured tasks | | get_status | Get current project progress | | get_next_task | Get the next pending task (respects task dependencies) | | check_if_implemented | Check if an issue is a bug or not implemented |

MCP Tool Parameters

create_prd | Parameter | Type | Description | |-----------|------|-------------| | idea | string | Project idea or description (required) | | deployment_type | string | Required. One of: local, github-only, github-cloud, github-aws, github-gcp, github-azure, self-hosted | | cloud_provider | string | Cloud hosting provider (required if deployment_type is github-cloud). One of: vercel, netlify, railway, render, fly-io, other | | iac_tool | string | IaC tool (required if deployment_type is github-aws/gcp/azure). One of: terraform, cdk, pulumi, cloudformation, none | | project_name | string | Project name (auto-detected if not provided) | | project_dir | string | Project directory to write files to (defaults to current directory) | | refinement_passes | number | Number of AI self-refinement passes (default: 1). Higher values produce more polished PRDs. | | interactive | boolean | If true, returns PRD for user feedback instead of auto-refining (default: false) | | feedback | string | User feedback to refine an existing PRD (used with interactive mode) | | current_prd | string | Current PRD content to refine (used with interactive mode and feedback) |

Interactive Mode Flow:

1. Call create_prd with interactive: true to get initial PRD
2. Review the PRD and call again with feedback, current_prd, and interactive: true to refine
3. Repeat step 2 until satisfied
4. Call with feedback, current_prd, and interactive: false to finalize and generate task files

parse_prd | Parameter | Type | Description | |-----------|------|-------------| | prd_path | string | Path to the PRD file to parse (required) | | project_name | string | Project name (auto-detected if not provided) | | target_agent | string | Target AI agent: claude-code, codex, or both | | project_dir | string | Project directory to write files to (defaults to current directory) |

Example Usage

Once configured, you can ask Claude:

• "Create a PRD for a todo app with user authentication, deployed to Vercel"
• "Create a PRD for an API service deployed to AWS with Terraform"
• "Parse my PRD at ./docs/requirements.md"
• "What's the current project status?"
• "What's the next task I should work on?"
• "Is user authentication implemented yet?"

Claude will call the appropriate MCP tool directly, asking for deployment details if not specified.

Slash Commands

When using Claude Code, these commands help maintain context:

| Command | What it does | |---------|--------------| | /next-task | Get the next task to work on | | /checkpoint | Save progress and create summary | | /phase-status | Show current phase completion | | /check-issue <desc> | Check if issue is bug or not implemented yet |

Configuration

API Keys

# Option 1: Environment variables (recommended)
export ANTHROPIC_API_KEY=sk-ant-...
export PERPLEXITY_API_KEY=pplx-...  # Optional, for research

# Option 2: Config file
vibe-assistant config --set-anthropic-key sk-ant-...
vibe-assistant config --set-perplexity-key pplx-...

View Config

vibe-assistant config --show

All Options

| Flag | Description | |------|-------------| | --set-anthropic-key <key> | Set Claude API key (required) | | --set-perplexity-key <key> | Set Perplexity API key (optional, for research) | | --set-default-agent <agent> | claude-code, codex, or both | | --set-model <model> | Set Claude model (default: claude-sonnet-4-5-20250929) |

The "Check Before Fixing" Feature

One of the most useful features is the /check-issue command and the guidance in CLAUDE.md.

When a user reports something "broken", the AI agent is instructed to:

1. Check state.json - What phase are we on? What's completed?
2. Check the PRD - Is this feature supposed to be implemented yet?
3. Determine verdict:
   • Feature in future phase? → Tell user "not implemented yet"
   • Feature should be working? → Investigate the bug

This prevents wasting time "fixing" things that simply haven't been built yet.

PRD Templates

Not sure how to structure your PRD? We have two options:

Quick-Start (Simple Projects)

cat node_modules/vibe-assistant/examples/quickstart-prd.md

A minimal template for small projects. Fill in the blanks and go.

Full Template (Complex Projects)

cat node_modules/vibe-assistant/examples/prd-template.md

The comprehensive Repository Planning Graph (RPG) template for larger projects. Helps you:

• Separate functional capabilities from code structure
• Define explicit dependencies between modules
• Create phases that follow topological order
• Write PRDs that produce better task breakdowns

Tip: Start with quick-start for simple projects. Use the full template when you have multiple developers, complex dependencies, or need detailed architecture planning.

How It Works

1. You provide your PRD (any text format - markdown, plain text, etc.)
2. Research step (if Perplexity API key is set):
   • Claude extracts key technical topics from your PRD
   • Perplexity researches best practices for each topic
   • Research results inform the task generation
3. Claude analyzes the PRD and extracts:
   • Project goals and summary
   • Implementation phases with entry/exit criteria
   • Individual tasks with dependencies
   • Parallelization opportunities
4. The structured output is saved as markdown files and JSON
5. Your AI coding agent uses these files to work through the project systematically

Note: The Perplexity research step is optional but recommended. It helps Claude create more informed tasks based on current best practices for your tech stack.

Troubleshooting

"Configuration Error: Missing Anthropic API key"

Set your API key via environment variable or config:

export ANTHROPIC_API_KEY=sk-ant-...
# or
vibe-assistant config --set-anthropic-key sk-ant-...

Research step failing

The Perplexity research step is optional. If it fails, vibe-assistant continues without it. To enable research:

export PERPLEXITY_API_KEY=pplx-...

"Task files already exist"

Use vibe-assistant update to re-parse or regenerate. Choose "Re-parse" to preserve progress for matching task IDs.

Slash commands not working in Claude Code

Ensure the .claude/commands/ directory was created:

ls .claude/commands/

If missing, re-run vibe-assistant init or vibe-assistant update.

Tasks seem out of order

Tasks should be completed in dependency order. Use /next-task to get the next task whose dependencies are met. Don't skip ahead unless all dependencies are complete.

AI keeps trying to fix unimplemented features

This is what vibe-assistant prevents! Make sure:

1. The generated CLAUDE.md is in your project root
2. Use /check-issue <description> before investigating any reported issue
3. Check docs/progress/state.json to see what's actually implemented

Contributing

Contributions welcome! Please feel free to submit a Pull Request.

License

MIT © Nick K