Infrastructure Setup

Gathering Project Context

Read project-knowledge references:

• .claude/skills/project-knowledge/references/architecture.md — tech stack, framework
• .claude/skills/project-knowledge/references/patterns.md — code conventions, branching strategy, testing
• .claude/skills/project-knowledge/references/deployment.md — deployment strategy

If files lack needed info, search other project-knowledge references — info may exist under different names. Inside an engagement you cannot reach the user: if a fact is missing entirely, take the convention below, write it into the relevant doc as a decision with its reason, and list it in your report.

Autonomous decisions (based on project-knowledge):

• Framework init commands, folder structure, test framework, .gitignore patterns

Decided before the engagement (the user answered these in the bootstrap interview):

• Docker: needed? Local dev, production, or both?
• Pre-commit strictness: gitleaks only, or add lint/format?

Read them from the brief's §Infrastructure: {ENG}/specs/project-brief.md, in the canonical engagement directory your prompt names, not in your worktree. Without a brief, or when it is silent: Docker only if deployment.md names a container platform; pre-commit per Phase 5. Record the choice in your report.

Phase 1: Framework Initialization

Init framework from architecture.md. Use Context7 for up-to-date init commands and flags. Verify it starts.

Checkpoint: dev server starts successfully.

Phase 2: Folder Structure

Convention — separate concerns by purpose:

• Web Apps: src/{components, services, lib, config} + tests/{unit, integration, e2e}
• APIs: src/{routes, services, models, middleware, config} + tests/{unit, integration}
• CLI tools: src/{commands, services, config} + tests/{unit, integration}

Add src/prompts/ if project uses LLM prompts. Add src/messages/ if project uses i18n.

Checkpoint: structure created, matches project type.

Phase 3: Docker (conditional)

Set up only if specified in project-knowledge or in the brief's Infrastructure section. Start .dockerignore from ~/.claude/shared/templates/infrastructure/static/.dockerignore and trim it to the stack.

Checkpoint: docker build succeeds, container starts.

Phase 4: .gitignore

Security patterns (always add):

.env
.env.*
!.env.example
*.key
*.pem
credentials.json
secrets/

Add framework-specific patterns from architecture.md. Create .env.example with required variable names (no values).

Checkpoint: git check-ignore .env returns .env.

Phase 5: Pre-commit Hooks

Convention: gitleaks for secret scanning. Target: total pre-commit time under 10 seconds. Starting points: ~/.claude/shared/templates/infrastructure/static/husky-pre-commit-gitleaks.sh (Node, husky) and ~/.claude/shared/templates/infrastructure/static/pre-commit-config.yaml (Python, pre-commit framework).

Pre-commit scope (fast, staged files only):

• gitleaks (~2-5 seconds), always
• Lint staged files, unless the brief's Infrastructure section says gitleaks only
• Format check, same condition

Full test suites, integration tests, builds belong in CI.

Checkpoint: commit a file containing AKIA1234567890EXAMPLE — gitleaks blocks it.

Phase 6: Testing Infrastructure

Set up test framework, create smoke test: 1-2 tests verifying setup works (import main module, check environment). Starting points: ~/.claude/shared/templates/infrastructure/tests/smoke.test.ts (Vitest) and ~/.claude/shared/templates/infrastructure/tests/test_smoke.py (pytest); replace the placeholder test with a real import of the main module.

Checkpoint: test command passes.

Phase 7: Documentation & Commit

Update project-knowledge references (append, don't overwrite):

• deployment.md — required environment variables
• patterns.md (Git Workflow section) — pre-commit hooks and what they check

Commit (outside an engagement only; inside one the engine's task prompt owns the single commit, so skip this step there or that commit finds nothing and fails):

chore: setup project infrastructure

- Initialize [framework] project
- Setup pre-commit hooks (gitleaks)
- Create folder structure
- Add testing infrastructure
- Configure .gitignore and .env.example
[- Setup Docker (if applicable)]

Verify before commit: git status shows no .env files (only .env.example).

Final Validation

• Framework runs locally
• Folder structure matches convention
• gitleaks blocks test secret
• .gitignore covers .env, *.key, secrets
• .env.example exists (if project uses env vars)
• Smoke test passes
• Documentation updated
• All infrastructure committed (outside an engagement); inside one, all intended changes present in the worktree and ready for the engine's commit
• Docker works (if applicable)