AI-Vibe-Prompts

An Autonomous AI-Agent Framework for Modern Web Development

AI-Vibe-Prompts has evolved from a collection of prompts into a powerful, agent-driven framework. It provides a team of specialized AI agents that collaborate to design, build, and maintain complex web applications, following a predictable, tool-based workflow.

🎯 The New Paradigm: Agent-Driven Development

This framework introduces a structured, tool-first approach to AI-assisted development, moving beyond simple prompts to a robust system of autonomous agents.

• From Prompts to Agents: We've transformed descriptive markdown files into active, specialized agents. Each agent has a clear role and uses a powerful set of tools to perform its tasks.
• The PLAN -> ACT Cycle: All agents operate on a strict Plan-then-Act cycle. They first analyze the task and create a detailed, transparent plan of tool calls. Only after the plan is defined do they execute it, ensuring predictable and auditable behavior.
• Orchestration with Workflow Composer: For complex tasks, the Workflow Composer acts as a director, creating and managing multi-agent workflows. It sequences tasks, hands off work between agents, and enforces quality gates, turning a high-level goal into a fully managed, automated process.

✨ Features

• 🤖 Autonomous AI Agents: A team of specialized agents for architecture, development, refactoring, debugging, and more.
• 🎯 Claude Skills (v2.x NEW): Reusable expertise packages with progressive disclosure for token efficiency
• 🔄 Predictable PLAN -> ACT Workflow: Ensures transparency and reliability in all agent operations.
• 🎼 Multi-Agent Orchestration: The Workflow Composer designs and executes complex development workflows.
• 🛠️ Tool-Based Execution: Agents perform all actions through Claude Code's native tools (Bash, Edit, Grep, Read, Write), eliminating guesswork.
• 📦 Progressive Disclosure: Load skills on-demand for unbounded expertise with minimal token usage
• 🚀 Automated Onboarding: The Onboarder agent automates project setup, from dependency checks to initial tests.
• 🔬 Scientific Debugging & Refactoring: Dedicated agents apply systematic, safe, and verifiable methods to improve code quality.
• 🛡️ Built-in Quality Gates: The Quality Monitor and RAG Assistant ensure that all work meets predefined standards.
• 🧩 Project Templates: Production-ready starters for various application types, now with automated setup.

🚀 Getting Started

This framework is now managed via a powerful command-line interface (CLI). Follow these steps to get started.

0. Integration with Your Project

Two approaches:

1. Recommended: Clone AI-Vibe-Prompts in your workspace and use it as a shared framework

   git clone https://github.com/Atman36/AI-Vibe-Prompts.git
   cd your-app
   # Reference agents via absolute path or as submodule
   

2. Alternative: Add as git submodule in your project

   git submodule add https://github.com/Atman36/AI-Vibe-Prompts.git .ai-agents
   npm install  # in submodule directory
   

1. Prerequisites

• Node.js version 18 or higher.
• Dependencies installed: npm install

2. Discover Available Agents and Skills

To see the full team of specialized agents and skills available to you:

# List all agents
node scripts/avp-init.js discover

# List all Claude Skills (v2.x)
node scripts/avp-init.js skills:list

# Show system status
node scripts/avp-init.js system:status

New in v3.0: Claude Skills provide reusable expertise that loads progressively, minimizing token usage while providing unlimited specialized knowledge.

3. Define a Workflow

Create a JSON file (e.g., my-workflow.json) to define a sequence of tasks for the agents. Each step specifies the agent to use and the task to perform.

Example my-workflow.json:

{
  "name": "New Feature Workflow",
  "steps": [
    {
      "agentName": "Project Initializer",
      "description": "Initialize a new project",
      "task": { "projectName": "my-new-app" }
    },
    {
      "agentName": "Codebase Analyzer Agent",
      "description": "Analyze the new codebase",
      "task": { "projectPath": "./my-new-app" }
    }
  ]
}

4. Run the Workflow

Execute your workflow using the workflow:run command:

node scripts/avp-init.js workflow:run my-workflow.json

The CLI will execute each step, applying confidence gating to ensure quality and reliability. If an agent's confidence is too low, the workflow will halt for an audit.

⚙️ The CLI-Driven Workflow

Interaction with the framework is managed entirely through the CLI, providing a structured and repeatable process for complex tasks.

1. Discover Agents: Use avp discover to identify the best agent for each part of your task.
2. Compose a Workflow: Define a series of steps in a .json file. Each step assigns a task to a specific agent.
3. Execute with Confidence: Run your workflow with avp workflow:run <your-file.json>. The system orchestrates the agents, and its confidence-gating system ensures each step meets quality standards before proceeding.

💬 Using Agents in Claude Code

Once integrated, use agents directly in Claude Code:

@developer implement the authentication system
@architect design the database schema
@react-optimizer improve component performance
@designer create the landing page layout

Or let Claude Code auto-select the best agent:

Help me build a checkout flow
Can you refactor this component?
Debug this authentication issue

🤖 The Agent Team

Our agents have been upgraded to be active participants in the development process.

• core/architect: Designs system architecture and creates technical plans for the Developer.
• core/developer: Implements features based on architectural plans, using its frontend, backend, and testing specialists.
• helpers/refactor-assistant: An active agent that uses tools like Edit and Bash to safely prepare code before new features are added.
• helpers/debugger-assistant: Uses a scientific method and tools to systematically find and fix bugs.
• helpers/quality-monitor: Automatically runs linters, tests, and security scans using Bash to enforce quality standards.
• helpers/onboarder: Automates the entire project setup process.
• helpers/workflow-composer: The team lead. Decomposes high-level goals into multi-agent workflows and orchestrates their execution.

...and many more specialized agents in the agents directory.

🎯 Claude Skills (v2.x NEW)

Skills are reusable expertise packages that auto-invoke based on context, using Progressive Disclosure for token efficiency.

Core Skills

• codebase-analysis (v1.0.0): Systematically analyze project structure, complexity, and dependencies
• quality-gates (v1.0.0): Run comprehensive quality checks (lint, test, security) before commits/deploys

Framework-Specific Skills

• nextjs-optimization (v1.0.0): Optimize Next.js 15 for Core Web Vitals and production performance

Workflow Skills

• git-workflow (v1.0.0): Git best practices with GitFlow and Conventional Commits
• testing-strategy (v1.0.0): Comprehensive testing with Vitest + Playwright

Design Skills

• frontend-design (v1.0.0): Create distinctive, production-grade frontend interfaces with high design quality

How Skills Work

1. Metadata Loading: Only name/description loaded initially (lightweight)
2. Full Context: Instructions loaded when skill is relevant
3. Deep Resources: Additional files loaded on-demand

Result: Unbounded expertise library with minimal token overhead

Total: 6 skills (5 with auto-invoke enabled, 1 on-demand)

See Skills System Guide for details.

📁 Repository Structure

ai-vibe-prompts/
├── .claude/                    # Claude Code v2.x integration
│   ├── agents/                # 16 specialized subagents
│   ├── skills/                # 6 reusable expertise packages (NEW v3.x)
│   └── plugins/               # Plugin system (NEW v3.x)
├── agents/                    # Legacy Cursor AI agents (compatibility)
├── docs/                      # Comprehensive documentation
│   ├── skills-system-guide.md    # Skills development guide
│   ├── plugin-system-guide.md    # Plugin architecture
│   ├── CHANGELOG-v3.0.md         # v3.0 release notes
│   └── CHANGELOG-v3.1.md         # v3.1 release notes
├── scripts/                   # CLI tools
│   └── avp-init.js           # Main CLI with skills support
├── templates/                 # Production-ready project starters
├── tools/                     # Tool configurations
├── core-config.yaml          # Central configuration
└── CLAUDE.md                 # Claude Code integration guide

🤝 Contributing

This project is rapidly evolving. Contributions to improve agents, tools, and workflows are welcome. Please see CONTRIBUTING.md for guidelines.

3. Place in appropriate folder:
   • agents/core/ - Core development workflow
   • agents/project/ - Project lifecycle management
   • agents/design/ - UI/UX specialization
   • agents/helpers/ - Utility and analysis

Extending Existing Agents

Fork this repository and modify agents to match your:

• Technology preferences
• Design system requirements
• Team coding standards
• Project-specific needs

🛠️ CLI Commands

The avp-init.js script provides the following commands to manage your agent workflows and skills.

Agent Commands

Lists all available agents and their capabilities.

node scripts/avp-init.js discover

Skill Commands (v2.x NEW)

# List all available skills
node scripts/avp-init.js skills:list

# Show detailed info about a specific skill
node scripts/avp-init.js skills:info codebase-analysis

# Show system status (agents + skills)
node scripts/avp-init.js system:status

Workflow Commands

Executes a multi-agent workflow from a JSON definition file.

node scripts/avp-init.js workflow:run <path_to_workflow.json>

🌟 Key Benefits

For Individual Developers

• Faster Development - AI agents accelerate coding with context-aware assistance
• Better Code Quality - Built-in quality gates and best practices enforcement
• Learning Tool - Learn modern patterns and architectural decisions
• Consistency - Standardized approaches across all projects

For Teams

• Workflow Standardization - Consistent development processes
• Knowledge Sharing - Capture and reuse architectural decisions
• Quality Assurance - Automated quality checks and monitoring
• Onboarding - New team members get up to speed faster

For Projects

• Modern Stack - React 19, Next.js 15, TypeScript best practices
• Performance First - Core Web Vitals optimization built-in
• Accessibility - WCAG 2.2 AA compliance by default
• Security - Security best practices and vulnerability detection

🆕 What's New in v3.1

New Workflow Skills

• git-workflow (v1.0.0): Professional Git workflow with GitFlow and Conventional Commits
• testing-strategy (v1.0.0): Comprehensive testing with Vitest and Playwright

Plugin System

• Complete Claude Code v2.x plugin architecture
• Marketplace-ready distribution
• Multiple installation methods

Enhanced Documentation

• Skills System Guide (13 KB)
• Plugin System Guide (8 KB)
• Complete changelogs and implementation report

See: CHANGELOG-v3.1 for full details

🎓 Learning Resources

"A Philosophy of Software Design" Concepts Applied

• Chapter 3 (Working Code Isn't Enough): Our system prompt emphasizes strategic programming
• Chapter 4 (Modules Should Be Deep): Component design follows simple interface, complex implementation
• Chapter 5 (Information Hiding): Configuration abstraction in project initialization
• Chapter 6 (General-Purpose Modules): Design system components are built for reuse
• Chapter 10 (Define Errors Out of Existence): TypeScript strict mode and validation schemas

Modern Web Development Stack

• React 19: Server Components, concurrent features, optimistic updates
• Next.js 15: App Router, Server Actions, React Compiler integration
• TypeScript 5.5+: Strict mode, branded types, advanced patterns
• Tailwind CSS: Utility-first styling, design tokens, OKLCH colors
• Cursor AI: AI-powered development with intelligent code completion
• Figma: Design systems, component specs, design-to-code workflows

💡 Advanced Features from Community Research

Safety & Refusal Patterns

Our agents incorporate safety principles from leading AI research:

• Factual accuracy: Built-in fact-checking and verification patterns
• Bias prevention: Explicit instructions for inclusive, unbiased responses
• Error boundaries: Clear guidelines for handling edge cases and limitations
• Context awareness: Structured information boundaries and source attribution

Advanced Prompting Techniques

• Chain-of-Thought: Step-by-step reasoning for complex architectural decisions
• Few-Shot Learning: Examples and patterns embedded in agent design
• Meta-Language: Custom command structures for efficient AI interaction
• Context Engineering: Advanced memory management and state alignment

Professional Tone Guidelines

• Direct and professional communication - no filler or apologetic language
• Focus on actionable outcomes rather than theoretical discussions
• Concrete examples and code snippets when beneficial
• Clear delegation to specialized agents when appropriate

🤝 Contributing

1. Follow the philosophy: Ensure new agents reduce complexity rather than add it
2. Test thoroughly: Verify agents work with current AI assistants
3. Document clearly: Explain the purpose and usage of new agents
4. Maintain consistency: Follow the established structure and naming conventions

Development Setup

git clone https://github.com/Atman36/AI-Vibe-Prompts.git
cd AI-Vibe-Prompts
npm install
npm run dev

💰 Support This Project

If these prompts save you time and improve your development workflow, consider supporting the project:

Cryptocurrency Donations

• Bitcoin: 1FEvqUr9fhx9z8jZQ3ympj19QaKG4sfe1u
• Ethereum: 0x6b8d7137b60a6f3ee8869dc6c53ab989937e3462
• USDT (TRC20): TBYiX5jAZ38qSHvkuyL3QMTytMf5P671VJ

Other Ways to Support

• ⭐ Star this repository
• 🐛 Report issues and bugs
• 💡 Suggest new agent ideas
• 🔄 Share with your development team
• 📝 Contribute improvements and documentation

📄 License

MIT License - feel free to use these agents in your projects and modify them to fit your needs.

🔗 Links

• GitHub Repository
• Documentation
• Issues & Support
• Discussions

---

Built with ❤️ for the modern web development community

Remember: The goal is to create software that gets easier to work with over time, not harder. These agents are designed to help you build systems that reduce cognitive load and manage complexity effectively.

Inspired by BMAD-METHOD's agent coordination principles and focused on React/Next.js development excellence.