accelint-onboard-agents

# Onboard Agents Guide the user through a conversational interview to produce a complete, project-specific `AGENTS.md` (or `CLAUDE.md`) governing how an AI coding agent behaves across all interactions in the project. ## Separation of Concerns This skill produces the **behavior layer** of the agent instruction stack. It is the companion to the `accelint-onboard-openspec` skill, which produces the **project DNA layer** (`openspec/config.yaml`). They never duplicate each other. ``` ┌──────────────────────────────────────────────────────────────┐ │ Agent Instruction Stack │ ├──────────────────────────────────────────────────────────────┤ │ │ │ AGENTS.md / CLAUDE.md ← THIS SKILL │ │ ───────────────────── (Layer 1: Agent Identity) │ │ WHO the agent is, HOW it works, WHEN it communicates │ │ │ │ • Role definition │ │ • Communication style and tone │ │ • Workflow procedures (PR flow, commit conventions) │ │ • Decision-making heuristics │ │ • Tool usage preferences │ │ • Behavioral guardrails │ │ │ ├──────────────────────────────────────────────────────────────┤ │ │ │ openspec/config.yaml ← accelint-onboard-openspec skill │ │ ──────────────────── (Layer 2: Project DNA) │ │ WHAT the project is, WHAT stack it uses, WHAT rules apply │ │ │ │ • Domain description and tech stack │ │ • Architectural patterns and coding standards │ │ • Project structure and per-artifact rules │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ### Hard Rule: What Does NOT Belong Here If a piece of information answers "what is the project?" rather than "how should the agent behave?", it belongs in `config.yaml`, not here. | Belongs in AGENTS.md | Belongs in config.yaml | |-----------------------------------|-----------------------------------| | "Always run `pnpm check` before committing" | "Package manager: pnpm" | | "Use Conventional Commits" | "TypeScript 5.x, strict mode" | | "Ask before deleting files" | "Monorepo: Turborepo + PNPM" | | "Prefer small, focused PRs" | "`type` over `interface`" | | "You are a senior TS engineer" | "Domain: geospatial visualization"| | "Never force-push to main" | "Testing: Vitest + @testing-library"| --- ## NEVER Do When Onboarding Agents - **NEVER run codebase discovery serially** — Phase 3 spawns parallel subagents for different behavioral domains. Serial scanning wastes time on codebases with many config files spread across directories. - **NEVER skip discovery before asking questions** — attempt to infer behavioral conventions from the codebase before adding questions to the interview. A question about commit format when `commitlint.config.ts` exists wastes the user's time. - **NEVER omit sections from the generated AGENTS.md** — if a section cannot be inferred or answered, mark it with `<!-- TODO: fill in -->` rather than leaving it out. Missing sections silently shape agent behavior in unpredictable ways. - **NEVER duplicate root-level instructions in package-level files** — if a monorepo root AGENTS.md exists, package files should reference it and add only what is package-specific. Repeated instructions inflate context on every agent invocation. - **NEVER write the final file without showing a preview** — the user must see inferred values with source annotations and confirm before any filesystem write. --- ## Phases ### Phase 0 — File State Detection Before any interview question is asked, check whether the target file exists and assess its state. Never silently pick a mode — always announce the detected mode to the user and confirm before proceeding. **Step 1 — Monorepo root check** Before assessing the local file, determine whether the current working directory is a package inside a monorepo. If a root-level `AGENTS.md` or `CLAUDE.md` exists above the current directory: 1. Read the root file in full. 2. Announce: *"I found a root-level AGENTS.md at [path]. I'll use it as context to avoid duplicating instructions that apply to all packages. The file I generate here will reference the root where appropriate rather than repeating it."* 3. In the generated file, add a header reference: ```markdown <!-- Inherits from: [relative path to root AGENTS.md] --> <!-- Only package-specific overrides and additions are defined here. --> ``` 4. During the interview, at the start of each turn, surface what the root file already covers for that section before asking any questions: > "The root AGENTS.md defines [summary of this section's content]. > Does this package need to add to or override any of that?" If the user says no: emit a reference in the generated file rather than repeating the content. If the user flags additions or overrides: ask the normal turn questions scoped to what's actually missing or different. **Step 1.5 — Check for Related Documents** Before detecting local AGENTS.md state, check for related onboarding documents: 1. **Check for openspec/config.yml or openspec/config.yaml** - If exists: Read it to understand the project's stack and patterns - Note its existence for the "Related Documentation" section - Announce: "Found openspec/config.yml — I'll reference it for the separation of concerns boundary." 2. **Check for ARCHITECTURE.md** - If exists: Read it to understand system structure - Note its existence for the "Related Documentation" section - Announce: "Found ARCHITECTURE.md — I'll reference it in the behavioral docs." **Step 2 — Local file detection** ``` Does a local AGENTS.md (or CLAUDE.md) exist in the current directory? │ ├── No → MODE 1: Create │ Full interview from scratch. │ └── Yes → Read the file, then assess: │ ├── Empty or near-blank (< ~10 meaningful lines)? │ → MODE 1: Create (with overwrite confirmation) │ Ask: "AGENTS.md exists but appears empty — should I │ populate it from scratch, or preserve any current content?" │ ├── Contains recognised template sections? │ (## Role & Identity, ## Guardrails, ## Workflow Procedures, etc.) │ → Announce Mode 3, then ask intent question (see below). │ └── Contains real content in an unrecognised shape? → Announce Mode 2, then ask intent question (see below). ``` **Intent question** (asked for Mode 2 and Mode 3, before any other step): > "Before I start — would you like to **start fresh**, treating the > existing file as a reference only *(recommended)*, or **work with what's > already there**?" If the user chooses **start fresh**: proceed as Mode 1 (full interview), treating the existing file as a read-only reference. Carry forward any content from the existing file that is still accurate — don't silently discard it — but regenerate the structure from scratch. If the user chooses **build on what's there**: proceed with Mode 2 or Mode 3 as detected. **Recognised template sections** (any two or more = recognised shape): `## Role & Identity`, `## Communication`, `## Workflow Procedures`, `## Decision Heuristics`, `## Tool Preferences`, `## Guardrails` --- #### Mode 1: Create Run the full Phase 1 → Phase 2 → Phase 3 → Phase 4 interview. This is the happy path for a fresh repo or an explicit "start fresh" choice. --- #### Mode 2: Import (build on what's there) The file has real content that was not generated by this skill. Present the user with three options before touching anything: > "This AGENTS.md has existing content with a structure I don't recognise. > How would you like to proceed? > > **(a) Restructure** — I'll import your existing content, map it onto this > skill's template sections, flag any material that belongs in > `openspec/config.yaml` instead, run a targeted interview to fill gaps, > and produce a merged file ready to replace the current one. > > **(b) Append** — I'll run the full interview and add this skill's sections > below your existing content without modifying what's already there. > > **(c) Dry run** — I'll run the full interview and show you exactly what I > would have generated, with no changes to the filesystem. Use this to > evaluate fit before committing." **If option (a) is chosen:** 1. Read the file in full. 2. Map each existing section onto the skill's template sections. 3. Flag any content that violates the separation-of-concerns boundary (e.g., stack facts, tech versions, domain descriptions) — these belong in `openspec/config.yaml`. For each violation, ask: *"This describes [X] — that's project DNA and belongs in `config.yaml`. Should I move it there and leave a reference here?"* 4. Run a targeted interview covering only the gaps (sections with no existing coverage). 5. Show a merged preview before writing. Inferred/existing content is labelled `# from existing file`; new content is labelled `# new`. **If option (b) is chosen:** Run the full Phase 1 → Phase 4 interview and append the generated sections below a `---` divider and a comment: `<!-- Added by accelint-onboard-agents skill -->`. **If option (c) is chosen:** Run the full Phase 1 → Phase 4 interview and present the output in the conversation. Explicitly state: "No files were changed." Offer to re-run as (a) or (b) if the user is satisfied. --- #### Mode 3: Refresh (build on what's there) The file matches the skill's expected shape — it was likely produced by a previous run. Run an abbreviated interview covering only: 1. **Drift detection** — scan the codebase for changes since the file was last updated: | Signal | Where to look | |--------|---------------| | New packages added | `package.json`, workspace `package.json` files | | CI checks changed | `.github/workflows/` — new required gates? | | Husky hooks modified | `.husky/` — new pre-commit steps? | | New migration directory | `migrations/`, `prisma/migrations/`, `alembic/` | | Versioning tooling added | `.changeset/`, `.releaserc*` | | OpenSpec added/removed | `openspec/` directory presence | | New protected branches | `.github/branch-protection*`, README | 2. **Unresolved TODOs** — find all `<!-- TODO: fill in -->` markers left from the previous run and surface them as targeted questions. 3. **Announce findings** before asking anything: > "I found [N] sections that may have drifted and [M] unresolved TODOs. > I'll only ask about those — the rest looks current." 4. After the targeted interview, show a diff-style preview (changed sections only) before writing. Do not re-emit sections that have not changed. --- ### Phase 1 — Discovery Interview Run the interview conversationally. Don't dump all questions at once. Group them into natural topic turns. If the user describes a workflow, infer related behavioral constraints and confirm rather than asking again. **Turn 1 — Role & Identity** - What role should the agent play? ("senior TypeScript engineer", "full-stack developer", "pair programmer", "code reviewer", etc.) - Is the agent scoped to a specific domain? ("focuses on the rendering pipeline", "works across the full monorepo", etc.) - Any role constraints? ("never makes architectural decisions alone") **Turn 2 — Communication Style** - How verbose should responses be? (concise summaries, detailed explanations, adaptive to the question?) - Preferred format for code changes? (show diffs, show full files, inline comments, separate explanation block?) - How should the agent handle uncertainty? ("state assumption and proceed", "always ask before proceeding", "ask for scope-changing uncertainty only"?) - Should the agent explain its reasoning, or just act? **Turn 3 — Workflow Procedures** - What is the standard flow for a new feature? (e.g., propose → spec → design → implement → test → PR) - For bug fixes, is the flow different? - What checks must always run before committing? (type-check, lint, tests?) - Any PR conventions? (size limits, labels, draft vs. ready, review requests?) - Commit message convention? (Conventional Commits, gitmoji, free-form, with example format?) - Versioning workflow? (when to bump, who approves changelog?) **Turn 4 — OpenSpec / Spec-Driven Workflow** *(skip if not using OpenSpec)* - When should the agent invoke `/opsx:propose`? *Good default: "for any new feature or non-trivial change".* - When is a spec required vs. optional? - Should the agent reference existing specs before creating new patterns? - How should the agent handle a task that has no existing spec? **Turn 5 — Decision Heuristics** - When should the agent ask vs. proceed autonomously? *Good prompts: "deleting files", "changing public APIs", "modifying migrations", "adding new dependencies".* - Any operations that require explicit human sign-off before acting? - How should scope creep be handled if discovered mid-task? - If two approaches are equally valid, should the agent pick one, ask, or present both? **Turn 6 — Tool & Command Preferences** - Any tool-level preferences the agent should honor? *Examples: "prefer vitest over jest", "use pnpm, never npm", "biome for formatting, never prettier".* - Any CLI commands the agent should always/never run? *Examples: "never run `git push --force`", "always use `pnpm` not `npm run`".* - Any environment setup the agent should validate before starting? **Turn 7 — Guardrails** - Hard "never" rules? (operations that are always off-limits) *Examples: "never force-push to main", "never delete migration files", "never commit secrets".* - Soft "always ask first" rules? *Examples: "ask before modifying `package.json` scripts", "ask before changing shared utility packages".* - Any security-sensitive areas that require special handling? --- ### Phase 2 — Smart Defaults After each workflow answer, surface relevant behavioral conventions to confirm. Use these examples as a pattern; extend to other stacks as appropriate. **Turborepo + PNPM monorepo → suggest confirming:** - "I'll assume you want `pnpm -w` (workspace root) for adding shared deps and `pnpm --filter <pkg>` for package-scoped deps; correct?" - "For tasks, I'll default to `pnpm turbo run build --filter=...` rather than running package scripts directly; correct?" **GitHub Actions CI → suggest confirming:** - "Should I wait for CI to pass before treating a PR as mergeable?" - "Any required status checks the agent should reference before marking work done?" **Conventional Commits → suggest confirming:** - "I'll use `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:` — any additional types your team uses (e.g., `perf:`, `ci:`)?" - "Are breaking changes annotated with `!` suffix (e.g., `feat!:`) or with a footer `BREAKING CHANGE:` block?" **Spec-Driven Development (OpenSpec) → suggest confirming:** - "For non-trivial changes, I'll start with `/opsx:propose` before writing any code; should I also require a design artifact for changes touching more than N files?" - "Should I link task IDs or spec refs in commit messages?" --- ### Phase 3 — Parallel Codebase Discovery (fill gaps before generating) After the interview, audit every AGENTS.md section that still has no answer. For each gap, attempt to derive the behavioral intent directly from the codebase using parallel subagents before asking or leaving a `# TODO`. A behavioral file with explicit TODOs is actionable; a file with missing sections silently shapes agent behavior in unpredictable ways. Spawn discovery subagents in parallel — don't scan serially. Each agent focuses on one behavioral domain and returns structured findings. Wait for all agents to complete, then merge results before Phase 4. **Spawn these agents simultaneously:** **Agent A — Version Control & Commit Conventions** - Commit convention: `commitlint.config.*`, recent `git log --oneline`, `.gitmessage`, `.releaserc*` - Versioning workflow: `.changeset/`, `CHANGELOG.md`, `standard-version`, `conventional-changelog` - Forced-push protection: `.github/branch-protection*`, README mentions of branch policy - Return: commit message format with types and examples, versioning commands, branch protection rules **Agent B — CI/CD & Pre-commit Workflows** - PR workflow: `.github/PULL_REQUEST_TEMPLATE.md`, `.github/workflows/` (CI gate names, required checks) - Pre-commit checks: `.husky/`, `.lefthook.yml`, `package.json#scripts` (lint, typecheck, test) - Return: PR conventions (size, labels, templates), pre-commit checklist with commands, CI required checks **Agent C — Testing & Code Quality** - Test runner: `vitest.config.*`, `jest.config.*`, `pytest.ini`, `pyproject.toml [tool.pytest]`, Playwright, Cypress - Package manager: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb` - TypeScript project: `tsconfig.json` presence, path aliases in `tsconfig.json#paths` or `vite.config` - Vitest config: `vitest.config.ts` — check for `clearMocks`, `mockReset`, `restoreMocks` flags - Test file type checking: CI workflows, `package.json` scripts — check if `tsc --noEmit` runs on test files - Return: test framework, package manager, TS-specific guardrails if applicable, vitest cleanup config **Agent D — Security & Migrations** - Migration files: presence of `migrations/`, `prisma/migrations/`, `alembic/` - Secret handling: `.env.example`, `.gitignore` patterns, presence of `dotenv` / vault tooling - Return: migration guardrails if migrations exist, secret handling practices **Agent E — OpenSpec & Development Workflow**