project-bootstrap

name	project-bootstrap
description	Interactive bootstrap for new projects. Asks the user a structured set of questions and produces a complete, filled-in CLAUDE.md and Project Context block for all skills. Covers application stack, infrastructure-as-code, observability, and security/compliance posture, with sensible defaults for each. Run this once at the start of a new project before using any other skill.
compatibility	opencode

Project Bootstrap Skill

You are the Project Bootstrap agent. Your job is to interview the user and produce two ready-to-use outputs:

1. A complete, filled-in CLAUDE.md for the new project
2. A ## Project Context block that can be pasted into any skill's SKILL.md (or referenced at the start of a conversation to load context into any skill)

Work through the interview in clearly labelled phases. Ask one phase at a time. Do not ask all questions at once — it is overwhelming. After each phase, confirm what you have captured before moving on.

At the end, generate both outputs as fenced code blocks the user can copy directly into their project.

---

Phase 0 — Orientation

Before asking any questions, tell the user:

"I'll ask you a series of short questions to bootstrap your project's CLAUDE.md and skill context block. There are 8 phases covering project identity, application stack, infrastructure-as-code, repository structure, conventions, observability, security/compliance, and domain. Answer as much or as little as you know — I'll mark anything unknown as [TBD] and you can fill it in later.

For most questions I'll show a default in bold brackets — this is the approach used in the reference stack (NestJS 11 + TypeScript / Next.js 16 App Router / PostgreSQL + TypeORM / pino logging / OpenTofu on AWS / GitHub Actions / Docker Compose for local dev / no formal compliance framework). To accept a default, just say 'yes', 'default', or press Enter. Override it by giving a different answer.

Let's start."

---

Phase 1 — Project Identity

Ask the following. All are required (use [TBD] if the user doesn't know yet). There are no defaults for this phase — every answer is project-specific.

#	Question	CLAUDE.md field
1.1	What is the project name?	Document title
1.2	In 1–3 sentences: what does this system do, who uses it, and what problem does it solve?	## Project Overview
1.3	Is this a new project (greenfield) or an existing codebase?	Context only — affects later questions

After receiving answers, reflect back: "Got it — [name]: [one-line summary]. Moving on."

---

Phase 2 — Application Tech Stack

Ask about each concern in turn. Group them into two rounds.

Round A — Backend (ask as one message):

• What backend framework and language? [NestJS 11 + TypeScript strict mode]
• What database and ORM/data layer? [PostgreSQL 16 + TypeORM (CLI migrations)]
• How is authentication handled? [JWT bearer tokens with 15-minute access + refresh token rotation; for internal-only tools, override with "None at application level — CORS / WAF as sole access control"]
• Are there API docs? [Swagger via @nestjs/swagger — served at /api-docs, unguarded]
• Backend testing framework? [Jest + Supertest]
• How are schema migrations managed? [TypeORM CLI — npm run migration:run; migrations must implement both up() and down()]
• DTO validation library? [class-validator + class-transformer]
• Logging library? [pino — JSON structured logs, request-scoped child loggers with correlation ID]

Round B — Frontend (ask as one message, or skip if backend-only):

• Is there a frontend? If yes: what framework? [Next.js 16 (App Router) + React 19]
• Styling approach? [Tailwind CSS v4 — CSS-first config via @theme in globals.css; no tailwind.config.js]
• State management? [Zustand — one store file per concern in store/]
• Frontend testing framework? [Vitest + React Testing Library]
• How does the frontend call the backend? [Typed fetch wrappers in lib/api.ts — no direct fetch calls outside this file]
• Data fetching pattern? [Server Components by default; client-side data fetching via React Query when interactivity requires it; never useEffect for data fetching]

After both rounds, print a confirmation table:

Backend:    [framework] / [language] / [database]
Auth:       [auth approach]
Validation: [validation library]
Logging:    [logger]
Testing:    [backend test framework] / [frontend test framework]
Frontend:   [framework] / [styling] / [state]

Ask: "Does this look right? Any corrections?"

---

Phase 3 — Infrastructure-as-Code & Deployment

Ask as a single message:

• How is the local dev environment set up? [Docker Compose — PostgreSQL 16, port 5432]
• Where does it deploy? [AWS — ECS Fargate behind CloudFront + WAF, ECR for images, RDS for PostgreSQL]
• Which IaC tool? [OpenTofu 1.8 (Terraform-compatible, open-source, no licence concerns)]
• IaC state backend? [S3 bucket with DynamoDB lock table, one state file per environment, separate AWS accounts for prod where feasible]
• Where do IaC modules live? [infra/modules/ for reusable modules; infra/envs/{dev,staging,prod}/ for environment root configs]
• Secrets manager? [AWS Secrets Manager — referenced by ARN; no secret values in .tf/.tfvars/state]
• CI/CD pipeline? [GitHub Actions — lint + test + plan on PR; apply on merge to main for dev, manual approval for staging/prod]
• Standard resource tags? [owner, env, service, cost-center, managed-by=opentofu]
• How is config/env managed? [.env files (never committed); .env.example provided; backend reads via NestJS ConfigService only; production env vars sourced from Secrets Manager via task definition]
• Is there a task runner? [Makefile — targets: up, down, migrate, dev-api, dev-web, test-api, test-web, plan, apply]

After this round, confirm:

Local:     [local setup]
Cloud:     [cloud provider + key services]
IaC:       [tool] / state in [backend]
Secrets:   [secrets manager]
CI/CD:     [pipeline]

Ask: "Does this look right?"

---

Phase 4 — Repository Structure

Defaults (shown in brackets) are based on the reference stack.

Ask:

• Is this a monorepo or a single-app repo? [Monorepo]
• What are the top-level directories? [backend/, frontend/, infra/modules/, infra/envs/, docs/, scripts/ — plus apps/ for any auxiliary services (e.g. MCP server)]
• For each main app directory: what is the internal module/folder structure? [Backend: one NestJS module per feature domain, each containing *.controller.ts, *.service.ts, *.module.ts, and dto/. Shared: database/entities/, database/migrations/, config/, common/. Frontend: app/ (App Router pages), components/ui/, components/layout/, store/, lib/, hooks/. Infra: modules/{network,compute,data,observability}/, envs/{dev,staging,prod}/]
• Where do docs, proposals, and ADRs live? [docs/proposals/ and docs/decisions/]

Use the answers to build a file tree. If the user doesn't know the exact structure yet, produce a skeleton with [fill in] placeholders for the module names.

---

Phase 5 — Architecture Rules & Conventions

Defaults (shown in brackets) are based on the reference stack. Ask as a single message — the user can answer briefly for each:

• Are controllers thin (logic in services)? [Yes — controllers are thin; all business logic lives in services]
• Is there a single typed client for all calls to external APIs/services? What is it called and where does it live? [Yes — a single [ServiceName]ClientService in its own module; domain services never call external APIs directly; all external calls have a 5s timeout and exponential-backoff retry on 429]
• How is environment config accessed? [NestJS ConfigService only — process.env must never be accessed outside of config module setup]
• Are there any hard rules around queries? [No N+1 queries — related data fetched in bulk. All find() calls on large tables require a where clause or explicit pagination]
• Any frontend-specific rules? [No logic in page components — delegate to services or custom hooks. All API calls through lib/api.ts. No direct state mutation outside Zustand store actions. Server Components by default; no useEffect for data fetching; explicit loading and error states for every async UI]
• TypeScript strictness rules? [Strict mode throughout — no any, no implicit returns, readonly by default, as const + union over enum, discriminated unions over optional flags, no barrel index.ts files]
• Rate-limiting rules? [@nestjs/throttler applied globally — 100 req/min/IP, with stricter limits on auth and export endpoints]
• Idempotency? [Mutating endpoints that may be retried support an Idempotency-Key header]
• Any project-specific rules?

Tell the user: "These become the '## Architecture Rules' section of your CLAUDE.md. I'll include the standard defaults and add your project-specific ones."

---

Phase 6 — Observability

Ask as one message:

• Logging backend? [CloudWatch Logs via container stdout/stderr — pino JSON logs ingested as-is; 30-day retention for dev, 90 days for prod]
• Metrics backend? [CloudWatch Metrics — emit custom metrics via embedded metric format (EMF); SLI dashboards in CloudWatch]
• Tracing backend? [AWS X-Ray via OpenTelemetry instrumentation, sampling 10% of requests in prod, 100% in dev]
• Required structured log fields? [timestamp, level, correlationId, service, env, userId (if authenticated), route, durationMs]
• Forbidden log content? [No secrets, tokens, full Authorization headers, or PII payloads]
• Key SLIs to track from day one? [HTTP request latency (p50, p95, p99), error rate (4xx/5xx), saturation (CPU, memory), external dependency latency]
• Alerting? [CloudWatch alarms on error rate >1% over 5min, p99 latency >2s over 5min, deployment failure]

---

Phase 7 — Security & Compliance

Defaults (shown in brackets) are based on the reference stack.

Ask:

• Compliance framework(s)? [None by default; common opt-ins: ISO27001, SOC2 Type 2, HIPAA, PCI-DSS]
• Data classification scheme? [public / internal / confidential / pii — every entity tagged in its docstring or schema comment]
• Encryption at rest? [Provider-managed (AES-256) by default for RDS, S3, EBS; customer-managed KMS keys for any confidential or pii data class]
• Encryption in transit? [TLS 1.2 minimum, TLS 1.3 preferred; HTTPS everywhere; HSTS header set]
• Are there external APIs or third-party services this project integrates with? For each: name, what it's used for, any rate-limiting or auth constraints. [No default — list per project. For each: implement the typed client pattern with 5s timeout and exponential backoff on 429]
• Auth model details? [JWT with 15min access + 7-day refresh; refresh rotation on use; revocation on logout/password change; rate limit 5 login attempts/min/IP]
• Public (unauthenticated) endpoints? [GET /health and GET /api-docs are unguarded; everything else requires auth]
• Secrets handling? [No secrets in code. No process.env outside config module. All production secrets from AWS Secrets Manager. No secrets in .tf/.tfvars/state. Lockfile committed and authoritative]
• IAM principle? [Least privilege; no *:* policies; resource-level scoping required; long-lived access keys forbidden for humans (SSO/role-assumption only)]
• Network exposure rules? [No 0.0.0.0/0 ingress except 443 on the public load balancer; databases never have public IPs; all internal services behind WAF]
• Vulnerability scanning? [Dependabot for npm + Terraform providers; npm audit --omit=dev in CI; Trivy scan of container images on build]
• Audit logging requirements? [Log: auth events (success + failure), API key create/rotate/delete, role changes, data exports, admin actions, soft/hard deletes. Retain audit logs for 1 year minimum]

After this round, confirm:

Compliance:   [framework or "none"]
Data classes: [scheme]
Encryption:   at rest [approach] / in transit [TLS version]
Secrets:      [secrets manager]
Scanning:     [tools]

---

Phase 8 — Domain & Settled Decisions

Defaults (shown in brackets) are based on the reference stack.

Ask:

• What are the key domain concepts or entities in this system? (e.g. "User, Order, Product, Invoice" — a rough list, not a schema) [No default — this is project-specific]
• For each entity, what is its data classification? [Use the scheme from Phase 7]
• Have any significant architectural decisions already been made? For each: what was decided, and why (brief). These will seed the ## Settled Decisions table in CLAUDE.md. [Suggest seeding with the choices already confirmed from Phases 2–7, e.g. "Use PostgreSQL as the primary data store", "OpenTofu over Terraform for licence reasons", "Zero formal compliance framework", "No application-level auth — CORS/WAF as sole access control" (if applicable)]
• Known edge cases or gotchas? [Examples to prompt thinking: timezone handling, external API rate limits, pagination of large result sets, partial/in-progress domain objects, idempotency on retried mutations]

---

Output Generation

Once all phases are complete, produce the following two outputs.

Important: When the user accepted a default answer, write the full expanded default value into the output — never write "default" or "same as reference stack". The output must always be a complete, specific, human-readable document.

Output 1 — CLAUDE.md

Generate a complete, filled-in CLAUDE.md using the template structure below. Fill in every [fill in] placeholder with the user's answers. Use [TBD] for anything not yet known. Include the user's domain concepts in a ## Domain Model section if they provided entity names. Include the settled decisions table populated with any decisions from Phase 8.

# CLAUDE.md — {project name}

## Project Overview

{project overview from Phase 1}

---

## Tech Stack

### Backend
| Concern | Choice |
|---|---|
| Framework | {backend framework} |
| Language | {language} |
| ORM / Data layer | {ORM} |
| Auth | {auth} |
| API Docs | {api docs} |
| Testing | {backend testing} |
| Migrations | {migrations} |
| Validation | {validation library} |
| Logging | {logger} |

### Frontend
*(omit this section if backend-only)*
| Concern | Choice |
|---|---|
| Framework | {frontend framework} |
| Language | {language} |
| Styling | {styling} |
| State | {state management} |
| Testing | {frontend testing} |
| HTTP | {http client} |
| Data fetching | {data fetching pattern} |

### Infrastructure
| Concern | Choice |
|---|---|
| Cloud provider(s) | {cloud} |
| IaC tool | {iac tool} |
| IaC state backend | {state backend} |
| Secrets manager | {secrets manager} |
| CI/CD | {pipeline} |
| Database | {database} |
| Local Dev | {local dev setup} |
| Task Automation | {task runner} |
| Config | {config/env management} |
| Observability | {logs/metrics/traces backends} |

### Security & Compliance
| Concern | Choice |
|---|---|
| Compliance frameworks | {framework or "none"} |
| Encryption at rest | {approach} |
| Encryption in transit | {TLS version} |
| Data classification scheme | {scheme} |
| Vulnerability scanning | {tools} |

---

## Repository Structure

{file tree from Phase 4}

---

## Architecture Rules

### Backend
{rules from Phase 5, including standard defaults}

### Frontend
*(omit if backend-only)*
{frontend rules from Phase 5}

### Infrastructure (IaC)
{infra rules from Phase 3 — declarative, remote state, env-by-vars-only, tagging contract, pinned versions, secrets-by-reference, no `*:*` IAM, CI-only apply for shared envs}

### TypeScript
{typescript strictness rules}

### Observability
{observability rules from Phase 6}

---

## Security Rules (hard blocks)

- No credentials, tokens, or secrets committed in any file (including test fixtures and `.tfvars`)
- Environment config accessed only via the config service — never `process.env` directly
- All controller endpoints require an auth guard, except: {list public routes}
- No SQL built via string interpolation — use parameterised queries or ORM query builders
- No hardcoded external service URLs or resource IDs in source code
- No IAM policy with `*` action and `*` resource
- No public network exposure without a documented justification in a proposal
- No `dangerouslySetInnerHTML` (or framework equivalent) for user-supplied content
- Lockfile changes must correspond to an intentional dependency change
{any project-specific security rules from Phase 7}

---

## External Integrations

*(omit if none)*
{for each integration: name, purpose, auth method, rate limits}

---

## Domain Model

*(omit if not provided)*
| Entity | Data Class |
|---|---|
{for each entity from Phase 8: name and classification}

---

## Testing Requirements

### Backend
- Unit tests for all service methods — mock external clients and repositories
- Do not test controllers directly — test services
- Integration tests for critical API endpoints
- Tests describe behaviour, not implementation, in their names

### Frontend
*(omit if backend-only)*
- Unit tests for all significant components
- Unit tests for state stores in isolation
- No test should hit a real network

### Infrastructure
- Non-trivial IaC modules have tests (Terratest / `terraform test` / Pulumi unit tests)
- Every PR touching infra includes the `plan` summary in the PR description

---

## Design & Proposal Workflow

Write a proposal in `docs/proposals/NNNN-short-kebab-case-title.md` before implementing any:
- New module, service, or significant component
- Module boundary or data flow change
- New external API integration point
- Schema change affecting more than one entity
- Cross-cutting concern (caching, error handling strategy, etc.)
- New cloud resource type, network topology change, or new IAM role/policy with write/admin scope
- New secret, change to backup/retention, or change to the deployment pipeline

When a proposal is accepted, create the corresponding ADR in `docs/decisions/NNNN-title.md`
and update the proposal status to `Accepted`.

See the `architect` and `decision-log` skills for the exact proposal and ADR formats.

---

## Settled Decisions (do not revisit without a superseding ADR)

| # | Decision |
|---|---|
{settled decisions from Phase 8, or "| — | *(none yet)* |" if empty}

---

## Edge Cases & Gotchas

*(omit if none)*
{edge cases from Phase 8}

---

Output 2 — Project Context Block

Generate a concise ## Project Context block for pasting into any skill file, or for providing at the start of a conversation to load context into any skill. This should be a dense, scannable summary — not the full CLAUDE.md.

## Project Context

**Project:** {project name} — {one-line description}

**Backend:** {framework} / {language} / {database + ORM}
**Frontend:** {framework} / {styling} / {state management} *(or: backend-only)*
**Auth:** {auth approach}
**Validation:** {validation library}
**Logging:** {logger} → {logs backend}
**Testing:** {backend test framework} / {frontend test framework}

**Infra:** {iac tool} on {cloud}; state in {state backend}; secrets in {secrets manager}; CI/CD via {pipeline}
**Local dev:** {local dev setup}

**Compliance:** {framework or "none"}
**Data classes:** {scheme}
**Encryption:** at rest {approach} / in transit {TLS}

**Repo structure:** {top-level directories, one line}
**Module structure:** {brief description of how code is organised, 1–2 sentences}

**Key rules:**
- {thin controllers / service-layer pattern}
- {external API client pattern and location}
- {config service rule}
- {IaC: declarative, remote state, no `*:*` IAM, CI-only apply}
- {observability: structured logs, correlation ID, no PII in logs}
- {any other hard rules}

**External integrations:** {list or "none"}
**Key entities:** {list with data classes, or "TBD"}
**Known gotchas:** {list or "none"}

---

After Output

Step 1 — Detect local skills

Before telling the user what to do, check whether skills are local to the project:

• Look for .opencode/skills/ in the project root
• If it exists, list which SKILL.md files are present

Step 2 — Insert Project Context into local skills

If .opencode/skills/ exists:

For each SKILL.md found, replace the ## Project Context placeholder block — the block that begins with the > Fill in before use: blockquote and ends at the --- rule that follows it — with the generated Project Context block from Output 2. Do this for every skill file present.

Confirm to the user which files were updated, e.g.:

"Updated Project Context in: architect, developer, reviewer, infosec, create-feature"

If .opencode/skills/ does not exist, tell the user:

"Skills are not local to this project. The Project Context block can be pasted into the ## Project Context section of any skill file, or provided at the start of a conversation: 'Here is my project context: [paste block]'.

To version skills inside this project and have the context inserted automatically, copy the skills into .opencode/skills/ — see the skills README for instructions."

Step 3 — MCP Setup

Invoke the mcp-setup skill to let the user choose which MCP servers to add to this project. The mcp-setup skill will handle reading/writing opencode.json and explaining each option.

After mcp-setup completes, continue to Step 4.

---

Step 4 — Finish

Tell the user:

"Your CLAUDE.md is ready to commit to the root of your repository.

Suggested next steps:

1. Commit CLAUDE.md, opencode.json, and any updated skill files to version control
2. Scaffold infra/modules/, infra/envs/{dev,staging,prod}/, docs/proposals/, and docs/decisions/ directories
3. If you have existing architectural decisions, run: use the decision-log skill to seed the initial ADRs
4. For your first feature, run: use the create-feature skill"