# CODEBASE.md - project-starter > This plugin has no npm/pip dependencies. It's pure metadata + scripts. - Skill: `tools-only/codebase-md-project-starter` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/codebase-md-project-starter` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/codebase-md-project-starter/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/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. | Attribute | Value | | ---------------- | ----------------------------------------------- | | **Name** | project-starter | | **Version** | 1.2.0 | | **Type** | Claude Code Plugin | | **License** | MIT | | **Author** | CloudAI-X | | **Repository** | https://github.com/CloudAI-X/claude-workflow-v2 | | **Requirements** | Claude Code v1.0.33+, Python 3, Git | ### 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)** ```bash git clone https://github.com/CloudAI-X/claude-workflow-v2.git claude --plugin-dir ./claude-workflow ``` **2. Per-Project (Permanent)** ```bash claude plugin install ./claude-workflow ``` **3. Global (Marketplace)** ```bash claude plugin install project-starter ``` **4. Agent SDK (Programmatic)** ```typescript import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ plugins: [{ type: "local", path: "./claude-workflow" }], })) { // Handle messages } ``` ### Prerequisites | Tool | Required | Purpose | | ----------- | ----------- | ------------------------------ | | Claude Code | v1.0.33+ | Plugin host | | Python 3 | Yes | Hook scripts | | Git | Recommended | Version control features | | Node.js | Optional | JS/TS formatting, npm commands | ### Validation ```bash 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 | Agent | Model | Responsibility | Auto-Trigger Keywords | | -------------------- | ------ | ------------------------------------------- | ---------------------------------------------------- | | **orchestrator** | opus | Multi-step coordination, parallel execution | "improve", "enhance", "build", "architecture" | | **code-reviewer** | sonnet | Quality assessment, best practices | "review", "PR review", "lint", "standards audit" | | **debugger** | sonnet | Root cause analysis, bug fixing | "bug", "error", "crash", "memory leak", "timeout" | | **security-auditor** | sonnet | Vulnerability detection, OWASP | "security", "auth", "JWT", "CORS", "secrets" | | **test-architect** | sonnet | Test strategy, coverage | "test", "coverage", "mocking", "flaky tests" | | **refactorer** | sonnet | Code structure, SOLID principles | "refactor", "tech debt", "code smells", "complexity" | | **docs-writer** | sonnet | Technical documentation | "document", "changelog", "migration guide" | ### 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 | Type | Location | Format | | ----------------------- | ---------------------------- | --------------------------- | | **Plugin Config** | `.claude-plugin/plugin.json` | JSON | | **Hook Registry** | `hooks/hooks.json` | JSON | | **Agent Definitions** | `agents/*.md` | YAML frontmatter + Markdown | | **Command Definitions** | `commands/*.md` | YAML frontmatter + Markdown | | **Skill Knowledge** | `skills/*/SKILL.md` | YAML frontmatter + Markdown | ### YAML Frontmatter Schema ```yaml --- 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 ```json // 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 ```python 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 | Command | Description | | ---------------------------- | --------------------------------------------- | | `/project-starter:architect` | System design mode - architecture before code | | `/project-starter:rapid` | Fast development - minimal ceremony | | `/project-starter:mentor` | Teaching mode - explains concepts | | `/project-starter:review` | Strict code review mode | #### Git Workflow | Command | Description | | ------------------------------------ | --------------------------------- | | `/project-starter:commit` | Auto-generate conventional commit | | `/project-starter:commit-push-pr` | Full workflow: commit → push → PR | | `/project-starter:quick-fix` | Fast lint/type error fixes | | `/project-starter:add-tests` | Generate tests for changes | | `/project-starter:lint-fix` | Auto-fix all linting issues | | `/project-starter:sync-branch` | Sync with main (rebase/merge) | | `/project-starter:summarize-changes` | Generate standup/PR summaries | #### Verification | Command | Description | | ----------------------------------- | ------------------------------------ | | `/project-starter:verify-changes` | Multi-agent adversarial verification | | `/project-starter:validate-build` | Build process validation | | `/project-starter:run-tests` | Tiered test execution | | `/project-starter:lint-check` | Code quality checks | | `/project-starter:security-scan` | Vulnerability detection | | `/project-starter:code-simplifier` | Post-implementation cleanup | | `/project-starter:parallel-review` | Multi-directory parallel review | | `/project-starter:parallel-analyze` | Multi-perspective analysis | #### Planning & Refactoring | Command | Description | | ------------------------------------- | --------------------------------- | | `/project-starter:plan` | Persistent PLAN.md phase tracking | | `/project-starter:refactor-guided` | 4-phase systematic refactoring | | `/project-starter:dependency-upgrade` | Safe dependency upgrades | #### Onboarding & Knowledge | Command | Description | | ----------------------------------------- | ---------------------------------- | | `/project-starter:tutorial` | Interactive guided tutorial | | `/project-starter:bootstrap-repo` | 10-agent parallel repo exploration | | `/project-starter:save-session-learnings` | Persist session discoveries | | `/project-starter:metrics` | View agent performance metrics | ### Hook Events | Event | Trigger | Scripts | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------- | | **PreToolUse** | Before Edit/Write | `protect-files.py`, `security-check.py` | | **PreToolUse** | Before Bash | `log-commands.sh`, `branch-protection.sh`, `pre-commit-check.py` | | **PostToolUse** | After Edit/Write | `format-on-edit.py`, `typescript-check.py` | | **SessionStart** | Plugin load | `validate-environment.py` | | **UserPromptSubmit** | User prompt | `validate-prompt.py` | | **Stop** | Task complete | `verify-on-complete.py`, `suggest-doc-updates.py`, `notify-complete.sh`, `track-metrics.py` | | **Notification** | Input needed | `notify-input.sh` | --- ## 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 | Language | Unit | Integration | E2E | | --------------------- | ----------------- | --------------------- | ---------- | | JavaScript/TypeScript | Jest, Vitest | Vitest + MSW | Playwright | | Python | pytest | pytest + httpx | Playwright | | Go | testing + testify | testing + httptest | chromedp | | Rust | cargo test | cargo test --features | - | ### Tiered Execution ```bash # 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: | Traditional | project-starter Equivalent | | ---------------- | --------------------------------- | | GitHub Actions | `/project-starter:verify-changes` | | Build pipeline | `/project-starter:validate-build` | | Test runner | `/project-starter:run-tests` | | Security scanner | `/project-starter:security-scan` | | Linter | `/project-starter:lint-check` | | PR creation | `/project-starter:commit-push-pr` | ### Hook Automation | Operation | Automation | | ------------- | ---------------------------------- | | File edit | Auto-format (prettier/black/gofmt) | | Commit | Secret detection, file protection | | Task complete | Auto-verification, notifications | | Session start | Environment validation | ### 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) | Tool | File Types | Required | | ------------ | --------------------------- | ---------------- | | **Prettier** | JS, TS, JSON, CSS, MD, YAML | Optional | | **Black** | Python | Optional | | **gofmt** | Go | Built-in with Go | | **rustfmt** | Rust | rustup component | | **ESLint** | JS, TS | Optional | | **Ruff** | Python | Optional | ### Graceful Degradation All tools are optional. Missing tools result in warnings, not failures. --- ## Domain Glossary ### Core Entities | Term | Definition | | ---------------- | ----------------------------------------------------------- | | **Agent** | Specialized subagent spawned by Claude for specific domains | | **Skill** | Knowledge domain applied automatically when relevant | | **Command** | Slash command (`/project-starter:`) for workflows | | **Hook** | Automation script triggered on specific events | | **Orchestrator** | Master coordinator that delegates to specialist agents | ### Execution Patterns | Term | Definition | | ----------------------- | ----------------------------------------------------------------------------- | | **Parallel Execution** | N tasks spawned simultaneously using Task tool with `run_in_background: true` | | **Sequential Workflow** | Tasks executed one after another with dependencies | | **Task Synthesis** | Combining outputs from multiple parallel agents | | **Adversarial Review** | Using multiple agents to validate findings | ### Code Quality | Term | Definition | | ------------------- | ------------------------------------------------ | | **Code Smell** | Surface indicator of deeper structural problem | | **Technical Debt** | Cost of rework from choosing expedient solutions | | **Root Cause** | Why an error occurred, not just what/where | | **Regression Test** | Test ensuring bug doesn't reoccur after fix | ### Security | Term | Definition | | -------------------- | ----------------------------------------------- | | **OWASP Top 10** | Most critical web application security risks | | **Secret Detection** | Pattern matching for hardcoded credentials | | **File Protection** | Blocking edits to sensitive files (.env, locks) | --- ## Documentation Index | Document | Purpose | | ---------------------------------------- | --------------------------------------- | | [README.md](README.md) | Main documentation, quick start | | [CLAUDE.md](CLAUDE.md) | Development guidelines for contributors | | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute | | [CHANGELOG.md](CHANGELOG.md) | Version history | | [PERMISSIONS.md](PERMISSIONS.md) | Permission framework reference | | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community guidelines | | [examples/](examples/) | Multi-agent orchestration examples | | [templates/](templates/) | User-copyable configuration templates | ### Agent Documentation | Agent | File | | ---------------- | -------------------------------------------------------- | | Orchestrator | [agents/orchestrator.md](agents/orchestrator.md) | | Code Reviewer | [agents/code-reviewer.md](agents/code-reviewer.md) | | Debugger | [agents/debugger.md](agents/debugger.md) | | Security Auditor | [agents/security-auditor.md](agents/security-auditor.md) | | Test Architect | [agents/test-architect.md](agents/test-architect.md) | | Refactorer | [agents/refactorer.md](agents/refactorer.md) | | Docs Writer | [agents/docs-writer.md](agents/docs-writer.md) | ### Skill Documentation | Skill | File | | --------------------------- | ------------------------------------------------------------------------------------------ | | Analyzing Projects | [skills/analyzing-projects/SKILL.md](skills/analyzing-projects/SKILL.md) | | Convex Backend | [skills/convex-backend/SKILL.md](skills/convex-backend/SKILL.md) | | Database Design | [skills/database-design/SKILL.md](skills/database-design/SKILL.md) | | Designing Architecture | [skills/designing-architecture/SKILL.md](skills/designing-architecture/SKILL.md) | | Designing APIs | [skills/designing-apis/SKILL.md](skills/designing-apis/SKILL.md) | | Designing Tests | [skills/designing-tests/SKILL.md](skills/designing-tests/SKILL.md) | | DevOps Infrastructure | [skills/devops-infrastructure/SKILL.md](skills/devops-infrastructure/SKILL.md) | | Error Handling | [skills/error-handling/SKILL.md](skills/error-handling/SKILL.md) | | Managing Git | [skills/managing-git/SKILL.md](skills/managing-git/SKILL.md) | | Optimizing Performance | [skills/optimizing-performance/SKILL.md](skills/optimizing-performance/SKILL.md) | | Parallel Execution | [skills/parallel-execution/SKILL.md](skills/parallel-execution/SKILL.md) | | Security Patterns | [skills/security-patterns/SKILL.md](skills/security-patterns/SKILL.md) | | Vercel React Best Practices | [skills/vercel-react-best-practices/SKILL.md](skills/vercel-react-best-practices/SKILL.md) | | Web Design Guidelines | [skills/web-design-guidelines/SKILL.md](skills/web-design-guidelines/SKILL.md) | --- ## 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._