CODEBASE.md - project-starter

CODEBASE.md - project-starter

Comprehensive codebase documentation generated by 10 parallel exploration agents. Generated: 2026-01-17

Overview

project-starter (formerly claude-workflow) is a universal Claude Code plugin that augments the IDE with specialized AI agents, knowledge skills, automation hooks, and workflow commands for accelerated software development.

Key Capabilities

• 7 Specialized Agents: Autonomous subagents with action-first directives, effort scaling, and adversarial self-review
• 26 Slash Commands: Output styles, git workflows, verification, planning, onboarding, metrics
• 14 Knowledge Skills: Architecture, testing, APIs, performance, git, security, database, devops, error handling — with on-demand context loading
• 14 Automation Hooks: Pre/post tool validation, formatting, security, TypeScript, branch protection, doc suggestions, metrics, notifications

Repository Structure

claude-workflow/
├── .claude-plugin/              # Plugin configuration
│   ├── plugin.json              # Plugin manifest (name, version, metadata)
│   └── marketplace.json         # Marketplace publishing metadata
├── .github/                     # GitHub governance & CI
│   ├── workflows/
│   │   └── validate.yml         # Plugin validation CI/CD
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       └── feature_request.md
├── .claude/                     # Local settings and permissions
│   └── settings.local.json
├── agents/                      # 7 specialized AI subagents
│   ├── orchestrator.md          # Master coordinator (opus model)
│   ├── code-reviewer.md         # Quality and best practices
│   ├── debugger.md              # Root cause analysis
│   ├── docs-writer.md           # Technical documentation
│   ├── security-auditor.md      # OWASP vulnerability detection
│   ├── refactorer.md            # Code structure improvements
│   └── test-architect.md        # Test strategy design
├── commands/                    # 26 slash commands
│   ├── architect.md             # System design mode
│   ├── rapid.md                 # Fast development mode
│   ├── mentor.md                # Teaching mode
│   ├── review.md                # Strict review mode
│   ├── commit.md                # Auto-generate commits
│   ├── commit-push-pr.md        # Full PR workflow
│   ├── verify-changes.md        # Multi-agent verification
│   ├── validate-build.md        # Build validation
│   ├── run-tests.md             # Tiered test execution
│   ├── lint-check.md            # Linting checks
│   ├── lint-fix.md              # Auto-fix linting
│   ├── security-scan.md         # Security scanning
│   ├── quick-fix.md             # Fast lint/type fixes
│   ├── add-tests.md             # Generate tests
│   ├── sync-branch.md           # Sync with main
│   ├── summarize-changes.md     # Session summaries
│   ├── code-simplifier.md       # Post-implementation cleanup
│   ├── parallel-review.md       # Multi-directory review
│   ├── parallel-analyze.md      # Multi-perspective analysis
│   ├── plan.md                  # Persistent PLAN.md tracking
│   ├── refactor-guided.md       # 4-phase guided refactoring
│   ├── dependency-upgrade.md    # Safe dependency upgrades
│   ├── tutorial.md              # Interactive plugin tutorial
│   ├── bootstrap-repo.md        # 10-agent repo exploration
│   ├── save-session-learnings.md # Persist session discoveries
│   └── metrics.md               # View agent metrics
├── skills/                      # 14 knowledge domains
│   ├── analyzing-projects/SKILL.md
│   ├── convex-backend/SKILL.md
│   ├── database-design/SKILL.md
│   ├── designing-architecture/SKILL.md
│   ├── designing-apis/SKILL.md
│   ├── designing-tests/SKILL.md
│   ├── devops-infrastructure/SKILL.md
│   ├── error-handling/SKILL.md
│   ├── managing-git/SKILL.md
│   ├── optimizing-performance/SKILL.md
│   ├── parallel-execution/SKILL.md
│   ├── security-patterns/SKILL.md
│   ├── vercel-react-best-practices/SKILL.md
│   └── web-design-guidelines/SKILL.md
├── hooks/                       # 14 automation scripts
│   ├── hooks.json               # Hook registry
│   ├── protect-files.py         # Block sensitive file edits
│   ├── security-check.py        # Detect hardcoded secrets
│   ├── format-on-edit.py        # Auto-format (prettier/black/gofmt)
│   ├── typescript-check.py      # tsc --noEmit on .ts/.tsx edits
│   ├── pre-commit-check.py      # Debug statements & temp markers
│   ├── validate-environment.py  # Check Node/Python/Git
│   ├── validate-prompt.py       # Suggest agents for prompts
│   ├── verify-on-complete.py    # Run tests/lint on completion
│   ├── log-commands.sh          # Audit bash commands
│   ├── branch-protection.sh     # Warn on protected branch ops
│   ├── suggest-doc-updates.py   # Suggest doc updates on changes
│   ├── track-metrics.py         # Session telemetry logging
│   ├── notify-input.sh          # Desktop notification (input needed)
│   └── notify-complete.sh       # Desktop notification (complete)
├── examples/                    # Multi-agent orchestration examples
│   ├── README.md
│   └── orchestration/
│       ├── comprehensive-code-review/
│       └── parallel-execution/
├── templates/                   # User-copyable configuration
│   ├── CLAUDE.md.template
│   ├── settings.json.template
│   ├── settings.local.json.template
│   └── mcp.json.template
├── CLAUDE.md                    # Development guidelines
├── README.md                    # Main documentation
├── CHANGELOG.md                 # Version history
├── CONTRIBUTING.md              # Contribution guidelines
├── CODE_OF_CONDUCT.md           # Community guidelines
├── PERMISSIONS.md               # Permission framework
└── LICENSE                      # MIT license

Getting Started

Installation Options

1. Per-Session (Temporary)

git clone https://github.com/CloudAI-X/claude-workflow-v2.git
claude --plugin-dir ./claude-workflow

2. Per-Project (Permanent)

claude plugin install ./claude-workflow

3. Global (Marketplace)

claude plugin install project-starter

4. Agent SDK (Programmatic)

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

for await (const message of query({
  plugins: [{ type: "local", path: "./claude-workflow" }],
})) {
  // Handle messages
}

Prerequisites

Validation

claude plugin validate  # Validate plugin structure

Architecture

Plugin Architecture Pattern

This plugin uses a metadata-driven, modular architecture with no traditional runtime dependencies:

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code IDE                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Agents    │  │  Commands   │  │   Skills    │         │
│  │ (7 specs)   │  │ (19 specs)  │  │ (7 domains) │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┼────────────────┘                 │
│                          │                                  │
│                ┌─────────┴─────────┐                        │
│                │   Hook System     │                        │
│                │ (Event-Driven)    │                        │
│                └─────────┬─────────┘                        │
│                          │                                  │
│    ┌─────────────────────┼─────────────────────┐           │
│    │         │           │           │         │           │
│    ▼         ▼           ▼           ▼         ▼           │
│ PreToolUse PostToolUse  Stop  SessionStart  Notification   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Agent Hierarchy

Parallel Execution (v1.1.0)

The orchestrator can spawn N subagents simultaneously for Nx performance:

           User Request
                │
                ▼
       ┌─────────────────┐
       │   Orchestrator  │
       │   (Creates Plan)│
       └────────┬────────┘
                │
    ┌───────────┼───────────┬───────────┬───────────┐
    │           │           │           │           │
    ▼           ▼           ▼           ▼           ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Task 1 │ │ Task 2 │ │ Task 3 │ │ Task 4 │ │ Task 5 │
└────┬───┘ └────┬───┘ └────┬───┘ └────┬───┘ └────┬───┘
     │          │          │          │          │
     └──────────┴──────────┴──────────┴──────────┘
                          │
                   [TaskOutput]
                          │
                   [Synthesize]

Critical Rule: ALL Task calls must be in a SINGLE assistant message for true parallelism.

Data Layer

This plugin has no traditional database layer. Instead, it uses:

Data Sources

YAML Frontmatter Schema

---
name: identifier
description: Purpose. Use PROACTIVELY when [triggers].
tools: Read, Write, Edit, Bash, Glob, Grep
model: opus|sonnet|haiku
permissionMode: default|acceptEdits
skills: skill-name1, skill-name2
---

Hook Input/Output

// stdin (hook receives)
{
  "tool_input": {
    "file_path": "/path/to/file",
    "content": "file contents..."
  }
}

// Exit codes
// 0 = Allow operation
// 2 = Block with message

Core Logic

Orchestrator Workflow

Phase 1: UNDERSTAND
  └─ Read requirements, explore codebase, identify affected systems

Phase 2: PLAN
  └─ Create TodoWrite list, group parallelizable tasks, identify dependencies

Phase 3: DELEGATE
  └─ Spawn specialists (sequential or parallel via Task tool)

Phase 4: INTEGRATE
  └─ Synthesize outputs, resolve conflicts, ensure consistency

Phase 5: VERIFY
  └─ Run tests/lint, quality checks

Phase 6: DELIVER
  └─ Summarize changes, create PRs, update documentation

Security Check Algorithm

SECRET_PATTERNS = [
    r'api[_-]?key.*[a-zA-Z0-9_-]{20,}',  # API keys
    r'ghp_[a-zA-Z0-9]{36}',               # GitHub PATs
    r'sk-ant-[a-zA-Z0-9-]{90,}',          # Anthropic keys
    r'AKIA[0-9A-Z]{16}',                  # AWS credentials
    r'-----BEGIN.*PRIVATE KEY-----',      # Private keys
]

SKIP_FILES = ['.env.example', 'package-lock.json', '*test*']

# Exit 2 (block) if secret found, 0 (allow) otherwise

Verification Pipeline

verify-changes command spawns 5 parallel subagents:

1. Syntax & Type Check (tsc, mypy, go vet)
2. Test Runner (affected → unit → integration)
3. Lint & Style Check (eslint, ruff, golangci-lint)
4. Security Scan (secrets, dependencies, OWASP)
5. Build Validator (compile, artifacts)

+ 3 Adversarial subagents:
  - False Positive Filter
  - Missing Issues Finder
  - Context Validator

API Reference

Commands (26 total)

Output Styles

Git Workflow

Verification

Planning & Refactoring

Onboarding & Knowledge

Hook Events

Testing

Test Strategy (Testing Pyramid)

        /\
       /  \     E2E Tests (10%)
      /----\    - Critical user journeys
     /      \   - Slow but comprehensive
    /--------\  Integration Tests (20%)
   /          \ - Component interactions
  /            \ - API contracts
 /              \ Unit Tests (70%)
/________________\ - Fast, isolated
                   - Business logic focus

Framework Detection

Tiered Execution

# Tier 1: Affected tests only (fast)
npm test -- --findRelatedTests [changed files]
pytest [specific files] -x --tb=short

# Tier 2: Full unit suite
npm test
pytest tests/unit/

# Tier 3: Integration tests
npm run test:integration
pytest tests/integration/

Coverage Targets

• Global: 80%+ branches, functions, lines
• Core business logic: 95%+
• API contracts: 100%

Deployment

Agent-Based Operations

This plugin uses intelligent agents instead of traditional CI/CD:

Hook Automation

Cross-Platform Notifications

• macOS: osascript native notifications
• Linux: notify-send (graceful fallback if missing)
• Windows: PowerShell toast notifications

Dependencies

Zero Runtime Dependencies

This plugin has no npm/pip dependencies. It's pure metadata + scripts.

Tool Dependencies (Auto-detected)

Graceful Degradation

All tools are optional. Missing tools result in warnings, not failures.

Domain Glossary

Core Entities

Execution Patterns

Code Quality

Security

Documentation Index

Agent Documentation

Skill Documentation

Version History

v1.2.0 (2026-02-14)

• Agent Upgrades: All 7 agents enhanced with action-first directives, effort scaling, adversarial self-review, paired WRONG/CORRECT examples
• 4 New Skills: database-design, devops-infrastructure, error-handling, security-patterns
• On-Demand Context Loading: All 14 skills now have "When to Load" sections for optimized context usage
• 7 New Commands: plan, refactor-guided, dependency-upgrade, tutorial, bootstrap-repo, save-session-learnings, metrics
• 5 New Hooks: pre-commit-check.py, branch-protection.sh, typescript-check.py, suggest-doc-updates.py, track-metrics.py
• Improved Hook Messages: All hooks now include actionable remediation suggestions
• CI/CD: GitHub Actions plugin validation workflow
• Rewritten: web-design-guidelines skill now self-contained (was external URL dependency)

v1.1.0 (2025-01-07)

• Parallel Execution Support: Orchestrator can spawn N subagents simultaneously
• New Commands: parallel-review, parallel-analyze
• New Skill: parallel-execution with patterns and best practices
• Performance: ~Nx faster execution for N independent tasks

v1.0.0 (2025-01-01)

• Initial release with 7 agents, 6 skills, 17 commands, 9 hooks
• Full multi-agent orchestration support
• Cross-platform desktop notifications
• Comprehensive security scanning

This document was generated by the /bootstrap-repo command using 10 parallel exploration agents.