Project Onboard

Project Onboard

A skill that onboards AI agents into any project by generating structured, task-routed context files. Unlike /init which produces a flat agent file, this skill creates a progressive disclosure system where the agent reads only what it needs for the current task — saving tokens and eliminating redundant project exploration.

Invocation

/project-onboard                     First run: full onboard. Re-run: refresh + audit.
/project-onboard --quick             Phase 1+2 only (skip audit & interview)
/project-onboard Thai                Full onboard, confirm output language first

Do not create or document separate update or audit commands. /project-onboard is the single entrypoint; when it is run again, it refreshes existing context and re-runs the audit automatically. Treat plain "onboard" as a natural-language request to run project-onboard behavior; do not create, document, or refer to a /onboard slash command.

Start Here: Choose the Run Mode

Before doing any phase, decide whether this is a first onboard or a rerun. Do this even if the user only says /project-onboard, because the same command handles both first-run onboarding and reruns.

Check for existing generated context:

• .context/onboard-meta.json
• AGENTS.md or CLAUDE.md
• .context/features/audit-meta.json

Use this decision table:

Generated project-onboard markers are <!-- generated by project-onboard -->, .context/onboard-meta.json, or task-routing that points to .context/. If an instruction file exists without these markers, treat it as user-written input to preserve and merge, not as proof that project-onboard already ran.

First onboard

Run Phase 1 and Phase 2. Then ask whether to run Phase 3 and Phase 4 unless the user requested --quick.

Rerun project-onboard

Refresh generated context and then re-run the audit. Do not ask whether to audit; re-running onboard is already a request to make the generated context current. This is internal behavior of the same /project-onboard command, not a separate update or audit command.

Rerun goals:

1. Refresh stale or changed context files.
2. Re-run the 8-category audit for changed areas, or fully if reliable change detection is not possible.
3. Update .context/features/_feature-map.md and audit metadata.
4. Update task-routing in the canonical instruction file when routes, APIs, data, auth, jobs, integrations, testing, warnings, or workflows changed.
5. Preserve interview-derived files and user-written instruction content. Update only generated project-onboard sections unless the user explicitly asks to revise user-written content.
6. Update .context/onboard-meta.json with last_update, last_audit, git_commit, completed phases, detected categories, and cached docs status.

If the repo has no git history, the stored commit is missing, or the diff fails, fall back to a conservative full refresh of Phase 1, Phase 2 context files, and Phase 3. Preserve interview answers and existing user-written sections.

Language Support

If the user appends a language name to the command (e.g., /project-onboard Thai, /project-onboard Japanese), confirm the language before proceeding:

"You requested output in Thai. This will generate all context files
and agent instruction files in Thai. Confirm? (yes/no)"

If confirmed, write ALL output files in that language — AGENTS.md, CLAUDE.md shim, context files, feature map, everything. The SKILL.md instructions themselves remain in English, but generated output respects the user's language choice.

Default language is English if not specified.

How It Works

The skill runs 4 phases. Each phase builds on the previous one. The agent knows more at each step, so later phases are smarter.

Phase 1: DISCOVER .......... auto-detect stack + research docs
Phase 2: GENERATE .......... create AGENTS.md + CLAUDE.md shim + context files
Phase 3: FEATURE AUDIT ..... map Page → API → DB → Feature (optional)
Phase 4: INTERVIEW ......... ask the developer (knows everything now)

Phase 3 and 4 are optional on first run. On reruns, Phase 3 runs automatically unless the user requested --quick. After Phase 2 on first run, ask the user:

• "Want me to audit existing features? (maps pages, endpoints, DB)"
• "Want me to interview you for business context?"

If the user runs /project-onboard --quick, skip Phase 3 and 4.

On reruns, the skill should be quiet and direct: update generated context and audit outputs first, then summarize what changed. Ask questions only when a canonical instruction file choice is ambiguous or when preserving user-written content requires a decision.

Phase 1: DISCOVER

Two sub-phases. Do not ask the user anything during this phase.

Phase 1a: DETECT

Read project files to identify the tech stack and tooling. Do NOT use find or ls recursively. Read specific known files only.

Check these files (skip if they don't exist):

Package managers & stack:

• package.json → Node.js ecosystem, framework, dependencies, scripts
• pubspec.yaml → Flutter/Dart
• go.mod → Go
• requirements.txt / pyproject.toml / Pipfile → Python
• Cargo.toml → Rust
• composer.json → PHP
• Gemfile → Ruby

Mobile:

• package.json dep react-native → React Native
• app.json / app.config.js → Expo
• pubspec.yaml dep flutter → Flutter

State management:

• @reduxjs/toolkit / zustand / jotai / @tanstack/react-query in deps
• riverpod / bloc / provider in pubspec.yaml

Background jobs:

• bullmq / bull / celery / sidekiq in deps
• Queue processor files

i18n:

• Locale files (en.json, th.json, etc.)
• i18n library in deps (next-intl, react-i18next, flutter_localizations)

Configuration:

• tsconfig.json → TypeScript settings
• .eslintrc* / biome.json / .prettierrc → linting/formatting
• docker-compose.yml / Dockerfile → containerization
• vercel.json / netlify.toml / fly.toml → deploy target
• .env.example → environment variables (NEVER read .env)

Database:

• prisma/schema.prisma → Prisma schema
• drizzle.config.ts → Drizzle ORM
• knexfile.* / ormconfig.* → other ORMs
• migrations/ or db/migrate/ → check migration tool

CI/CD & workflows:

• .github/workflows/ → GitHub Actions
• .gitlab-ci.yml → GitLab CI
• .husky/ → git hooks

Testing:

• jest.config* / vitest.config* / playwright.config* / cypress.config*
• Count test files: how many *.test.* or *.spec.* files exist

Existing AI context:

• AGENTS.md → preferred canonical agent instructions; preserve, merge later
• CLAUDE.md → existing Claude Code instructions; ask user before migrating
• .cursor/rules/ → import conventions
• .github/copilot-instructions.md → existing copilot rules

Documentation:

• README.md → project description, setup
• CONTRIBUTING.md → team conventions
• CHANGELOG.md → recent changes, current version
• docs/ → architecture docs

Phase 1b: RESEARCH

Use the information from Phase 1a to do targeted research.

1. Project docs — read what exists in the repo

Read README.md fully. Extract: project purpose, setup instructions, architecture notes. If CONTRIBUTING.md or docs/ exist, read those too.

2. Stack docs — pull up-to-date docs via Context7 (conditional)

Read .context/onboard-meta.json if it exists. For each major dependency:

• If version has changed since last onboard → pull fresh docs
• If docs are older than 7 days → pull fresh docs
• If docs are fresh and version unchanged → SKIP, use cached

When pulling, query Context7 for the specific version detected. Focus on: conventions, breaking changes, migration guides, best practices.

Save results to .context/stack-docs/{lib}-{version}.md

3. Skills — search for relevant skills

Based on detected stack, search for available skills:

• npx skills search {framework} if the CLI is available
• Or note recommendations from known sources:
  • vercel-labs/agent-skills (React, Next.js, deploy)
  • VoltAgent/awesome-agent-skills (community collection)

Store recommendations for Phase 2 output and Phase 4 suggestion.

4. Ecosystem — verify actual tooling

Read package.json scripts to understand real build/test/dev commands. Read CI config to understand actual pipeline steps. Read tsconfig/eslint to understand actual code conventions. DO NOT assume — verify from config files.

Phase 2: GENERATE

Generate the output files. Read references/output-format.md for the complete templates and file structure.

PATH RULES — read carefully before writing any file:

• Context files go in project-root/.context/ (a top-level dot folder)
• Canonical agent instructions go in project-root/AGENTS.md (plural)
• Claude Code compatibility instructions go in project-root/CLAUDE.md
• The single Claude command goes in project-root/.claude/commands/project-onboard.md
• These are TWO SEPARATE directories at project root. Do NOT nest .context/ inside .claude/.
• Wrong: .claude/context/, .claude/.context/, .claude/architecture.md
• Correct: AGENTS.md, CLAUDE.md, .context/architecture.md, .claude/commands/project-onboard.md

Before creating the first file, double-check: are you about to write to .context/ or .claude/context/? If the path contains .claude/context or .claude/.context, STOP — that's wrong. Fix it to .context/.

Output structure

project-root/
├── AGENTS.md                          # ≤ 150 lines, canonical task-routed instructions
├── CLAUDE.md                          # Compatibility shim pointing to AGENTS.md, unless user chooses otherwise
├── .context/                          # ⚠️ THIS IS project-root/.context/ — NOT .claude/context/
│   ├── architecture.md                # Directory map + patterns
│   ├── conventions.md                 # Coding standards (from config)
│   ├── workflow.md                    # CI/CD, deploy, branch strategy
│   ├── stack-docs/                    # Cached library docs
│   │   └── {lib}-{version}.md
│   ├── warnings.md                    # Things to watch out for
│   └── onboard-meta.json             # Metadata for reruns
└── .claude/
    ├── commands/
    │   └── project-onboard.md                 # /project-onboard command (single entrypoint)
    └── .claudeignore                  # (if not exists) auto-generated

⚠️ CRITICAL PATH WARNING: .context/ lives at project root — the same level as AGENTS.md and CLAUDE.md. NEVER create .claude/context/ — that is wrong. The two directories are separate:

• .context/ = onboard context files (architecture, conventions, features, etc.)
• .claude/ = Claude commands and config only

Agent Instruction Files — CRITICAL RULES

Use AGENTS.md (plural) as the preferred canonical instruction file. AGENT.md singular is not the convention used here.

The canonical instruction file is NOT documentation for humans. It is a decision tree for the AI agent.

Write it using the task-based routing pattern:

BEFORE [action] → read [file]
WHEN [situation] → read [file]

Never just list files. Always tell the agent WHEN to read each file.

Read references/output-format.md for the full AGENTS.md template and CLAUDE.md shim templates.

Existing instruction file policy

Before writing AGENTS.md or CLAUDE.md, detect which instruction files already exist:

• If neither AGENTS.md nor CLAUDE.md exists:
  • Create full task-routed content in AGENTS.md.
  • Create CLAUDE.md as a small shim that tells Claude Code to read AGENTS.md first.
• If AGENTS.md exists and CLAUDE.md does not:
  • Preserve and merge into AGENTS.md.
  • Create CLAUDE.md as a small shim pointing to AGENTS.md.
• If CLAUDE.md exists and AGENTS.md does not:
  • Ask the user before changing ownership: "I found an existing CLAUDE.md. Do you want me to migrate its content into AGENTS.md and replace CLAUDE.md with a pointer, or keep CLAUDE.md as the canonical file and create AGENTS.md as a pointer to it?"
  • If the user chooses migration: read CLAUDE.md, preserve all user-written content in AGENTS.md, add generated task-routing sections, then replace CLAUDE.md with a shim pointing to AGENTS.md.
  • If the user chooses to keep Claude canonical: preserve and merge into CLAUDE.md, then create AGENTS.md as a shim pointing to CLAUDE.md.
• If both AGENTS.md and CLAUDE.md exist:
  • Read both.
  • Prefer AGENTS.md as canonical unless CLAUDE.md clearly contains newer or more complete user-written instructions.
  • If the canonical choice is ambiguous, ask before merging.
  • Keep the non-canonical file as a shim pointing to the canonical file.

Never discard user-written instruction content. A shim may replace an existing file only after its original content has been migrated into the canonical file or the user explicitly chooses that direction.

Context files — AI-first writing

Every context file must start with:

1. WHEN to read this file (one line)
2. HOW the agent should use the information
3. The actual content — concise, structured, actionable

Do NOT write prose. Write structured data the agent can act on.

onboard-meta.json

{
  "version": "2.0",
  "last_onboard": "ISO-8601",
  "last_update": "ISO-8601",
  "last_audit": "ISO-8601",
  "git_commit": "hash",
  "previous_git_commit": "hash",
  "language": "en",
  "agent_instructions": {
    "canonical": "AGENTS.md",
    "shim": "CLAUDE.md",
    "shim_direction": "CLAUDE.md -> AGENTS.md"
  },
  "stack": ["nextjs", "prisma", "postgresql"],
  "platforms": {
    "web": true,
    "mobile": false,
    "backend": true
  },
  "categories_detected": [
    "pages-routing",
    "api-middleware",
    "data-layer",
    "auth-security",
    "background-events",
    "integrations-infra"
  ],
  "stack_docs": {
    "next": { "version": "15.1.0", "docs_pulled_at": "ISO-8601" }
  },
  "phases_completed": ["discover", "generate"],
  "interview_done": false,
  "audit_done": false,
  "last_run_mode": "first-onboard | rerun-project-onboard | first-run-quick | rerun-quick | recovery-rerun"
}

Merging with existing instruction files

If the canonical instruction file already exists:

1. Read it fully
2. Preserve all existing content
3. ADD missing sections (task routing, context references, warnings)
4. DO NOT overwrite user-written content
5. Mark generated sections with <!-- generated by project-onboard -->

Skill recommendations

After generating files, show the user what skills are available:

"Detected: Next.js + React + Prisma. Recommended skills:"
  1. vercel-react-best-practices — 40+ React performance rules
  2. web-design-guidelines — accessibility + UX audit
  
"Install with: npx skills add vercel-labs/agent-skills@vercel-react-best-practices"
"Want me to install any of these?"

Phase 3: UNIVERSAL AUDIT (optional on first run, automatic on rerun)

On first onboard, ask before running unless the user already requested an audit: "Want me to audit existing features? I'll scan pages, state, UI, API, data, auth, jobs, and integrations." On rerun project-onboard, do not ask; run the audit automatically after refreshing generated context.

Scan the codebase using 8 categories. Each category auto-detects and auto-skips if not found. Read references/universal-audit.md for full scanning strategies, then read templates/feature-audit-format.md for the exact output templates.

The 8 Categories

Cross-reference all detected categories into _feature-map.md. Also identify orphans: unmapped endpoints, pages, state, jobs, DB tables.

Audit refresh mode

When rerunning /project-onboard on an existing onboarded repo:

1. Read .context/features/audit-meta.json if it exists.
2. Read .context/onboard-meta.json if it exists.
3. Determine changed files:
   • If the context refresh step already produced changed files in this run, reuse them.
   • If changed files are not available, diff from the commit recorded in audit-meta.json; if absent, use onboard-meta.json git_commit; if absent, use previous_git_commit.
   • If no reliable commit is available, run the full audit.
4. Use changed files to choose affected audit categories.
5. Re-scan affected categories fully enough to keep cross-references accurate. A page change can affect API callers; an API change can affect pages and the feature map; schema/auth/job/integration changes can affect multiple feature sections.
6. Always rebuild .context/features/_feature-map.md from the current category outputs, because the feature map is the cross-category index.
7. If affected categories cannot be determined confidently, run the full 8-category audit instead of leaving stale feature maps.
8. Update audit-meta.json with scanned categories, skipped categories, coverage counts, orphan counts, last_audit, and the git commit used.

Output files

Remember: .context/ is at project root, not inside .claude/.

.context/features/
  ├── _feature-map.md           # Cross-reference all categories per feature
  ├── pages-routing.md          # 1: Pages & Routing (web + mobile)
  ├── state-data.md             # 2: State & Data Fetching
  ├── design-system.md          # 3: Design System & UI
  ├── api-middleware.md          # 4: API & Middleware
  ├── data-layer.md             # 5: Data Layer
  ├── auth-security.md          # 6: Auth & Security
  ├── background-events.md      # 7: Background & Events
  ├── integrations-infra.md     # 8: Integrations & Infra
  └── audit-meta.json           # Coverage stats per category

After generating, update the canonical instruction file with task-routing rules:

BEFORE modifying or creating any page, screen, or route:
  → read .context/features/pages-routing.md
  → read .context/features/_feature-map.md

BEFORE modifying app state (stores/slices/providers):
  → read .context/features/state-data.md
  → read .context/features/pages-routing.md (check consumers)

BEFORE modifying UI components, theming, forms, or i18n:
  → read .context/features/design-system.md

BEFORE modifying or creating any API endpoint:
  → read .context/features/api-middleware.md
  → read .context/features/pages-routing.md (check callers)

BEFORE modifying database schema, caching, or migrations:
  → read .context/features/data-layer.md
  → read .context/features/_feature-map.md (check impact)

BEFORE modifying auth, permissions, or security config:
  → read .context/features/auth-security.md

BEFORE modifying background jobs, events, or service communication:
  → read .context/features/background-events.md

BEFORE modifying external integrations, logging, or config:
  → read .context/features/integrations-infra.md

Phase 4: INTERVIEW (optional)

The agent has now scanned and understood the entire project. Questions are informed by everything discovered in Phase 1-3.

Ask before running: "Want me to ask you some questions about the project? This helps me understand things code can't tell me."

If Phase 3 was completed — short interview (3 questions)

The agent already knows the codebase deeply. Ask only what code cannot reveal:

1. "[Summary from README + code]. Is this accurate?
    Any business context or domain terms I should know?"

2. "Any conventions, processes, or areas I should NOT touch
    without asking first?"

3. "Anything else you want me to know?"

If Phase 3 was skipped — full interview (4 groups)

Group 1: Business & Domain

1. "What does this project do? Who are the main users?"
2. "Any domain-specific terms I should understand?"
3. "What phase is this project in?
    (MVP / active dev / maintenance / legacy refactor)"

Group 2: Team & Workflow

4. "How many people work on this? Code review process?"
5. "Branch strategy? (trunk-based / gitflow / feature branches)"
6. "Deploy process? (auto/manual, staging environment?)"
7. "Any conventions you want me to always follow?"

Group 3: Code Quality & Testing

8. "Want to restructure the code?
    (e.g., extract business logic to service layer)"
    — If Phase 1 found logic in route handlers, mention it specifically.

9. "Do you want TDD? (write tests before implementation)"

10. "Testing strategy?"
    — Unit only
    — Unit + Integration
    — Unit + Integration + E2E
    — No tests yet, want to start

11. "Test framework preference?"
    — Mention what was detected: "Found [vitest/jest], correct?"
    — For E2E: Playwright / Cypress / other?

12. "Coverage target? (none / 60% / 80% / 90%+)"
    — If tests exist, mention current estimated coverage.

Group 4: AI Behavior

13. "Anything that AI agents frequently break in this project?"

14. "Files or folders I should never modify without asking?"

15. "How autonomous should I be?"
    — Conservative: always ask before acting
    — Balanced: act but explain
    — Autonomous: just do it

16. "Anything else I should know?"

Adaptive questions

Questions MUST adapt to what was discovered. Do not ask generic questions when you already have the answer from Phase 1-3.

Example — tests detected:

BAD:  "Do you want to write tests?"
GOOD: "Found Vitest with 23 test files, ~45% coverage.
       Want me to help increase coverage? Add E2E with Playwright?"

Example — logic in route handlers:

BAD:  "Want to restructure the code?"
GOOD: "Found business logic directly in route handlers
       (e.g., /api/pipelines has 120 lines of logic).
       Want me to extract it to a service layer?"

Interview output

Save answers to context files:

• Business context → .context/business.md
• Testing strategy → .context/testing-strategy.md
• Update warnings.md with files/areas to protect
• Update workflow.md with team process info
• Update conventions.md with stated preferences
• Update the canonical instruction file task-routing with new sections

Update onboard-meta.json: set interview_done: true.

Rerun Project Onboard (/project-onboard)

When the user runs /project-onboard in a repo that already has onboard context, refresh generated context and re-run the audit through the same command. Do not tell the user to run a separate update or audit command.

1. Read .context/onboard-meta.json
2. Validate the canonical instruction file recorded in agent_instructions.canonical; if it moved or disappeared, detect the best canonical file using the existing instruction file policy.
3. Run git diff {last_commit}..HEAD --name-only to find changed files
   • Use git_commit from metadata as {last_commit}.
   • If git_commit is missing, invalid, or unavailable, fall back to previous_git_commit.
   • If git diff cannot run, perform a full refresh.
   • If the diff is empty, still check docs cache freshness and audit metadata timestamps before deciding there is nothing to update.
4. For each changed file, determine which context files need updating:
   • package.json changed → re-detect stack, check if docs need refresh
   • prisma/schema.prisma changed → update .context/features/data-layer.md + .context/features/_feature-map.md
   • Route files changed → update .context/features/api-middleware.md + .context/features/_feature-map.md
   • Page files changed → update .context/features/pages-routing.md + .context/features/_feature-map.md
   • Config files changed → update conventions.md or workflow.md
5. Update only affected context files and the canonical instruction file recorded in agent_instructions.canonical if task-routing changed
6. Keep the shim direction recorded in agent_instructions.shim_direction unless the user asks to change canonical ownership
7. Unless the user requested /project-onboard --quick, run Phase 3 audit refresh mode after context files are refreshed.
8. Preserve interview-derived files unless the user asks to redo interview:
   • .context/business.md
   • .context/testing-strategy.md
   • interview sections merged into .context/warnings.md, .context/workflow.md, and .context/conventions.md
9. Update onboard-meta.json with new timestamp, previous_git_commit, current git_commit, last_run_mode, and audit fields if audit ran. Before replacing git_commit, copy the old git_commit to previous_git_commit; on first onboard, set previous_git_commit to null or omit it.
10. Show summary: "Updated X context files and Y audit files based on Z changed files since last onboard"

For full refresh requests or recovery reruns:

• Re-scan everything from Phase 1.
• Regenerate all generated context files.
• Preserve interview answers; do not re-ask unless the user asks to redo them.
• Run Phase 3 unless the user requested /project-onboard --quick.

Rerun safety rules

• Never delete user-written sections from AGENTS.md, CLAUDE.md, or context files. Merge generated sections in place.
• Never rewrite interview answers just because code changed.
• Never skip the feature map on rerun. If any category changed, rebuild _feature-map.md.
• Prefer targeted updates when the diff is reliable; prefer full refresh when the diff is missing, ambiguous, or would risk stale context.
• Do not ask the user routine first-run questions on rerun. Ask only for ambiguous canonical ownership or explicit business-context gaps.

Stack Docs Caching

Context7 docs are cached in .context/stack-docs/. Pull strategy:

Future: Multi-agent Support

This skill generates AGENTS.md as the canonical, agent-neutral entrypoint and CLAUDE.md as a Claude Code compatibility shim. Future versions may support additional wrappers:

Claude Code  → CLAUDE.md shim → AGENTS.md + .context/
Cursor       → .cursor/rules/
Codex        → AGENTS.md + .context/
Copilot      → .github/copilot-instructions.md

The context files in .context/ are written in agent-neutral markdown. Adding support for other agents means generating a wrapper file that routes to the same context.

Reference files

Read these before generating output:

• references/output-format.md — AGENTS.md template, CLAUDE.md shim template, context file templates
• references/universal-audit.md — Full scanning strategies + output templates for all 8 audit categories
• templates/feature-audit-format.md — Feature audit output templates