research-notes/blog/content/notes/005-project-setup/meta.yaml

id: "005"
slug: 005-project-setup
date: "2026-02-07"
title: Project Setup
preview: "Creating expert agents and setting up quality hooks before writing any code."

prompts:
  - id: pick-agents
    label: Pick expert agents
    content: |
      What 3 people in the world would be best at working on this project? Pick from a diverse set.      

  - id: create-agents
    label: Create agents
    content: |
      /do-parallel /create-agent for each      

  - id: scaffold
    label: Scaffold project
    content: |
      /scaffold      

  - id: create-docs
    label: Create docs
    content: |
      Create a basic readme.md and quickstart.md      

  - id: verify
    label: Verify setup
    content: |
      Run through the quickstart and pre-commit hooks and make sure everything works properly      

skillsUsed:
  - name: create-agent
    command: /create-agent
    description: Create a new Claude Code agent for specialized tasks

  - name: scaffold
    command: /scaffold
    description: Initialize a new project with hello world + quality hooks
    usage: |
      ---
      name: project-skeleton
      description: Initialize a new project with hello world + quality hooks. Use when starting any new project.
      ---

      # Project Skeleton

      ## Identity

      You run `cargo new` and `/setup-hooks`. That's it.

      ## What This Does

      1. Initialize a hello world project
      2. Install pre-commit hooks
      3. Verify it builds

      ## Protocol

      ### Phase 1: Detect or Ask Project Type

      | Signal | Type | Init Command |
      |--------|------|--------------|
      | `Cargo.toml` exists or "Rust" mentioned | Rust | `cargo new` or `cargo init` |
      | `package.json` exists or "TypeScript/Node" mentioned | TypeScript | `npm init -y && npm i -D typescript && npx tsc --init` |
      | `go.mod` exists or "Go" mentioned | Go | `go mod init` |
      | `pyproject.toml` exists or "Python" mentioned | Python | `uv init` or `poetry init` |

      If unclear, ask.

      ### Phase 2: Initialize

      Run the init command. That's the scaffold.

      For workspaces/monorepos, create the workspace manifest and one hello-world member.

      ### Phase 3: Setup Hooks

      Run `/setup-hooks` or apply the `quality-gates` skill.

      ### Phase 4: Verify

      Run the build command:
      - Rust: `cargo check`
      - TypeScript: `npx tsc --noEmit`
      - Go: `go build ./...`
      - Python: `python -c "import <package>"`

      If it doesn't build, fix it until it does.

      ## Do

      1. Run the language's standard init command
      2. Install pre-commit hooks
      3. Verify it builds

      ## Do Not

      1. Write application code
      2. Define types, traits, interfaces
      3. Create stubs or mocks
      4. Add dependencies beyond hello world
      5. Create multiple files beyond what init produces
      6. Read project specs/roadmaps and implement them

      ## Constraints

      - NEVER write more than what `cargo new` / `npm init` / `go mod init` produces
      - ALWAYS install hooks before declaring done
      - ALWAYS verify the build succeeds      

  - name: setup-hooks
    command: /setup-hooks
    description: Set up and maintain pre-commit hooks and CI quality checks
    usage: |
      ---
      name: quality-gates
      description: Set up and maintain pre-commit hooks and CI quality checks. Use when configuring automated quality enforcement.
      ---

      # Quality Gates

      Enforce code quality automatically. Catch problems on commit, not in CI.

      ## Check Categories

      ### Pre-commit (fast, <10s, staged files only)

      | Check | Purpose | Auto-fix? |
      |-------|---------|-----------|
      | Formatting | Consistent style | YES |
      | Import sorting | Organized imports | YES |
      | Linting | Bug patterns, code smells | PARTIAL |
      | Type checking | Type safety | NO |
      | File length | Maintainability (max 500) | NO |
      | Function length | Readability (max 100) | NO |
      | Complexity | Cognitive load (max 15-25) | NO |

      ### CI (slow, full repo)

      | Check | Purpose |
      |-------|---------|
      | Circular dependencies | Module health |
      | Code duplication | DRY violations |
      | Dead code | Unused exports/functions |
      | Security audit | Vulnerabilities |
      | Test coverage | Quality gates |

      ## Tool Matrix

      | Check | Go | TypeScript | Rust | Python |
      |-------|-----|------------|------|--------|
      | Format | gofmt | prettier | rustfmt | black/ruff |
      | Imports | goimports | eslint-plugin-import | rustfmt | isort/ruff |
      | Lint | golangci-lint | eslint | clippy | ruff |
      | Types | compiler | tsc | compiler | mypy/pyright |
      | Complexity | gocyclo | eslint complexity | clippy | radon/ruff |
      | Circular | go-cycles | madge | cargo-depgraph | pydeps |
      | Duplication | dupl | jscpd | cargo-clone | jscpd |
      | Dead code | deadcode | knip/ts-prune | cargo-udeps | vulture |

      ## Hook Structure

      Use two-phase approach:

      ```
      PHASE 1: AUTO-FIX
        → Run formatters on staged files
        → Run linters with --fix
        → Re-stage fixed files

      PHASE 2: VERIFY
        → Check formatting (should pass after phase 1)
        → Run linting (unfixable issues)
        → Type check
        → File length check
        → Complexity check
        → Custom project rules
      ```

      ## Threshold Defaults

      | Metric | Default | Rationale |
      |--------|---------|-----------|
      | File length | 500 lines | Fits in head |
      | Function length | 100 lines | Single responsibility |
      | Cyclomatic complexity | 15-25 | Testable |
      | Duplication | 5+ lines | Worth abstracting |
      | Max pre-commit time | 10s | Won't get disabled |

      ## Do

      - Keep pre-commit under 10 seconds
      - Check staged files only
      - Auto-fix then verify
      - Re-stage fixed files
      - Provide fix commands in errors
      - Split slow checks to CI

      ## Do Not

      - Run full test suite on commit
      - Check entire codebase on commit
      - Make hooks so slow they get disabled
      - Fail without explaining how to fix
      - Skip the auto-fix phase      

filesCreated: []

navigation:
  prev:
    slug: 004-hydrating-the-roadmap
    id: "004"
    title: Hydrating the Roadmap
  next: null