# Project Kickstart Templates

Templates for setting up a new project with full Claude Code infrastructure (v3.0.0).

---

## Overview

These templates provide a complete development system including:

- **5-Phase Lifecycle** - Specify, Design, Develop, Validate, Deploy
- **18 Hooks** - Safety, auditing, progress tracking, recovery
- **241 Primitives** - Atomic operations across 5 namespaces
- **31 Agents** - Specialized agents with 3-tier model selection (opus/sonnet/haiku)
- **47 Skills** - Slash commands for spec, design, develop, validate, deploy, git, and session management
- **3-Tier Context** - Standards, project specs, task-specific context
- **Quality Gates** - Tests, lint, typecheck with automated enforcement
- **Task Tracker Integration** - Abstract support for JIRA, GitHub Issues, or Linear

---

## Quick Start

### Option 1: Use `/new-project` Skill (Recommended)

```bash
/new-project
```

Interview-driven scaffolding that deploys all templates with your project values filled in.

### Option 2: Manual Setup

```bash
# Copy the entire template
cp -r scaffold/project/ /path/to/your/project/.claude/

# Rename CLAUDE.md template
mv /path/to/your/project/CLAUDE.md.project.template /path/to/your/project/CLAUDE.md

# Make hooks executable
chmod +x /path/to/your/project/.claude/hooks/*.sh

# Replace all {PLACEHOLDER} values
# See .claude/project-constants.md for the full placeholder list
```

---

## File Inventory

### Root Level (6 files)

| File                          | Purpose                                    |
| ----------------------------- | ------------------------------------------ |
| `CLAUDE.md.project.template`  | Project guidance for Claude Code           |
| `development-workflow.md`     | 5-phase lifecycle workflow specification   |
| `workflow-quick-reference.md` | Concise command reference                  |
| `workflow-diagrams.md`        | Visual workflow diagrams (Mermaid)         |
| `project-constitution.md`     | Governance, constraints, quality standards |
| `README.md`                   | This file                                  |

### .claude/ Directory

| Path                               | Count | Purpose                                               |
| ---------------------------------- | ----- | ----------------------------------------------------- |
| `.claude/agents/*.md`              | 30    | Agent definitions (lean format with YAML frontmatter) |
| `.claude/skills/*/SKILL.md`        | 44    | Skill definitions (slash commands)                    |
| `.claude/hooks/*.sh`               | 18    | Hook scripts (safety, audit, recovery)                |
| `.claude/primitives/**/*.md`       | 105+1 | Atomic operations + README                            |
| `.claude/context/standards/*.md`   | 3     | Coding standards (Python, TypeScript, Database)       |
| `.claude/context/project/.gitkeep` | 1     | Placeholder for synced specs                          |
| `.claude/handovers/.gitkeep`       | 1     | Placeholder for pre-compact handovers                 |
| `.claude/project-constants.md`     | 1     | Pre-computed project values                           |
| `.claude/settings.json.template`   | 1     | Hook and permission configuration                     |
| `catalog.yaml`                     | 1     | Unified catalog (components + skill metadata)         |

### MCP Configuration

No `.mcp.json` template ships. JIRA, Confluence, and Linear integrate via official Claude Code plugins (see `global/plugin-manifest.yaml` and `/eck:plugin-status`). For any other server, add a stanza to a project-root `.mcp.json` using the standard Claude Code format — ECK skills that need one (e.g. `/eck:switch-tracker`) supply a minimal stanza inline.

**Total: ~200 files**

---

## Agents (30)

### Opus Tier (Complex Reasoning)

| Agent               | Purpose                                |
| ------------------- | -------------------------------------- |
| backend-architect   | Technical architecture, service design |
| backend-designer    | Backend API design, data modeling      |
| frontend-architect  | Component architecture, state patterns |
| frontend-designer   | UI/UX design, visual specifications    |
| security-specialist | Security review (has FINAL AUTHORITY)  |

### Sonnet Tier (Implementation)

| Agent                   | Purpose                          |
| ----------------------- | -------------------------------- |
| backend-developer       | Python/FastAPI implementation    |
| backend-reviewer        | Backend code review              |
| backend-test-developer  | Backend test authoring           |
| bot-developer           | AI/Bot service implementation    |
| cpp-developer           | C/C++ implementation             |
| csharp-developer        | C#/.NET implementation           |
| dart-developer          | Dart/Flutter implementation      |
| database-specialist     | Schema, migrations, optimization |
| devops-engineer         | CI/CD, Docker, deployment        |
| frontend-developer      | React/TypeScript implementation  |
| frontend-reviewer       | Frontend code review             |
| frontend-test-developer | Frontend test authoring          |
| go-developer            | Go implementation                |
| integration-qa          | Cross-service testing            |
| java-developer          | Java implementation              |
| kotlin-developer        | Kotlin implementation            |
| php-developer           | PHP implementation               |
| ruby-developer          | Ruby implementation              |
| rust-developer          | Rust implementation              |
| swift-developer         | Swift implementation             |
| technical-writer        | Documentation                    |

### Haiku Tier (Pattern Matching)

| Agent           | Purpose                 |
| --------------- | ----------------------- |
| code-simplifier | Over-engineering review |
| backend-qa      | API testing             |
| frontend-qa     | E2E testing             |

---

## Skills (44)

### Specify Phase

| Skill          | Command           | Purpose                              |
| -------------- | ----------------- | ------------------------------------ |
| spec-scope     | `/spec-scope`     | Define feature scope and boundaries  |
| spec-discovery | `/spec-discovery` | Collaborative requirements discovery |
| spec-criteria  | `/spec-criteria`  | Acceptance criteria definition       |
| spec-questions | `/spec-questions` | Generate clarifying questions        |

### Design Phase

| Skill            | Command                  | Purpose                                            |
| ---------------- | ------------------------ | -------------------------------------------------- |
| design-feature   | `/design-feature <desc>` | Full feature design orchestrator                   |
| design-research  | `/design-research`       | Technical research and analysis                    |
| design-arch      | `/design-arch`           | System architecture and service decomposition      |
| design-solution  | `/design-solution`       | Component design and UI/UX patterns                |
| design-specs     | `/design-specs`          | API contracts, DB schemas, sequence diagrams       |
| design-discovery | `/design-discovery`      | Collaborative technical discovery for design phase |
| design-qa        | `/design-qa`             | QA plan and test strategy                          |
| design-adr       | `/design-adr`            | Architecture Decision Records                      |
| dev-plan         | `/dev-plan`              | Task breakdown from design artifacts               |
| design-risk      | `/design-risk`           | Risk assessment gate                               |
| design-document  | `/design-document`       | Design documentation                               |

### Develop Phase

| Skill           | Command                  | Purpose                          |
| --------------- | ------------------------ | -------------------------------- |
| dev-feature     | `/dev-feature <KEY>-XXX` | Execute all tasks under epic     |
| dev-task        | `/dev-task <KEY>-XXX`    | Single task TDD workflow         |
| dev-test        | `/dev-test`              | Generate failing tests (TDD red) |
| dev-feature-tdd | `/dev-feature-tdd`       | Full feature TDD workflow        |
| dev-sprint      | `/dev-sprint`            | Sprint execution workflow        |
| dev-simplify    | `/dev-simplify`          | Code simplification review       |

### Validate Phase

| Skill             | Command              | Purpose                  |
| ----------------- | -------------------- | ------------------------ |
| validate-quality  | `/validate-quality`  | Run all quality gates    |
| validate-code     | `/validate-code`     | Code review and analysis |
| validate-security | `/validate-security` | Security validation      |
| validate-ci       | `/validate-ci`       | CI pipeline diagnostics  |
| validate-uat      | `/validate-uat`      | User acceptance testing  |

### Deploy Phase

| Skill             | Command              | Purpose                 |
| ----------------- | -------------------- | ----------------------- |
| dev-branch        | `/dev-branch`        | Branch management       |
| dev-commit        | `/dev-commit`        | Commit workflow         |
| validate-merge    | `/validate-merge`    | Merge workflow          |
| dev-pr            | `/dev-pr`            | Pull request creation   |
| validate-approval | `/validate-approval` | PR review workflow      |
| dev-push          | `/dev-push`          | Push workflow           |
| deploy-release    | `/deploy-release`    | Release management      |
| deploy-status     | `/deploy-status`     | Deployment status check |
| deploy-tracker    | `/deploy-tracker`    | Tracker status updates  |

### Git & Workflow

| Skill         | Command              | Purpose                    |
| ------------- | -------------------- | -------------------------- |
| git-flow      | `/git-flow <action>` | Git workflow automation    |
| git-status    | `/git-status`        | Repository status overview |
| orchestrate   | `/orchestrate`       | Multi-skill orchestration  |
| evolve        | `/evolve`            | Project evolution workflow |
| start-project | `/start-project`     | Project initialization     |

### Documentation & Tracker

| Skill                   | Command                    | Purpose                            |
| ----------------------- | -------------------------- | ---------------------------------- |
| confluence              | `/confluence <action>`     | Confluence page management         |
| jira                    | `/jira <action>`           | JIRA issue management              |
| sync-context            | `/sync-context`            | Sync project docs to context files |
| refresh-project-catalog | `/refresh-project-catalog` | Refresh project catalog            |

### Session Management

| Skill            | Command             | Purpose                 |
| ---------------- | ------------------- | ----------------------- |
| learn            | `/learn <insight>`  | Quick learning capture  |
| retrospective    | `/retrospective`    | Session analysis        |
| heuristic-status | `/heuristic-status` | Heuristic system status |

---

## Hooks (18)

| Hook                    | Event                    | Purpose                              |
| ----------------------- | ------------------------ | ------------------------------------ |
| protect-files.sh        | PreToolUse (Edit/Write)  | Block edits to protected files       |
| detect-secrets.sh       | PreToolUse (Bash)        | Block committing secrets             |
| hitl-approval.sh        | PreToolUse (Bash)        | Block destructive operations         |
| planning-guard.sh       | PreToolUse (Task)        | Block dev agents during planning     |
| planning-bash-guard.sh  | PreToolUse (Bash)        | Block code execution during planning |
| planning-write-guard.sh | PreToolUse (Write)       | Block file writes during planning    |
| security-gate.sh        | PreToolUse               | Security gate enforcement            |
| audit-log.sh            | PostToolUse (all)        | Tool usage logging                   |
| checkpoint-save.sh      | PostToolUse (Edit/Write) | Progress snapshots                   |
| mcp-error-detect.sh     | PostToolUse (all)        | MCP error detection                  |
| heuristic-capture.sh    | PostToolUse              | Heuristic pattern capture            |
| heuristic-inject.sh     | PreToolUse               | Heuristic pattern injection          |
| error-detect.sh         | PostToolUseFailure (all) | Tool failure logging                 |
| stale-branch.sh         | SessionStart             | Branch hygiene warnings              |
| context-recovery.sh     | SessionStart             | Auto-restore from checkpoint         |
| session-auto-learn.sh   | SessionStart             | Auto-load learned patterns           |
| pre-compact.sh          | PreCompact               | Save handover before compression     |
| session-end-reminder.sh | Stop                     | Archive errors, session stats        |

---

## Primitives (16 Namespaces, 105 Files)

| Namespace      | Count | Purpose                                         |
| -------------- | ----- | ----------------------------------------------- |
| agent/         | 6     | Agent dispatch, orchestration, selection        |
| codebase/      | 3     | Search, explore, analyze                        |
| confluence/    | 7     | Page CRUD, search, labels (Confluence)          |
| git/           | 15    | Branch, commit, push, merge, PR, tag operations |
| github-issues/ | 12    | Issue CRUD, milestones, PRs (GitHub Issues)     |
| jira/          | 15    | Issue CRUD, sprint management, search (JIRA)    |
| linear/        | 9     | Issue CRUD, cycles, search (Linear)             |
| local-docs/    | 5     | Doc CRUD, search (local markdown)               |
| mode/          | 1     | Mode detection and switching                    |
| model/         | 2     | Model selection and configuration               |
| ops/           | 4     | Operational utilities                           |
| output/        | 2     | Visual framework, error handler                 |
| planning/      | 5     | Planning phase operations                       |
| review/        | 7     | Lint, test, typecheck, security scan            |
| task/          | 4     | Claude task create, update, list                |
| validation/    | 8     | Branch check, commit format, MCP health         |

---

## Placeholder Reference

| Placeholder               | Description             | Example                     |
| ------------------------- | ----------------------- | --------------------------- |
| `<PROJECT_NAME>`          | Project display name    | My Project                  |
| `<PROJECT_KEY>`           | Short project key       | MP                          |
| `<PROJECT_KEY_LOWERCASE>` | Lowercase project key   | mp                          |
| `<PROJECT_DESCRIPTION>`   | One-line description    | Internal training platform  |
| `<TRACKER_TYPE>`          | Task tracker type       | JIRA                        |
| `<TRACKER_URL>`           | Tracker URL             | https://myorg.atlassian.net |
| `<CONFLUENCE_SPACE_KEY>`  | Confluence space key    | MP                          |
| `<CONFLUENCE_SPACE_ID>`   | Confluence space ID     | 12345                       |
| `<MAIN_BRANCH>`           | Production branch       | main                        |
| `<DEV_BRANCH>`            | Integration branch      | dev                         |
| `<BACKEND_RUN_CMD>`       | Python runner           | uv run                      |
| `<BACKEND_PATH>`          | Backend repo path       | /path/to/project-be         |
| `<FRONTEND_PATH>`         | Frontend repo path      | /path/to/project-fe         |
| `<BACKEND_PORT>`          | Backend API port        | 8000                        |
| `<FRONTEND_PORT>`         | Frontend web port       | 3000                        |
| `<HOOK_COUNT>`            | Number of enabled hooks | 12                          |
| `<LABEL_PREFIX>`          | Confluence label prefix | mp                          |

See `.claude/project-constants.md` for the complete list.

---

## Standards Compliance

These templates follow standards from the evolv-coder-standards repository:

- `standards/documentation/` - Documentation formats
- `standards/architecture/` - Architectural patterns
- `standards/frontend/` - TypeScript, React standards
- `standards/backend/` - Python, FastAPI standards
- `standards/database/` - Schema, naming conventions
- `standards/devops/` - Git workflow, CI/CD

---

**Version**: 3.0.0
**Based on**: evolv-coder-standards
