project-starter

A universal Claude Code workflow plugin with specialized agents, skills, hooks, and mode commands for any software project. Compatible with skills.sh — works with Claude Code, Cursor, Codex, and 35+ AI agents.

Quick Start

Option 1: skills.sh (Recommended — Any Agent)

npx skills add CloudAI-X/claude-workflow-v2

Installs skills to Claude Code, Cursor, Codex, Windsurf, Cline, and 35+ other AI agents automatically.

Option 2: npx (Claude Code — Full Plugin)

npx install-claude-workflow-v2@latest

Copies agents, commands, skills and hook scripts into .claude/ and registers the hooks in .claude/settings.json (existing files and settings are kept). Two differences from a plugin install: commands are not namespaced (/commit instead of /project-starter:commit), and permissionMode: acceptEdits on the debugger, docs-writer, refactorer and test-architect agents takes effect (Claude Code ignores that field for plugin agents).

Option 3: CLI (Per-Session)

# Clone the plugin
git clone https://github.com/CloudAI-X/claude-workflow-v2.git

# Run Claude Code with the plugin
claude --plugin-dir ./claude-workflow-v2

Option 4: Agent SDK

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello",
  options: {
    plugins: [{ type: "local", path: "./claude-workflow-v2" }],
  },
})) {
  // Plugin commands, agents, and skills are now available
}

Option 5: Install Permanently

# Add this repository as a marketplace, then install the plugin from it
claude plugin marketplace add CloudAI-X/claude-workflow-v2
claude plugin install project-starter@claude-workflow

Verify Installation

After loading the plugin, verify it's working:

> /plugin

Tab to Installed - you should see project-starter listed. Tab to Errors - should be empty (no errors).

These commands become available:

/project-starter:architect    # Architecture-first mode
/project-starter:rapid        # Ship fast mode
/project-starter:commit       # Auto-generate commit message
/project-starter:verify-changes  # Multi-agent verification

What's Included

Usage Examples

Commands in Action

Auto-commit your changes:

> /project-starter:commit

Looking at staged changes...
✓ Created commit: feat(auth): add JWT refresh token endpoint

Full git workflow:

> /project-starter:commit-push-pr

✓ Committed: feat: add user dashboard
✓ Pushed to origin/feature/dashboard
✓ Created PR #42: https://github.com/you/repo/pull/42

Verify before shipping:

> /project-starter:verify-changes

Spawning verification agents...
├─ build-validator: ✓ Build passes
├─ test-runner: ✓ 42 tests pass
├─ lint-checker: ⚠ 2 warnings (non-blocking)
└─ security-scanner: ✓ No vulnerabilities

Ready to ship!

Agents in Action

Agents spawn automatically based on your request:

You say: "The login is broken, users get 401 errors"

[debugger agent activated]
→ Checking auth middleware... found issue
→ Token validation uses wrong secret in production
→ Fix: Update AUTH_SECRET in .env.production

You say: "Review my changes"

[code-reviewer agent activated]
→ Analyzing 3 files changed...
✓ Logic is correct
⚠ Missing null check on line 42
⚠ Consider adding rate limiting to this endpoint

You say: "Add authentication to the API"

[orchestrator agent activated]
→ Breaking down into subtasks:
  1. Design auth schema (applying the designing-architecture skill)
  2. Implement JWT middleware
  3. Add login/register endpoints
  4. Write tests (spawning test-architect)
  5. Update API docs (spawning docs-writer)

Skills in Action

Skills provide domain knowledge automatically:

You ask: "How should I structure the payment service?"

[designing-architecture skill applied]
→ Recommending hexagonal architecture
→ Payment providers as adapters
→ Core domain isolated from infrastructure

You ask: "Make this endpoint faster"

[optimizing-performance skill applied]
→ Adding database indexes
→ Implementing response caching
→ Using pagination for large results

Hooks in Action

Hooks run automatically on events:

Security block (pre-edit):

🚫 BLOCKED - Security issue detected in src/config.ts:
  - Potential API key detected → Move to .env file and use environment variables (e.g., process.env.API_KEY)

Auto-format (post-edit):

The edited file is formatted silently with the project's own formatter; the hook prints nothing.

Desktop notifications:

🔔 "Claude needs input" - when waiting for your response
🔔 "Task complete" - when finished

Commands Reference

All commands use the format /project-starter:<command>.

Mode Commands (Output Styles)

Git Workflow (Inner-Loop)

Verification

Parallel

Planning & Refactoring

Onboarding & Knowledge

Agents

Agents are specialized subagents that Claude spawns automatically based on your task.

Skills

Skills are knowledge domains that Claude uses autonomously when relevant.

Hooks

Hooks run automatically on specific events.

Examples

For detailed multi-agent orchestration examples, see the examples/ directory:

The comprehensive-code-review example includes:

• README.md - Overview and quick start
• workflow.md - Exact prompts to use
• verification.md - How to verify it works
• sample-outputs/ - Example agent outputs

Configuration

Add Permissions to Your Project

Copy the permissions template to your project:

mkdir -p /path/to/your/project/.claude
cp templates/settings.local.json.template /path/to/your/project/.claude/settings.local.json

This pre-allows a broad set of development commands so you don't get prompted every time. It includes interpreters and package runners (python, npx, bun), network tools (curl, wget) and git push, which together allow arbitrary code execution and data egress without a prompt — trim the list to what your project needs.

Add Team Conventions

Copy the CLAUDE.md template to your project root:

cp templates/CLAUDE.md.template /path/to/your/project/CLAUDE.md

Then customize with your:

• Package manager commands
• Test/build/lint commands
• Code conventions
• Architecture decisions

MCP Servers

Copy the MCP template to enable integrations like Slack, GitHub, Sentry:

cp templates/mcp.json.template /path/to/your/project/.mcp.json

Then configure the environment variables for the servers you want to use.

GitHub Action (@.claude in PRs)

Enable Claude to respond to PR comments by installing the GitHub Action:

# Inside Claude Code, in your repository
> /install-github-app

This enables:

• Tag @claude in PR comments to get code suggestions
• Auto-update CLAUDE.md during code review
• Claude responds to review feedback automatically

Example PR comment:

@claude please add input validation to the email field

Team workflow tip: Use @claude to update your CLAUDE.md with learnings from code review:

@claude add a note to CLAUDE.md that we should always validate email format before API calls

Extending the Plugin

Add Custom Commands

Create .md files in commands/:

---
allowed-tools: Bash(git:*), Read, Write
description: What this command does
argument-hint: "[optional arguments]"
---

[Command instructions here]

Add Custom Agents

Create .md files in agents/:

---
name: my-agent
description: What it does. Use PROACTIVELY when [triggers].
tools: Read, Write, Edit, Bash
model: sonnet
---

[Agent instructions here]

Add Custom Skills

Create subdirectories in skills/ with a SKILL.md file:

---
name: my-skill
description: Guides [domain]. Use when [triggers].
---

[Skill knowledge and patterns here]

Plugin Structure

claude-workflow/
├── .claude-plugin/
│   ├── plugin.json           # Required: Plugin manifest
│   └── marketplace.json      # Optional: Marketplace metadata
├── agents/                   # 7 specialized agents
│   ├── orchestrator.md
│   ├── code-reviewer.md
│   ├── debugger.md
│   ├── docs-writer.md
│   ├── security-auditor.md
│   ├── refactorer.md
│   └── test-architect.md
├── commands/                 # 26 slash commands
│   ├── architect.md          # Output styles
│   ├── rapid.md
│   ├── mentor.md
│   ├── review.md
│   ├── commit.md             # Git workflow
│   ├── commit-push-pr.md
│   ├── quick-fix.md
│   ├── add-tests.md
│   ├── lint-fix.md
│   ├── sync-branch.md
│   ├── summarize-changes.md
│   ├── verify-changes.md     # Verification
│   ├── validate-build.md
│   ├── run-tests.md
│   ├── lint-check.md
│   ├── security-scan.md
│   ├── code-simplifier.md
│   ├── parallel-review.md    # Parallel
│   ├── parallel-analyze.md
│   ├── plan.md               # Planning & refactoring
│   ├── refactor-guided.md
│   ├── dependency-upgrade.md
│   ├── tutorial.md           # Onboarding & knowledge
│   ├── bootstrap-repo.md
│   ├── save-session-learnings.md
│   └── metrics.md
├── skills/                   # 14 knowledge domains
│   ├── analyzing-projects/
│   ├── convex-backend/
│   ├── database-design/
│   ├── designing-apis/
│   ├── designing-architecture/
│   ├── designing-tests/
│   ├── devops-infrastructure/
│   ├── error-handling/
│   ├── managing-git/
│   ├── optimizing-performance/
│   ├── parallel-execution/
│   ├── security-patterns/
│   ├── vercel-react-best-practices/
│   └── web-design-guidelines/
├── hooks/
│   ├── hooks.json            # Hook configuration
│   └── 14 automation scripts # Pre/post tool, session, metrics, notifications
├── templates/                # User-copyable templates
│   ├── CLAUDE.md.template
│   ├── settings.json.template
│   ├── settings.local.json.template
│   ├── mcp.json.template
│   ├── mcp-servers-template.md
│   └── README.md
├── CLAUDE.md                 # Plugin development guidelines
└── README.md

Requirements

• Claude Code v1.0.33 or later
• Python 3 (for hook scripts)
• Node.js (optional, for npm commands)
• Git (for version control features)

Multi-Agent Compatibility (skills.sh)

This repo is fully compatible with skills.sh — the universal agent skills platform. Our 14 skills work with 38+ AI coding agents:

Note: npx skills add installs skills only. For agents, commands and hooks as well, use npx install-claude-workflow-v2@latest or install the plugin (Option 5).

Contributing

Contributions welcome! See CONTRIBUTING.md.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Star History

Credits

• Plugin created by @cloudxdev
• Workflow patterns inspired by Boris Cherny (creator of Claude Code)

License

MIT - see LICENSE for details.