Claude Development Template

A bootstrapping template for software projects built with Claude Code. Use it as a GitHub template, run /start, and Claude walks you through setting up all the documentation before a single line of code is written.

Conventions in this template are enforced — not just advisory. Lifecycle hooks, file-scoped rules, and MCP server configuration mean Claude follows the standards 100% of the time, not ~80%.

---

What This Is

This repository is an opinionated project scaffold that gives Claude everything it needs to act as a coherent development team from day one:

• Specialized agents for each discipline (architecture, frontend, mobile/React Native, backend, design, database, QA, CI/CD, Docker, docs, copywriting & SEO)
• Lifecycle hooks that fire automatically — blocking destructive commands, auto-formatting on save, and warning when docs fall out of sync with implementation
• MCP servers pre-configured for live library documentation and structured reasoning — shared across the whole team via a committed .mcp.json
• File-scoped rules that inject TypeScript, migration, and test standards only when the relevant file type is being edited
• Workflow skills (invoked as slash commands) for every common workflow: /orchestrate, /review, /release, /checkpoint, /status, /start, /sync-template
• Living documentation that agents keep up to date as the project evolves
• A product requirements document that serves as the authoritative source of truth — protected from accidental edits
• A backlog agents can reference when you ask “what should we work on next?”

---

How to Use

1. Create a new repository from this template

Click “Use this template” → “Create a new repository” on GitHub.

Or with the GitHub CLI:

gh repo create my-project --template https://github.com/josipjelic/orchestrated-project-template --private --clone && cd my-project

1b. Or: install into an existing project

Already have a codebase? Run this from the project root:

curl -fsSL https://raw.githubusercontent.com/josipjelic/orchestrated-project-template/main/install.sh | bash

The installer is non-destructive — it only adds what’s missing and never overwrites your files:

• .claude/ — agents, skills, hooks, rules, settings.json, doc templates (missing files only)
• .mcp.json, CLAUDE.md, TODO.md, START_HERE.md — only if absent
• docs/ skeleton — PRD.md plus every domain folder with its AGENTS.md rules file — missing files only
• .tasks/TASK_TEMPLATE.md and .github/PULL_REQUEST_TEMPLATE.md — only if absent
• Marks hook scripts executable and appends Claude runtime artifacts to .gitignore

If you already had a CLAUDE.md or .mcp.json, merge the template versions by hand (see .claude/templates/CLAUDE.md). Then open the project in Claude Code and run /start — it auto-detects the existing codebase, reads the code, and fills CLAUDE.md, docs/PRD.md, TODO.md, and the technical docs in docs/ from what it finds, asking you only the product questions the code can’t answer. It never overwrites your existing README.md.

Prefer not to pipe to bash? Clone the repo and copy the same paths manually, or review install.sh first — it’s ~50 lines.

2. Authenticate the GitHub CLI (optional)

gh auth login

Agents use gh directly for GitHub operations (issues, PRs, CI status). One-time setup — persists across all sessions automatically. Skip if you don’t need GitHub integration.

3. Open it in Claude Code and run /start

Claude will read START_HERE.md and begin the onboarding sequence — first detecting whether this is a new project or an existing codebase. New project: it interviews you and fills in all the documentation placeholders. Existing codebase: it reads the code, fills the docs from what it finds, and asks only what the code can’t answer.

4. Start building

Once onboarding is complete, START_HERE.md is deleted and the project is ready. Use TODO.md to see what to work on first, or run /status for a full project health overview.

---

Workflow Skills

Each workflow ships as a skill in .claude/skills/ and is invoked as a slash command. Claude can also invoke a skill autonomously when a task clearly matches its description.

/start

Run once after creating a new project. Claude reads START_HERE.md and walks you through the full onboarding sequence — gathering project details, copying documentation templates into place, filling in every placeholder, and building the initial backlog from your requirements.

/orchestrate

Hand off a multi-agent task and let Claude coordinate the execution. The orchestrator analyzes your task, identifies which specialists are needed, determines the correct execution order (parallel where safe, sequential where dependencies require it), registers the work in the backlog, creates a feature branch, and runs the agents wave by wave.

/orchestrate add user authentication with email and password

Presents a wave plan for your approval before anything runs. Stops and asks if a wave fails — never silently continues.

/review [branch or file]

Triggers a structured multi-agent code review scoped to the current branch diff (or a specific file/branch if provided). The systems-architect checks for architectural drift, the qa-engineer audits test coverage, and the relevant implementation agent checks code quality. Outputs a tiered report: required fixes, suggestions, and nice-to-haves.

/release [version]

Pre-release quality gate. Checks that the backlog is clear, then runs @qa-engineer, @documentation-writer, and @cicd-engineer in parallel. Compiles their results into a signed-off release checklist — and asks before proceeding if any blockers are found.

/checkpoint [description]

Safe-save before pausing a session. Verifies docs are current, runs available lint/tests, then commits all changes as chore(checkpoint): WIP — [description]. Useful before closing Claude or handing off to another session.

/status

Renders a live project health card: current branch, in-progress tasks, recent commits, open PRs (via gh pr list), blockers, and open PRD questions. Read-only — completes in seconds.

/sync-template

Pull the latest .claude/ directory from the upstream template repository into your project. Useful when agents are improved, new skills are added, or documentation templates are updated.

Shows a diff and asks for confirmation before changing anything. Local-only files are never deleted.

---

What’s Inside

├── CLAUDE.md                     # Master Claude instructions (auto-loaded every session)
├── TODO.md                       # Prioritized backlog — humans curate, agents consult
├── START_HERE.md                 # Onboarding protocol — deleted after setup
├── .mcp.json                     # MCP server config (sequential-thinking, context7)
├── .gitignore
│
├── .claude/
│   ├── settings.json             # Lifecycle hook configuration
│   ├── agents/                   # Specialist sub-agents
│   │   ├── project-manager.md    # Backlog governance & agent coordination
│   │   ├── systems-architect.md  # Architecture decisions & ADRs (Claude Opus)
│   │   ├── frontend-developer.md # UI components & pages
│   │   ├── react-native-developer.md # Mobile screens, navigation & native modules
│   │   ├── backend-developer.md  # API endpoints & business logic
│   │   ├── ui-ux-designer.md     # UX flows & design system specs
│   │   ├── database-expert.md    # Schema design & migrations
│   │   ├── qa-engineer.md        # Playwright E2E tests
│   │   ├── documentation-writer.md # User guide & project docs
│   │   ├── cicd-engineer.md      # GitHub Actions workflows & deployment pipelines
│   │   ├── docker-expert.md      # Dockerfiles, Compose, image optimization
│   │   └── copywriter-seo.md     # Conversion copy, brand voice, keyword strategy, technical SEO
│   ├── skills/
│   │   ├── orchestrate/SKILL.md  # /orchestrate — multi-agent task execution
│   │   ├── review/SKILL.md       # /review — multi-agent code review
│   │   ├── release/SKILL.md      # /release — pre-release QA + docs + CI/CD pass
│   │   ├── checkpoint/SKILL.md   # /checkpoint — save, verify docs, commit WIP
│   │   ├── status/SKILL.md       # /status — live project health card
│   │   ├── start/SKILL.md        # /start — runs the onboarding protocol
│   │   └── sync-template/SKILL.md # /sync-template — pulls latest .claude/ from upstream
│   ├── hooks/                    # Lifecycle hook scripts (chmod +x, called by settings.json)
│   │   ├── guard-destructive.sh  # PreToolUse: blocks rm -rf, force push, DROP TABLE, etc.
│   │   ├── format-on-write.sh    # PostToolUse: auto-formats saved files (prettier, ruff, gofmt…)
│   │   ├── validate-completion.sh # Stop: warns if docs/TODO weren't updated with code changes
│   │   └── log-agent.sh          # SubagentStart: audit trail → .claude/agent-log.txt
│   ├── rules/                    # File-scoped rules — injected only when matching files are open
│   │   ├── typescript.md         # *.ts, *.tsx — no any, strict null, explicit returns
│   │   ├── migrations.md         # *.sql, migrations/** — reversible, naming convention
│   │   └── tests.md              # *.spec.ts, *.test.ts — POM, data-testid, no test.only
│   └── templates/                # Blank doc templates — synced from upstream via /sync-template
│       ├── CLAUDE.md             # Master Claude instructions template
│       ├── README.md             # Project README template
│       ├── docs/                 # Mirrors the project docs/ tree — every folder ships with its AGENTS.md rules file
│       │   ├── AGENTS.md         # Top-level docs structure rules & folder map
│       │   ├── PRD.md            # Product requirements template
│       │   ├── FEATURE_TEMPLATE.md # Per-feature doc template — endpoints, integrations, Mermaid flows
│       │   ├── architecture/     # ARCHITECTURE.md, DECISIONS.md
│       │   ├── frontend/         # FRONTEND.md
│       │   ├── backend/          # BACKEND.md, API.md
│       │   ├── database/         # DATABASE.md
│       │   ├── design/           # DESIGN_SYSTEM.md
│       │   ├── devops/           # DEVOPS.md
│       │   ├── user/             # USER_GUIDE.md
│       │   ├── stakeholders/     # STAKEHOLDER_BRIEF.md
│       │   └── content/          # CONTENT_STRATEGY.md
│       └── .tasks/
│           └── TASK_TEMPLATE.md  # Task file template
│
├── .github/
│   └── PULL_REQUEST_TEMPLATE.md  # Enforces consistent PR descriptions
│
├── .tasks/                       # Detailed task files — one per TODO item
│   └── TASK_TEMPLATE.md          # Copy this when creating new tasks
│
└── docs/                         # All project documentation — one folder per domain, each governed by its AGENTS.md;
                                  # bigger features get their own .md inside the owning folder
    ├── AGENTS.md                 # Docs structure rules & folder map (ships with the template)
    ├── PRD.md                    # Product Requirements Document — agents read, never modify
    ├── architecture/             # ARCHITECTURE.md + DECISIONS.md (ADR log) — @systems-architect
    ├── frontend/                 # FRONTEND.md — architecture, conventions, state & routing — @frontend-developer
    ├── backend/                  # BACKEND.md + API.md — services, business logic, endpoint reference — @backend-developer
    ├── database/                 # DATABASE.md — schema, migrations, query patterns — @database-expert
    ├── design/                   # DESIGN_SYSTEM.md — tokens, UX specs, component inventory — @ui-ux-designer
    ├── devops/                   # DEVOPS.md — environments, pipeline, deployment runbook — @cicd-engineer
    ├── user/                     # USER_GUIDE.md — how the system is used (user perspective)
    ├── stakeholders/             # STAKEHOLDER_BRIEF.md — plain-language status & scope
    └── content/                  # CONTENT_STRATEGY.md — brand voice, keywords, copy library — @copywriter-seo

---

Agents

Each agent is a specialist Claude sub-agent with a defined role, document ownership, working protocol, and scoped MCP access.

Models are assigned by alias (opus, sonnet, haiku), so agents automatically track the current Claude model family — as of the Claude 5 generation, opus resolves to Claude Opus 4.8 and sonnet to Claude Sonnet 5. Swap any agent’s alias for fable (Claude Fable 5, Anthropic’s most capable model) if a project warrants the extra cost.

Claude selects agents automatically based on context, or you can invoke them directly.

---

Key Conventions

Commits — Conventional Commits:

feat(auth): add OAuth2 login with Google
fix(api): handle null response from payment provider

Branches:

feature/-short-description
fix/-short-description

PRD is read-only — docs/PRD.md is protected by a three-layer mechanism (warning block, CLAUDE.md rule, and agent system prompts). Agents will refuse to modify it without explicit human instruction.

Documentation stays current — Agents are required to update the relevant docs/ file before marking any implementation task complete. The validate-completion.sh hook warns at the end of every turn if this hasn’t happened.

Conventions are enforced, not advisory — The guard-destructive.sh hook blocks dangerous commands at the tool call level (100% enforcement), and format-on-write.sh runs the project formatter automatically on every save. File-scoped rules in .claude/rules/ inject TypeScript, migration, and test standards only when the matching file type is active — keeping context tight and standards precise.

---

Design Principles

• Design before code — the Systems Architect agent produces specs and ADRs; specialists implement
• Copy before implementation — the Copywriter & SEO agent defines page copy, CTAs, and keyword targets before @frontend-developer builds marketing pages
• Document ownership — every docs/ file has a declared owner agent; others don’t overwrite
• Append-only ADRs — architectural decisions are never silently revised; a new ADR supersedes an old one
• Tests map to requirements — QA writes tests against FR-XXX items in the PRD, not implementation details
• TODO.md is human territory — agents read the backlog to suggest work; they never auto-modify it
• Hooks over instructions — destructive command blocking, auto-formatting, and completion checks are implemented as shell scripts that fire 100% of the time, not as text instructions that agents can overlook
• Scoped context — rules and MCP tools are granted per-agent and per-file, not globally; database-expert gets database docs, systems-architect gets structured reasoning, and TypeScript rules only appear when a .ts file is open

---

License

MIT