# Project Onboard

> Onboard an AI agent into any project — detect stack (web, mobile, backend), research up-to-date docs, run a universal 8-category audit (pages, state, UI, API, data, auth, jobs, integrations) with auto-detection and auto-skip, interview the developer, and generate structured context files with task-based routing so the agent never wastes time exploring the project again. Re-running project-onboard on an already-onboarded repo refreshes changed context, re-runs the feature audit, preserves interview answers, and updates routing without requiring separate update or audit commands. Use this skill whenever the user says "onboard", "onboard again", "rerun onboard", "update onboard", "refresh context", "set up context", "scan this project", "generate AGENTS.md", "generate CLAUDE.md", "map this codebase", "audit features", "what does this project do", or any request to help an AI agent understand a new or existing codebase. Also trigger when the user starts working in an unfamiliar repo or an existing repo with stale

- Skill: `nixxel-company-limited/project-onboard` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add nixxel-company-limited/project-onboard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nixxel-company-limited/project-onboard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nixxel-company-limited (https://skillmd.com/u/nixxel-company-limited)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nixxel-company-limited/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:

| Situation | Run mode |
|-----------|----------|
| No `.context/onboard-meta.json` and no generated instruction files | First onboard |
| No `.context/onboard-meta.json`, but `AGENTS.md` or `CLAUDE.md` exists without project-onboard markers | First onboard with existing instruction file policy |
| Existing `.context/onboard-meta.json` and user says `/project-onboard`, "onboard again", "rerun", "update", or "refresh" | Rerun project-onboard: refresh + audit |
| Existing context but metadata is missing or invalid | Recovery rerun: full refresh + audit, preserve existing files |
| User asks `/project-onboard --quick` on a new repo | First-run quick: run Phase 1+2 only |
| User asks `/project-onboard --quick` on an already-onboarded repo | Rerun quick: refresh generated context only; skip audit and interview |

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

```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

| # | Category | Output file | What it covers |
|---|----------|-------------|----------------|
| 1 | Pages & Routing | `pages-routing.md` | Pages, screens, navigation, deep links, route guards |
| 2 | State & Data Fetching | `state-data.md` | Stores, slices, providers, client caching, data fetching |
| 3 | Design System & UI | `design-system.md` | Components, theming, forms, i18n, accessibility |
| 4 | API & Middleware | `api-middleware.md` | Endpoints, middleware pipeline, validation, error handling |
| 5 | Data Layer | `data-layer.md` | DB schema, migrations, caching, transactions, seeds |
| 6 | Auth & Security | `auth-security.md` | Authentication, authorization, rate limits, CORS, secrets |
| 7 | Background & Events | `background-events.md` | Jobs, event-driven arch, scheduled tasks, service comms |
| 8 | Integrations & Infra | `integrations-infra.md` | External APIs, file storage, logging, config, health checks |

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:

| Condition | Action |
|-----------|--------|
| Never pulled | Pull now |
| Library version changed | Pull now (may have breaking changes) |
| Same version, docs ≤ 7 days old | Skip, use cache |
| Same version, docs > 7 days old | Pull fresh |
| User runs `--force-docs` | Pull everything |

---

## 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