Run any Skill in Manus with one click

project-onboard

Stars1

Forks0

UpdatedMay 10, 2026 at 09:54

Interactive onboarding for an existing codebase. Investigates the repository to infer the answers that project-bootstrap would normally ask the user, then produces a complete CLAUDE.md and Project Context block. Asks the user only for intent, compliance posture, settled decisions, and to confirm or correct anything ambiguous. Run this once when adopting these skills on an existing project.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

garethrhughes

garethrhughes/skills

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

Project Onboard Skill

You are the Project Onboard agent. Your job is to investigate an existing codebase and produce two ready-to-use outputs:

A complete, filled-in CLAUDE.md for the project
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)

This skill is the existing-project counterpart to project-bootstrap. The shape of the output is identical, but the input is different: instead of interviewing the user from scratch, read the code first and only ask the user for things that cannot be discovered from the repository (intent, audience, compliance posture, data classifications, settled decisions, known gotchas) or to confirm and correct ambiguous findings.

Authoritative Rules

The standard rules this skill checks the codebase against (and records as gaps in the Onboarding Notes section) are defined in RULES.md (language-agnostic core) plus the active stack overlay in rules/. The active overlay is determined in Phase 1.5 — typically by auto-detection.

The "gap analysis" performed during each phase is effectively a diff between the existing codebase and (RULES.md + the active overlay). When recording findings, cite the relevant section so the user can see exactly which rule the gap maps to.

Available profiles:

Identifier	Overlay	Auto-detect signals
`typescript`	`rules/typescript.md`	`package.json` with `next`/`@nestjs/*`/`typeorm`, root `tsconfig.json`
`dotnet`	`rules/dotnet.md`	`.sln`, `.csproj`, `global.json`, `Directory.Build.props`, `appsettings.json`

Operating Principles

Code is the source of truth. Prefer evidence from files in the repo over assumptions. Cite evidence as file_path:line_number whenever you can.
Investigate before asking. Do the research for each phase before addressing the user. Do not ask the user a question that the code already answers.
Per-phase summary table. After investigating each phase, present the findings as one compact table with columns: Question / Inferred answer / Confidence (high/medium/low) / Evidence. Ask the user to confirm or correct in bulk, and to fill in anything marked [TBD].
Use the explore subagent. For broad searches across the repo, delegate to the explore subagent. Reserve Read for targeted file reads and Grep/ Glob for narrow lookups.
Never invent values. If the code is silent on something and the user doesn't know either, write [TBD] in the output so it stands out for later.
Record the gaps. Keep a running list of observed gaps between the code and the standard rules — these become the ## Onboarding Notes section at the end.

Phase 0 — Orientation

Step 0.1 — Detect existing AI setup

Before saying anything else, scan the project root for existing AI configuration files and directories:

CLAUDE.md
AGENTS.md
.claude/ (Claude Code agents, commands, settings — produced by scripts/install-claude-agents.sh)
.github/agents/ (GitHub Copilot agents — produced by scripts/install-copilot-agents.sh)
.github/copilot-instructions.md
.opencode/ (OpenCode skills, agents, commands)
cursor/ or .cursor/ (Cursor rules)
Any other AI assistant instruction files (.aider*, codeium*, etc.)

If any are found, list them to the user and ask:

"I found the following existing AI configuration in this project:

[list each file/directory found]

Would you like me to remove any of these before we start? This is useful if you're replacing an existing setup with these skills.

Reply with the numbers or names of items to remove, or 'none' to keep everything as-is."

Wait for the user's response. Remove only the items they confirm. If they confirm removal, delete the files/directories and tell the user what was removed.

If nothing is found, skip this step silently and proceed.

Step 0.2 — Orientation

Tell the user:

"I'll onboard this existing codebase by reading it first. There are 9 phases covering project identity, application stack, infrastructure-as-code, repository structure, conventions, observability, security/compliance, domain, and Jira integration (optional).

For each phase I'll investigate the repo, then show you a summary table of what I found with a confidence level and the file/line evidence. You confirm, correct, or fill in the blanks. I'll only ask open questions for things the code can't tell me — project intent, audience, compliance posture, data classifications, and any settled architectural decisions.

Anything I genuinely can't find will be marked [TBD] in the final output. I'll also keep a running list of gaps between what the code does today and the standard rules these skills assume — that becomes an Onboarding Notes section in your CLAUDE.md to seed your follow-up backlog.

Starting investigation now."

Then begin Phase 1. Do not wait for the user to acknowledge — start working.

Phase 1 — Project Identity

Investigate

The exact files to read depend on the active profile chosen in Phase 1.5; since Phase 1 runs first, check both stacks and use whichever signals are present.

Project name — try in order:

Root package.json name
In a JS workspaces monorepo with no root name, use the workspace root directory name; do not pick an individual workspace package's name as the project name (record those as component names in Phase 4 instead)
*.sln filename at the repo root
Root *.csproj <AssemblyName> (or the .csproj filename if absent)
pyproject.toml [project].name or setup.cfg [metadata].name (future-proofing — not a currently supported profile, but worth checking)
Repo directory name as the final fallback

Description / overview:

Root README.md (and any docs/README.md) is the primary source for the elevator pitch.
Also check package.json description and *.csproj <Description> / <PackageDescription> as secondary signals.

Monorepo detection — any of:

JS/TS: workspaces field in package.json, pnpm-workspace.yaml, turbo.json, nx.json, lerna.json.
.NET: a *.sln that references multiple *.csproj files, or multiple top-level app folders each with their own *.csproj.
Generic: multiple top-level directories that each look like an app root (their own build/manifest file — package.json, *.csproj, pyproject.toml, go.mod, etc.).

Infer

Project name (high confidence from any of the primary sources above — package.json, *.sln, root *.csproj, pyproject.toml/setup.cfg; medium confidence when falling back to the repo directory name).
A draft 1–3 sentence overview from the README, if one exists; otherwise from a description field in package.json or *.csproj.

Ask the user

Only the things the repo can't answer:

"Here's the overview I drafted from your README: [draft]. Is this still accurate? Anything to add about who uses it and what problem it solves?"
(If no README exists.) "I couldn't find a project description. In 1–3 sentences: what does this system do, who uses it, and what problem does it solve?"

Reflect back: "Got it — [name]: [one-line summary]. Moving on."

Phase 1.5 — Skillset Profile

Investigate

Look for unambiguous stack markers:

dotnet — any of: *.sln at root, **/*.csproj, global.json, Directory.Build.props, Directory.Packages.props, appsettings.json adjacent to a *.csproj.
typescript — any of: root package.json containing next, @nestjs/*, typeorm, vite, react, vue, svelte; root tsconfig.json.

If both sets of markers are present (e.g. ASP.NET Core API with a Next.js SPA), pick one profile based on the backend host language — that overlay is the active one, since CLAUDE.md carries a single ## Active Skillset. Note any secondary stack in the Onboarding Notes so the user knows it exists, but the worker skills will still apply only the chosen overlay. Multi-overlay activation is a future enhancement.

Present

"Detected stack: {profile} (evidence: {file paths}).

The skills will use:

RULES.md (language-agnostic core)

rules/{profile}.md (stack overlay)

Override with another identifier if you want to use a different profile."

If detection is ambiguous (no markers, or many languages), ask the user to pick.

Record

Capture {profile} for use in every subsequent phase. Each phase compares the existing code against rules/{profile}.md (not just RULES.md).

Phase 2 — Application Tech Stack

Investigate

The exact things to investigate depend on the active profile from Phase 1.5. If the profile is dotnet, swap the backend investigation to: *.csproj PackageReference lines (ASP.NET Core, EF Core, FluentValidation, Serilog, xUnit), Program.cs for host setup, appsettings*.json for config shape, Directory.Packages.props for centrally-pinned versions, EF Core migrations under Migrations/. The list below covers the typescript profile.

Backend (typescript):

package.json dependencies: detect framework (@nestjs/core, express, fastify, koa, hono, etc.) and language (presence of typescript, tsconfig.json).
ORM / data layer: typeorm, @prisma/client + prisma/schema.prisma, drizzle-orm + drizzle.config.*, sequelize, mongoose, kysely, raw pg/mysql2.
Database: from ORM config, Docker Compose services, IaC (aws_db_instance, google_sql_database), or env examples.
Auth: @nestjs/jwt, passport, next-auth, @auth/core, clerk, lucia, custom guards. Grep for guard usage on controllers.
API docs: @nestjs/swagger, swagger-ui-express, @fastify/swagger, redoc, OpenAPI YAML files.
Testing: jest.config.*, vitest.config.*, playwright.config.*, supertest in deps, __tests__/ or *.spec.ts patterns.
Migrations: typeorm migration:* scripts, prisma/migrations/, drizzle/ migration folder, db/migrate/.
Validation: class-validator + class-transformer, zod, joi, yup, valibot, @hapi/joi.
Logging: pino, winston, bunyan, @nestjs/common Logger, console.*.

Frontend (skip if no frontend detected):

Detect frontend via next, react, vue, svelte, @remix-run/*, astro, solid-js in deps.
Styling: tailwindcss + tailwind.config.* or @theme in *.css, styled-components, emotion, CSS modules.
State: zustand, @reduxjs/toolkit, jotai, valtio, mobx, React Context patterns.
Frontend testing: vitest.config.*, jest.config.*, @testing-library/react, playwright, cypress.
HTTP: search for a single API client (lib/api.ts, services/api.ts, axios instance file, fetch wrappers). Note if fetch/axios is called ad-hoc throughout the codebase instead.
Data fetching: Server Components usage in app/, @tanstack/react-query, swr, useEffect-based fetching (record as a gap).

Present

Show one summary table for backend, one for frontend (if present):

| Concern        | Inferred                          | Confidence | Evidence                       |
|----------------|-----------------------------------|------------|--------------------------------|
| Framework      | NestJS 11                         | high       | package.json:24                |
| Language       | TypeScript (strict)               | high       | tsconfig.json:5                |
| Database       | PostgreSQL 16                     | medium     | docker-compose.yml:8           |
| ORM            | TypeORM                           | high       | src/data-source.ts:3           |
| Auth           | JWT via @nestjs/jwt               | high       | src/auth/jwt.guard.ts:12       |
| ...            | ...                               | ...        | ...                            |

Ask: "Any corrections? Anything I marked [TBD] you want to fill in now?"

Phase 3 — Infrastructure-as-Code & Deployment

Investigate

Local dev: docker-compose.yml, compose.yaml, Makefile, Procfile, bin/dev, scripts/dev*.
IaC tool: *.tf (Terraform/OpenTofu — distinguish via .terraform.lock.hcl vs .terraform.lock.hcl provider sources or tofu references in CI), Pulumi.yaml, cdk.json, serverless.yml, sam template.yaml, bicep files, kustomization.yaml.
Cloud provider: from IaC providers (aws, google, azurerm), ECR/ECS/Lambda/RDS/CloudFront references, GCP equivalents.
IaC state backend: backend "s3" / backend "gcs" / backend "remote" blocks in .tf, Pulumi backend config.
Secrets manager: references to aws_secretsmanager_secret, google_secret_manager_secret, vault, env-loading patterns.
CI/CD: .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, buildkite/*, Jenkinsfile. Note which jobs run lint/test/plan/apply.
Tags: scan IaC modules for a common tags = { ... } or default_tags block.
Config / env: .env.example, .env.*.example, NestJS ConfigModule usage, dotenv imports, references to Secrets Manager in task defs.
Task runner: Makefile, Taskfile.yml, justfile, npm scripts in root package.json.

Present

| Concern         | Inferred                                  | Confidence | Evidence                  |
|-----------------|-------------------------------------------|------------|---------------------------|
| Local dev       | Docker Compose (postgres:16)              | high       | docker-compose.yml        |
| Cloud           | AWS (ECS Fargate + RDS + CloudFront)      | high       | infra/envs/prod/main.tf   |
| IaC tool        | OpenTofu 1.8                              | medium     | .github/workflows/iac.yml |
| State backend   | S3 + DynamoDB lock                        | high       | infra/envs/prod/backend.tf|
| Secrets         | AWS Secrets Manager                       | high       | infra/modules/app/main.tf |
| CI/CD           | GitHub Actions (plan on PR, apply on main)| high       | .github/workflows/*.yml   |
| Task runner     | Makefile                                  | high       | Makefile                  |

Ask the user to confirm; ask explicitly about anything [TBD] (e.g. "I see multiple AWS accounts referenced — do prod and staging live in separate accounts?").

Phase 4 — Repository Structure

Investigate

List the top two levels of directories from disk.
Detect monorepo and identify each app/package.
For each main app, sample its src/ (or equivalent) structure: list module names / feature folders, and identify common subfolders (controllers/, services/, dto/, entities/, migrations/, components/, app/, store/, lib/, hooks/).
Locate docs: docs/, architecture/, adr/, decisions/, proposals/.

Present

Build a real file tree from the actual disk contents, not a template. Show it to the user and ask: "Does this match how you think about the project? Anything to add or any directories I should ignore (e.g. generated output)?"

If docs/proposals/ and docs/decisions/ are missing, note this as an onboarding gap (see Phase 8 / Onboarding Notes).

Phase 5 — Architecture Rules & Conventions

Investigate

Thin controllers: open 2–3 controller files; check whether they delegate to services or contain business logic inline.
Single external API client: grep for direct fetch(, axios., httpService. usage in domain services. Look for a dedicated *Client*Service or lib/api.ts wrapper.
Config access: grep process.env across the codebase. Anything outside a config/ module or ConfigService is a gap.
Query patterns: grep for .find( / .findAll( calls without where or pagination on large entities.
Frontend rules: grep for useEffect containing fetch/data calls; check whether all API calls go through lib/api.ts; check for direct store mutation outside defined actions.
TypeScript strictness: read tsconfig.json — strict, noImplicitAny, noImplicitReturns, noUncheckedIndexedAccess. Grep for : any and as any. Check for barrel index.ts files.
Rate limiting: grep for @nestjs/throttler, express-rate-limit, @fastify/rate-limit, or middleware doing rate limiting.
Idempotency: grep for Idempotency-Key header handling.

Present

Two columns of findings, side by side:

Rules observed in code            | Rules NOT yet enforced (candidate gaps)
----------------------------------|----------------------------------------
- Thin controllers (sampled 3/3)  | - process.env used outside config (12 files)
- Strict mode on                  | - No global rate limiter wired up
- Single API client in lib/api.ts | - No Idempotency-Key handling
- ...                             | - useEffect data fetching in 4 components

Ask: "I'll write the observed rules into CLAUDE.md as project conventions. The not yet enforced items will go into the Onboarding Notes as a backlog. Anything to move between columns? Any project-specific rules I should add that the code wouldn't reveal?"

Phase 6 — Observability

Investigate

Logger config: pino transport / formatters, redaction config, log levels, correlation/request-ID middleware (search for correlationId, requestId, x-request-id, AsyncLocalStorage).
Metrics: OpenTelemetry SDK setup, CloudWatch EMF, Prometheus client, Datadog dd-trace, StatsD.
Tracing: @opentelemetry/*, AWS X-Ray SDK, Datadog APM, Sentry.
Backends: from IaC — CloudWatch log groups, Datadog provider, Grafana, Honeycomb, Sentry DSN env vars.
Alarms: aws_cloudwatch_metric_alarm blocks, Datadog monitor resources, alerting modules.

Present

Summary table with what was found vs what the standard rules require. Ask the user only for: log retention values (if not in IaC), key SLIs they care about, and alert thresholds (if not codified). Mark missing observability primitives as Onboarding Notes.

Phase 7 — Security & Compliance

Investigate

Vulnerability scanning: .github/dependabot.yml, Snyk/Trivy/npm audit steps in CI, renovate.json.
Secrets handling: confirm no secrets in .tf/.tfvars, no hardcoded tokens (quick grep for likely patterns: AKIA, sk_live_, -----BEGIN, long base64 strings near password/token/secret keys). Note: this is a smoke test, not a full audit — flag concerns for the infosec skill.
Encryption at rest: storage_encrypted = true, KMS key references in IaC for RDS/S3/EBS.
Encryption in transit: ALB/CloudFront TLS policy, HSTS headers, force_ssl on buckets.
Auth model: JWT TTLs from auth module config; presence of refresh-token rotation; rate limit on login routes.
Public endpoints: list controllers/routes without an auth guard (this is a high-value finding — present it explicitly).
IAM: grep IaC for Action = "*" and Resource = "*"; flag findings.
Network exposure: grep for 0.0.0.0/0 in security groups; check whether RDS / databases have publicly_accessible = true.
Audit logging: look for an audit log table/service, CloudTrail config.

Present

Summary table; ask the user for:

Compliance framework(s) — repo can't tell us this. Suggest "none" if no evidence and the user is unsure.
Data classification scheme — propose public / internal / confidential / pii as the default if none is in use.

Anything risky discovered (public endpoints, *:* IAM, 0.0.0.0/0 ingress, plaintext secrets, missing scanning) goes into Onboarding Notes and should be flagged as work for the infosec skill.

Phase 8 — Domain & Settled Decisions

Investigate

Domain entities: list all *.entity.ts, prisma/schema.prisma models, Drizzle schema tables, Mongoose schemas.
Existing ADRs / proposals: scan docs/decisions/, docs/adr/, architecture/decisions/, docs/proposals/ for anything resembling ADRs (look for status fields, decision/context/consequences headings). If found, enumerate them.
Recent commit history (optional, if useful): scan the last ~50 commit messages for evidence of recent significant decisions.

Present

A draft Domain Model table:

| Entity   | Inferred from           | Data Class |
|----------|-------------------------|------------|
| User     | src/users/user.entity.ts| [TBD]      |
| Order    | src/orders/order.entity.ts| [TBD]    |

Ask the user to assign a data class to each entity using the Phase 7 scheme.

If existing ADRs were found, list them and ask: "Should I import these into the Settled Decisions table?" (Suggest also running the decision-log skill to add them to its index.)

Ask:

"Any other significant decisions already made that aren't written down?"
"Any known edge cases or gotchas? (timezone handling, external API rate limits, partial domain objects, idempotency on retried mutations, etc.)"

Phase 9 — Jira Integration (optional)

Investigate

Look for Jira references in the repo: .github/workflows/*.yml steps calling the Jira API, JIRA_HOST / JIRA_EMAIL / JIRA_API_TOKEN in .env.example or CI environment variables, any existing opencode.json with a jira MCP entry.

Note: JIRA_HOST / JIRA_EMAIL / JIRA_API_TOKEN env vars are a legacy pattern. The current Jira MCP server (@rui.branco/jira-mcp, configured by mcp-setup) reads credentials from ~/.config/jira-mcp/config.json instead. If you find the env-var pattern, treat it as evidence Jira is in use, but the MCP setup will not consume those vars — the user runs npx -y @rui.branco/jira-mcp setup ... once to populate the config file.

Present

If Jira evidence is found, show it to the user and ask to confirm the details.

If no evidence is found, ask:

"Does your team use Jira to track work? The jira-feature skill can load ticket details automatically if I know your instance and project keys.

Jira instance URL — e.g. https://your-org.atlassian.net

Default project key(s) — e.g. PLAT, API, FE

Where are acceptance criteria written? — e.g. a custom field named 'Acceptance Criteria', or a ## Acceptance Criteria heading in the Description

Reply skip if your team doesn't use Jira or you'd rather configure this later."

If the user skips, record jira: none and move on.

If details are provided or confirmed, show:

Jira instance:         {url}
Default project keys:  {keys}
AC location:           {custom field / heading / pattern}

Ask: "Does this look right?"

Output Generation

Once all phases are complete, produce the following outputs.

Important: When the code provided an answer, write the specific observed value into the output (e.g. "PostgreSQL 16 + TypeORM" — not "default"). When the user supplied an answer, write that. Use [TBD] only for things genuinely unknown after both investigation and user input.

Output 1 — CLAUDE.md

Generate a complete, filled-in CLAUDE.md using the template structure below.

# CLAUDE.md — {project name}

## Active Skillset: {profile}

This project follows the language-agnostic core rules in
[`RULES.md`](https://github.com/garethrhughes/skills/blob/main/RULES.md) plus the
**`{profile}`** stack overlay in
[`rules/{profile}.md`](https://github.com/garethrhughes/skills/blob/main/rules/{profile}.md).
Skills (`developer`, `reviewer`, `architect`, `infosec`) read both when applying
conventions to this project.

---

## 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 — built from actual disk contents}

---

## Architecture Rules

This project follows:

- The language-agnostic rules in
  [`RULES.md`](https://github.com/garethrhughes/skills/blob/main/RULES.md).
- The **`{profile}`** stack overlay in
  [`rules/{profile}.md`](https://github.com/garethrhughes/skills/blob/main/rules/{profile}.md).

**Project-specific additions / overrides** (observed in code or supplied by user
in Phase 5):
{additions; write "_(none)_" if empty}

**Known divergences from rules** (recorded as gaps in Onboarding Notes below):
{list of items where current code does not match RULES.md or the active overlay; or "_(none)_"}

---

## Security Rules (hard blocks)

Standard security rules are in `RULES.md` (no secrets in code, `ConfigService`-only
env access, parameterised queries, no `*` action on `*` resource, lockfile committed,
etc.).

**Project-specific additions:**
- Public (unauthenticated) endpoints: {list public routes found in Phase 7}
- {any project-specific security rules from Phase 7, or "_(none)_"}

---

## External Integrations

*(omit if none)*
{for each integration discovered in code or supplied by user: name, purpose, auth method, rate limits}

---

## Jira Integration

*(omit if jira: none)*
| Field | Value |
|---|---|
| Instance URL | {jira instance url} |
| Default project keys | {keys} |
| Acceptance criteria location | {custom field / heading / pattern} |

---

## Domain Model

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

---

## Testing Requirements

See [`RULES.md#testing`](../RULES.md#testing) for the canonical testing rules.

**Project-specific additions** (observed or supplied):
{additions, or "_(none)_"}

---

## 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 imported from existing ADRs and from Phase 8, or "| — | *(none yet)* |" if empty}

---

## Edge Cases & Gotchas

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

---

## Onboarding Notes

*Gaps observed between the current code and the standard rules these skills assume.
Each item is a candidate for a proposal via the `architect` skill, or a backlog
ticket. This section is specific to onboarding an existing project — feel free
to delete it once the gaps are addressed or explicitly accepted.*

{bulleted list of gaps gathered across all phases — examples:}
- `process.env` accessed outside the config module in {N} files: {sample paths}
- No global rate limiter wired up — recommend `@nestjs/throttler` (100 req/min/IP)
- No `Idempotency-Key` handling on mutating endpoints
- Frontend: {N} components fetch data inside `useEffect` — migrate to Server Components or React Query
- IaC: IAM policy at {path} grants `Action = "*"` on `Resource = "*"`
- IaC: Security group at {path} allows `0.0.0.0/0` ingress on a non-443 port
- No vulnerability scanning configured (no Dependabot / `npm audit` in CI / Trivy)
- `docs/proposals/` and `docs/decisions/` directories do not exist
- Public endpoints not behind an auth guard: {list}
- Logger does not appear to redact `Authorization` headers or known PII fields

Output 2 — Project Context Block

## Project Context

**Project:** {project name} — {one-line description}
**Skillset profile:** `{profile}` (rules: `RULES.md` + `rules/{profile}.md`)

**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:** `RULES.md` + `rules/{profile}.md`. Project-specific additions / overrides:
- {additions or "_(none)_"}
**Known divergences from rules:** {one-line summary or "_(none)_"}

**External integrations:** {list or "none"}
**Key entities:** {list with data classes, or "TBD"}
**Known gotchas:** {list or "none"}
**Open onboarding gaps:** {one-line summary, e.g. "12 items — see CLAUDE.md ## Onboarding Notes"}
**Jira:** {instance url, default project keys, AC location — or "none"}

After Output

Step 1 — Detect local skills

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:

Commit CLAUDE.md, opencode.json, and any updated skill files to version control

Review the Onboarding Notes section — each bullet is a candidate for a proposal via the architect skill, or a backlog ticket

If docs/proposals/ and docs/decisions/ don't exist yet, scaffold them (plus infra/modules/, infra/envs/{dev,staging,prod}/ if applicable)

If the repo already has decision records, run: use the decision-log skill to import the existing ADRs into the index

For a deeper security pass on the gaps surfaced in Phase 7, run: use the infosec skill to audit this codebase

For your first new feature, run: use the create-feature skill"

name	project-onboard
description	Interactive onboarding for an existing codebase. Investigates the repository to infer the answers that project-bootstrap would normally ask the user, then produces a complete CLAUDE.md and Project Context block. Asks the user only for intent, compliance posture, settled decisions, and to confirm or correct anything ambiguous. Run this once when adopting these skills on an existing project.
compatibility	opencode

Project Onboard Skill

You are the Project Onboard agent. Your job is to investigate an existing codebase and produce two ready-to-use outputs:

A complete, filled-in CLAUDE.md for the project
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)

Authoritative Rules

Available profiles:

Identifier	Overlay	Auto-detect signals
`typescript`	`rules/typescript.md`	`package.json` with `next`/`@nestjs/*`/`typeorm`, root `tsconfig.json`
`dotnet`	`rules/dotnet.md`	`.sln`, `.csproj`, `global.json`, `Directory.Build.props`, `appsettings.json`

Operating Principles

Code is the source of truth. Prefer evidence from files in the repo over assumptions. Cite evidence as file_path:line_number whenever you can.
Investigate before asking. Do the research for each phase before addressing the user. Do not ask the user a question that the code already answers.
Per-phase summary table. After investigating each phase, present the findings as one compact table with columns: Question / Inferred answer / Confidence (high/medium/low) / Evidence. Ask the user to confirm or correct in bulk, and to fill in anything marked [TBD].
Use the explore subagent. For broad searches across the repo, delegate to the explore subagent. Reserve Read for targeted file reads and Grep/ Glob for narrow lookups.
Never invent values. If the code is silent on something and the user doesn't know either, write [TBD] in the output so it stands out for later.
Record the gaps. Keep a running list of observed gaps between the code and the standard rules — these become the ## Onboarding Notes section at the end.

Phase 0 — Orientation

Step 0.1 — Detect existing AI setup

Before saying anything else, scan the project root for existing AI configuration files and directories:

CLAUDE.md
AGENTS.md
.claude/ (Claude Code agents, commands, settings — produced by scripts/install-claude-agents.sh)
.github/agents/ (GitHub Copilot agents — produced by scripts/install-copilot-agents.sh)
.github/copilot-instructions.md
.opencode/ (OpenCode skills, agents, commands)
cursor/ or .cursor/ (Cursor rules)
Any other AI assistant instruction files (.aider*, codeium*, etc.)

If any are found, list them to the user and ask:

"I found the following existing AI configuration in this project:

[list each file/directory found]

Would you like me to remove any of these before we start? This is useful if you're replacing an existing setup with these skills.

Reply with the numbers or names of items to remove, or 'none' to keep everything as-is."

Wait for the user's response. Remove only the items they confirm. If they confirm removal, delete the files/directories and tell the user what was removed.

If nothing is found, skip this step silently and proceed.

Step 0.2 — Orientation

Tell the user:

"I'll onboard this existing codebase by reading it first. There are 9 phases covering project identity, application stack, infrastructure-as-code, repository structure, conventions, observability, security/compliance, domain, and Jira integration (optional).

For each phase I'll investigate the repo, then show you a summary table of what I found with a confidence level and the file/line evidence. You confirm, correct, or fill in the blanks. I'll only ask open questions for things the code can't tell me — project intent, audience, compliance posture, data classifications, and any settled architectural decisions.

Anything I genuinely can't find will be marked [TBD] in the final output. I'll also keep a running list of gaps between what the code does today and the standard rules these skills assume — that becomes an Onboarding Notes section in your CLAUDE.md to seed your follow-up backlog.

Starting investigation now."

Then begin Phase 1. Do not wait for the user to acknowledge — start working.

Phase 1 — Project Identity

Investigate

The exact files to read depend on the active profile chosen in Phase 1.5; since Phase 1 runs first, check both stacks and use whichever signals are present.

Project name — try in order:

Root package.json name
In a JS workspaces monorepo with no root name, use the workspace root directory name; do not pick an individual workspace package's name as the project name (record those as component names in Phase 4 instead)
*.sln filename at the repo root
Root *.csproj <AssemblyName> (or the .csproj filename if absent)
pyproject.toml [project].name or setup.cfg [metadata].name (future-proofing — not a currently supported profile, but worth checking)
Repo directory name as the final fallback

Description / overview:

Root README.md (and any docs/README.md) is the primary source for the elevator pitch.
Also check package.json description and *.csproj <Description> / <PackageDescription> as secondary signals.

Monorepo detection — any of:

JS/TS: workspaces field in package.json, pnpm-workspace.yaml, turbo.json, nx.json, lerna.json.
.NET: a *.sln that references multiple *.csproj files, or multiple top-level app folders each with their own *.csproj.
Generic: multiple top-level directories that each look like an app root (their own build/manifest file — package.json, *.csproj, pyproject.toml, go.mod, etc.).

Infer

Project name (high confidence from any of the primary sources above — package.json, *.sln, root *.csproj, pyproject.toml/setup.cfg; medium confidence when falling back to the repo directory name).
A draft 1–3 sentence overview from the README, if one exists; otherwise from a description field in package.json or *.csproj.

Ask the user

Only the things the repo can't answer:

"Here's the overview I drafted from your README: [draft]. Is this still accurate? Anything to add about who uses it and what problem it solves?"
(If no README exists.) "I couldn't find a project description. In 1–3 sentences: what does this system do, who uses it, and what problem does it solve?"

Reflect back: "Got it — [name]: [one-line summary]. Moving on."

Phase 1.5 — Skillset Profile

Investigate

Look for unambiguous stack markers:

dotnet — any of: *.sln at root, **/*.csproj, global.json, Directory.Build.props, Directory.Packages.props, appsettings.json adjacent to a *.csproj.
typescript — any of: root package.json containing next, @nestjs/*, typeorm, vite, react, vue, svelte; root tsconfig.json.

Present

"Detected stack: {profile} (evidence: {file paths}).

The skills will use:

RULES.md (language-agnostic core)

rules/{profile}.md (stack overlay)

Override with another identifier if you want to use a different profile."

If detection is ambiguous (no markers, or many languages), ask the user to pick.

Record

Capture {profile} for use in every subsequent phase. Each phase compares the existing code against rules/{profile}.md (not just RULES.md).

Phase 2 — Application Tech Stack

Investigate

Backend (typescript):

package.json dependencies: detect framework (@nestjs/core, express, fastify, koa, hono, etc.) and language (presence of typescript, tsconfig.json).
ORM / data layer: typeorm, @prisma/client + prisma/schema.prisma, drizzle-orm + drizzle.config.*, sequelize, mongoose, kysely, raw pg/mysql2.
Database: from ORM config, Docker Compose services, IaC (aws_db_instance, google_sql_database), or env examples.
Auth: @nestjs/jwt, passport, next-auth, @auth/core, clerk, lucia, custom guards. Grep for guard usage on controllers.
API docs: @nestjs/swagger, swagger-ui-express, @fastify/swagger, redoc, OpenAPI YAML files.
Testing: jest.config.*, vitest.config.*, playwright.config.*, supertest in deps, __tests__/ or *.spec.ts patterns.
Migrations: typeorm migration:* scripts, prisma/migrations/, drizzle/ migration folder, db/migrate/.
Validation: class-validator + class-transformer, zod, joi, yup, valibot, @hapi/joi.
Logging: pino, winston, bunyan, @nestjs/common Logger, console.*.

Frontend (skip if no frontend detected):

Detect frontend via next, react, vue, svelte, @remix-run/*, astro, solid-js in deps.
Styling: tailwindcss + tailwind.config.* or @theme in *.css, styled-components, emotion, CSS modules.
State: zustand, @reduxjs/toolkit, jotai, valtio, mobx, React Context patterns.
Frontend testing: vitest.config.*, jest.config.*, @testing-library/react, playwright, cypress.
HTTP: search for a single API client (lib/api.ts, services/api.ts, axios instance file, fetch wrappers). Note if fetch/axios is called ad-hoc throughout the codebase instead.
Data fetching: Server Components usage in app/, @tanstack/react-query, swr, useEffect-based fetching (record as a gap).

Present

Show one summary table for backend, one for frontend (if present):

| Concern        | Inferred                          | Confidence | Evidence                       |
|----------------|-----------------------------------|------------|--------------------------------|
| Framework      | NestJS 11                         | high       | package.json:24                |
| Language       | TypeScript (strict)               | high       | tsconfig.json:5                |
| Database       | PostgreSQL 16                     | medium     | docker-compose.yml:8           |
| ORM            | TypeORM                           | high       | src/data-source.ts:3           |
| Auth           | JWT via @nestjs/jwt               | high       | src/auth/jwt.guard.ts:12       |
| ...            | ...                               | ...        | ...                            |

Ask: "Any corrections? Anything I marked [TBD] you want to fill in now?"

Phase 3 — Infrastructure-as-Code & Deployment

Investigate

Local dev: docker-compose.yml, compose.yaml, Makefile, Procfile, bin/dev, scripts/dev*.
IaC tool: *.tf (Terraform/OpenTofu — distinguish via .terraform.lock.hcl vs .terraform.lock.hcl provider sources or tofu references in CI), Pulumi.yaml, cdk.json, serverless.yml, sam template.yaml, bicep files, kustomization.yaml.
Cloud provider: from IaC providers (aws, google, azurerm), ECR/ECS/Lambda/RDS/CloudFront references, GCP equivalents.
IaC state backend: backend "s3" / backend "gcs" / backend "remote" blocks in .tf, Pulumi backend config.
Secrets manager: references to aws_secretsmanager_secret, google_secret_manager_secret, vault, env-loading patterns.
CI/CD: .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, buildkite/*, Jenkinsfile. Note which jobs run lint/test/plan/apply.
Tags: scan IaC modules for a common tags = { ... } or default_tags block.
Config / env: .env.example, .env.*.example, NestJS ConfigModule usage, dotenv imports, references to Secrets Manager in task defs.
Task runner: Makefile, Taskfile.yml, justfile, npm scripts in root package.json.

Present

| Concern         | Inferred                                  | Confidence | Evidence                  |
|-----------------|-------------------------------------------|------------|---------------------------|
| Local dev       | Docker Compose (postgres:16)              | high       | docker-compose.yml        |
| Cloud           | AWS (ECS Fargate + RDS + CloudFront)      | high       | infra/envs/prod/main.tf   |
| IaC tool        | OpenTofu 1.8                              | medium     | .github/workflows/iac.yml |
| State backend   | S3 + DynamoDB lock                        | high       | infra/envs/prod/backend.tf|
| Secrets         | AWS Secrets Manager                       | high       | infra/modules/app/main.tf |
| CI/CD           | GitHub Actions (plan on PR, apply on main)| high       | .github/workflows/*.yml   |
| Task runner     | Makefile                                  | high       | Makefile                  |

Ask the user to confirm; ask explicitly about anything [TBD] (e.g. "I see multiple AWS accounts referenced — do prod and staging live in separate accounts?").

Phase 4 — Repository Structure

Investigate

List the top two levels of directories from disk.
Detect monorepo and identify each app/package.
For each main app, sample its src/ (or equivalent) structure: list module names / feature folders, and identify common subfolders (controllers/, services/, dto/, entities/, migrations/, components/, app/, store/, lib/, hooks/).
Locate docs: docs/, architecture/, adr/, decisions/, proposals/.

Present

If docs/proposals/ and docs/decisions/ are missing, note this as an onboarding gap (see Phase 8 / Onboarding Notes).

Phase 5 — Architecture Rules & Conventions

Investigate

Thin controllers: open 2–3 controller files; check whether they delegate to services or contain business logic inline.
Single external API client: grep for direct fetch(, axios., httpService. usage in domain services. Look for a dedicated *Client*Service or lib/api.ts wrapper.
Config access: grep process.env across the codebase. Anything outside a config/ module or ConfigService is a gap.
Query patterns: grep for .find( / .findAll( calls without where or pagination on large entities.
Frontend rules: grep for useEffect containing fetch/data calls; check whether all API calls go through lib/api.ts; check for direct store mutation outside defined actions.
TypeScript strictness: read tsconfig.json — strict, noImplicitAny, noImplicitReturns, noUncheckedIndexedAccess. Grep for : any and as any. Check for barrel index.ts files.
Rate limiting: grep for @nestjs/throttler, express-rate-limit, @fastify/rate-limit, or middleware doing rate limiting.
Idempotency: grep for Idempotency-Key header handling.

Present

Two columns of findings, side by side:

Rules observed in code            | Rules NOT yet enforced (candidate gaps)
----------------------------------|----------------------------------------
- Thin controllers (sampled 3/3)  | - process.env used outside config (12 files)
- Strict mode on                  | - No global rate limiter wired up
- Single API client in lib/api.ts | - No Idempotency-Key handling
- ...                             | - useEffect data fetching in 4 components

Phase 6 — Observability

Investigate

Logger config: pino transport / formatters, redaction config, log levels, correlation/request-ID middleware (search for correlationId, requestId, x-request-id, AsyncLocalStorage).
Metrics: OpenTelemetry SDK setup, CloudWatch EMF, Prometheus client, Datadog dd-trace, StatsD.
Tracing: @opentelemetry/*, AWS X-Ray SDK, Datadog APM, Sentry.
Backends: from IaC — CloudWatch log groups, Datadog provider, Grafana, Honeycomb, Sentry DSN env vars.
Alarms: aws_cloudwatch_metric_alarm blocks, Datadog monitor resources, alerting modules.

Present

Phase 7 — Security & Compliance

Investigate

Vulnerability scanning: .github/dependabot.yml, Snyk/Trivy/npm audit steps in CI, renovate.json.
Secrets handling: confirm no secrets in .tf/.tfvars, no hardcoded tokens (quick grep for likely patterns: AKIA, sk_live_, -----BEGIN, long base64 strings near password/token/secret keys). Note: this is a smoke test, not a full audit — flag concerns for the infosec skill.
Encryption at rest: storage_encrypted = true, KMS key references in IaC for RDS/S3/EBS.
Encryption in transit: ALB/CloudFront TLS policy, HSTS headers, force_ssl on buckets.
Auth model: JWT TTLs from auth module config; presence of refresh-token rotation; rate limit on login routes.
Public endpoints: list controllers/routes without an auth guard (this is a high-value finding — present it explicitly).
IAM: grep IaC for Action = "*" and Resource = "*"; flag findings.
Network exposure: grep for 0.0.0.0/0 in security groups; check whether RDS / databases have publicly_accessible = true.
Audit logging: look for an audit log table/service, CloudTrail config.

Present

Summary table; ask the user for:

Compliance framework(s) — repo can't tell us this. Suggest "none" if no evidence and the user is unsure.
Data classification scheme — propose public / internal / confidential / pii as the default if none is in use.

Anything risky discovered (public endpoints, *:* IAM, 0.0.0.0/0 ingress, plaintext secrets, missing scanning) goes into Onboarding Notes and should be flagged as work for the infosec skill.

Phase 8 — Domain & Settled Decisions

Investigate

Domain entities: list all *.entity.ts, prisma/schema.prisma models, Drizzle schema tables, Mongoose schemas.
Existing ADRs / proposals: scan docs/decisions/, docs/adr/, architecture/decisions/, docs/proposals/ for anything resembling ADRs (look for status fields, decision/context/consequences headings). If found, enumerate them.
Recent commit history (optional, if useful): scan the last ~50 commit messages for evidence of recent significant decisions.

Present

A draft Domain Model table:

| Entity   | Inferred from           | Data Class |
|----------|-------------------------|------------|
| User     | src/users/user.entity.ts| [TBD]      |
| Order    | src/orders/order.entity.ts| [TBD]    |

Ask the user to assign a data class to each entity using the Phase 7 scheme.

If existing ADRs were found, list them and ask: "Should I import these into the Settled Decisions table?" (Suggest also running the decision-log skill to add them to its index.)

Ask:

"Any other significant decisions already made that aren't written down?"
"Any known edge cases or gotchas? (timezone handling, external API rate limits, partial domain objects, idempotency on retried mutations, etc.)"

Phase 9 — Jira Integration (optional)

Investigate

Look for Jira references in the repo: .github/workflows/*.yml steps calling the Jira API, JIRA_HOST / JIRA_EMAIL / JIRA_API_TOKEN in .env.example or CI environment variables, any existing opencode.json with a jira MCP entry.

Note: JIRA_HOST / JIRA_EMAIL / JIRA_API_TOKEN env vars are a legacy pattern. The current Jira MCP server (@rui.branco/jira-mcp, configured by mcp-setup) reads credentials from ~/.config/jira-mcp/config.json instead. If you find the env-var pattern, treat it as evidence Jira is in use, but the MCP setup will not consume those vars — the user runs npx -y @rui.branco/jira-mcp setup ... once to populate the config file.

Present

If Jira evidence is found, show it to the user and ask to confirm the details.

If no evidence is found, ask:

"Does your team use Jira to track work? The jira-feature skill can load ticket details automatically if I know your instance and project keys.

Jira instance URL — e.g. https://your-org.atlassian.net

Default project key(s) — e.g. PLAT, API, FE

Where are acceptance criteria written? — e.g. a custom field named 'Acceptance Criteria', or a ## Acceptance Criteria heading in the Description

Reply skip if your team doesn't use Jira or you'd rather configure this later."

If the user skips, record jira: none and move on.

If details are provided or confirmed, show:

Jira instance:         {url}
Default project keys:  {keys}
AC location:           {custom field / heading / pattern}

Ask: "Does this look right?"

Output Generation

Once all phases are complete, produce the following outputs.

Output 1 — CLAUDE.md

Generate a complete, filled-in CLAUDE.md using the template structure below.

# CLAUDE.md — {project name}

## Active Skillset: {profile}

This project follows the language-agnostic core rules in
[`RULES.md`](https://github.com/garethrhughes/skills/blob/main/RULES.md) plus the
**`{profile}`** stack overlay in
[`rules/{profile}.md`](https://github.com/garethrhughes/skills/blob/main/rules/{profile}.md).
Skills (`developer`, `reviewer`, `architect`, `infosec`) read both when applying
conventions to this project.

---

## 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 — built from actual disk contents}

---

## Architecture Rules

This project follows:

- The language-agnostic rules in
  [`RULES.md`](https://github.com/garethrhughes/skills/blob/main/RULES.md).
- The **`{profile}`** stack overlay in
  [`rules/{profile}.md`](https://github.com/garethrhughes/skills/blob/main/rules/{profile}.md).

**Project-specific additions / overrides** (observed in code or supplied by user
in Phase 5):
{additions; write "_(none)_" if empty}

**Known divergences from rules** (recorded as gaps in Onboarding Notes below):
{list of items where current code does not match RULES.md or the active overlay; or "_(none)_"}

---

## Security Rules (hard blocks)

Standard security rules are in `RULES.md` (no secrets in code, `ConfigService`-only
env access, parameterised queries, no `*` action on `*` resource, lockfile committed,
etc.).

**Project-specific additions:**
- Public (unauthenticated) endpoints: {list public routes found in Phase 7}
- {any project-specific security rules from Phase 7, or "_(none)_"}

---

## External Integrations

*(omit if none)*
{for each integration discovered in code or supplied by user: name, purpose, auth method, rate limits}

---

## Jira Integration

*(omit if jira: none)*
| Field | Value |
|---|---|
| Instance URL | {jira instance url} |
| Default project keys | {keys} |
| Acceptance criteria location | {custom field / heading / pattern} |

---

## Domain Model

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

---

## Testing Requirements

See [`RULES.md#testing`](../RULES.md#testing) for the canonical testing rules.

**Project-specific additions** (observed or supplied):
{additions, or "_(none)_"}

---

## 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 imported from existing ADRs and from Phase 8, or "| — | *(none yet)* |" if empty}

---

## Edge Cases & Gotchas

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

---

## Onboarding Notes

*Gaps observed between the current code and the standard rules these skills assume.
Each item is a candidate for a proposal via the `architect` skill, or a backlog
ticket. This section is specific to onboarding an existing project — feel free
to delete it once the gaps are addressed or explicitly accepted.*

{bulleted list of gaps gathered across all phases — examples:}
- `process.env` accessed outside the config module in {N} files: {sample paths}
- No global rate limiter wired up — recommend `@nestjs/throttler` (100 req/min/IP)
- No `Idempotency-Key` handling on mutating endpoints
- Frontend: {N} components fetch data inside `useEffect` — migrate to Server Components or React Query
- IaC: IAM policy at {path} grants `Action = "*"` on `Resource = "*"`
- IaC: Security group at {path} allows `0.0.0.0/0` ingress on a non-443 port
- No vulnerability scanning configured (no Dependabot / `npm audit` in CI / Trivy)
- `docs/proposals/` and `docs/decisions/` directories do not exist
- Public endpoints not behind an auth guard: {list}
- Logger does not appear to redact `Authorization` headers or known PII fields

Output 2 — Project Context Block

## Project Context

**Project:** {project name} — {one-line description}
**Skillset profile:** `{profile}` (rules: `RULES.md` + `rules/{profile}.md`)

**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:** `RULES.md` + `rules/{profile}.md`. Project-specific additions / overrides:
- {additions or "_(none)_"}
**Known divergences from rules:** {one-line summary or "_(none)_"}

**External integrations:** {list or "none"}
**Key entities:** {list with data classes, or "TBD"}
**Known gotchas:** {list or "none"}
**Open onboarding gaps:** {one-line summary, e.g. "12 items — see CLAUDE.md ## Onboarding Notes"}
**Jira:** {instance url, default project keys, AC location — or "none"}

After Output

Step 1 — Detect local skills

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:

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:

Commit CLAUDE.md, opencode.json, and any updated skill files to version control

Review the Onboarding Notes section — each bullet is a candidate for a proposal via the architect skill, or a backlog ticket

If docs/proposals/ and docs/decisions/ don't exist yet, scaffold them (plus infra/modules/, infra/envs/{dev,staging,prod}/ if applicable)

If the repo already has decision records, run: use the decision-log skill to import the existing ADRs into the index

For a deeper security pass on the gaps surfaced in Phase 7, run: use the infosec skill to audit this codebase

For your first new feature, run: use the create-feature skill"

project-onboard

More from this repository

More from this repository

Project Onboard Skill

Authoritative Rules

Operating Principles

Phase 0 — Orientation

Step 0.1 — Detect existing AI setup

Step 0.2 — Orientation

Phase 1 — Project Identity

Investigate

Infer

Ask the user

Phase 1.5 — Skillset Profile

Investigate

Present

Record

Phase 2 — Application Tech Stack

Investigate

Present

Phase 3 — Infrastructure-as-Code & Deployment

Investigate

Present

Phase 4 — Repository Structure

Investigate

Present

Phase 5 — Architecture Rules & Conventions

Investigate

Present

Phase 6 — Observability

Investigate

Present

Phase 7 — Security & Compliance

Investigate

Present

Phase 8 — Domain & Settled Decisions

Investigate

Present

Phase 9 — Jira Integration (optional)

Investigate

Present

Output Generation

Output 1 — CLAUDE.md

Output 2 — Project Context Block

After Output

Step 1 — Detect local skills

Step 2 — Insert Project Context into local skills

Step 3 — MCP Setup

Step 4 — Finish

Project Onboard Skill

Authoritative Rules

Operating Principles

Phase 0 — Orientation

Step 0.1 — Detect existing AI setup

Step 0.2 — Orientation

Phase 1 — Project Identity

Investigate

Infer

Ask the user

Phase 1.5 — Skillset Profile

Investigate

Present

Record

Phase 2 — Application Tech Stack

Investigate

Present

Phase 3 — Infrastructure-as-Code & Deployment

Investigate

Present

Phase 4 — Repository Structure

Investigate

Present

Phase 5 — Architecture Rules & Conventions

Investigate

Present

Phase 6 — Observability

Investigate

Present

Phase 7 — Security & Compliance

Investigate