accelint-onboard-agents

# Onboard Agents Guide the user through a conversational interview that produces a complete, project-specific `AGENTS.md` or `CLAUDE.md` for how an AI coding agent should behave in this repository. ## Separation of Concerns This skill produces the **behavior layer** of the agent instruction stack. Keep content here only when it directly improves recurring agent behavior. If a detail is better described as project background, stack fact, architecture explanation, process handbook material, or nearby reference documentation, use a canonical companion document and link to it instead of restating it here. These layers must not duplicate each other. Canonical companion documents may include `openspec/config.yml` or `openspec/config.yaml` for project DNA, `ARCHITECTURE.md` for system structure, `CONSTRAINTS.md` for externally imposed boundaries, `EPISTEMIC-MAP.md` for validated facts vs open questions and assumptions, and `JARGON.md` for internal terminology. Use the rule below to decide what stays in this file and what belongs in a canonical companion document. ### Hard Rule: What Does NOT Belong Here If material does not answer "how should the agent behave?", it does not belong in `AGENTS.md` or `CLAUDE.md`. Move that material to the appropriate canonical companion document when one exists, or leave it out. | Belongs in AGENTS.md | Belongs in a canonical companion document | |---|---| | "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`" | | "Work as a senior TS engineer when useful" | "Domain: geospatial visualization" | | "Never force-push to main" | "Testing: Vitest + @testing-library" | | "Read `ARCHITECTURE.md` before changing deployment-related code" | "Service topology and deployment model" | | "Check `CONSTRAINTS.md` before changing compliance-sensitive flows" | "The actual compliance or stakeholder constraint itself" | ### Final Inclusion Rule Only include guidance in the final `AGENTS.md` or `CLAUDE.md` when it earns a permanent place. A detail earns that place only when it: - changes how the agent should behave - applies to recurring work, not a one-off task - prevents the agent from making a repository-specific mistake or unsupported assumption - is durable enough for standing guidance - is valuable enough to load in every agent session Do not include a detail just because the agent might not know it already. Include it only when it describes a repository-specific rule or exception that affects how the agent should work. Otherwise, leave it out or link to the canonical document that contains it. Persona or identity framing is optional. Use it only when it improves behavior. Do not let role language replace operational guidance. --- ## NEVER Do When Onboarding Agents - **NEVER run codebase discovery serially** — when discovery is needed, use parallel subagents for different behavioral domains. Serial scanning wastes time on codebases with many config files spread across directories. - **NEVER skip needed discovery before asking questions** — infer behavioral conventions from the codebase before adding avoidable questions to the interview. A question about commit format when `commitlint.config.ts` exists wastes the user's time. For narrow refreshes, do only the scoped discovery the request needs. - **NEVER omit required template sections from the generated AGENTS.md** — if a required section from `./assets/template.md` cannot be inferred or answered, keep that section and mark unresolved fields with `<!-- TODO: fill in -->` rather than leaving the section out. Omit optional sections only when `./assets/template.md` explicitly allows it. Missing required template sections silently shape agent behavior in unpredictable ways. - **NEVER duplicate root-level instructions in package-level files** — if a monorepo root `AGENTS.md` or `CLAUDE.md` exists, package files should reference it and add only what is package-specific. Repeated instructions inflate context on every agent invocation. - **NEVER preserve conflicting standing rules only because both were found** — resolve conflicts using source precedence, or surface the unresolved issue in preview instead of emitting both as authoritative guidance. - **NEVER write the final file without showing a preview** — the user must see inferred values with source annotations and confirm before any filesystem write. --- ## Conflict Resolution and Source Precedence When candidate rules conflict during import, refresh, or final synthesis, resolve them in this order: 1. **Direct user-confirmed answers** 2. **Confirmed repository policy or explicitly documented repository behavior** 3. **Evidence-backed inference from repository materials** 4. **Existing `AGENTS.md` or `CLAUDE.md` content that remains consistent with stronger evidence** 5. **Template defaults or generic skill defaults** 6. **`<!-- TODO: fill in -->` or an explicit open question instead of forced synthesis when conflict remains unresolved** Apply this rule every time: - Do not preserve conflicting rules because both were discovered. - Do not let defaults outrank stronger repository evidence. - Do not let old file content survive unchanged if it conflicts with current confirmed evidence. - When uncertainty remains, surface it in preview or use a TODO instead of inventing a unified rule. --- ## Workflow at a Glance Follow this workflow in order. Do not skip ahead. Complete each gate before moving to the next step. ### Step 0: Start progress tracking Do this before any other workflow step. Create a progress checklist with your task-tracking tool. If no tool is available, copy the checklist below into your working state or reply. Update it after each completed step or branch handoff. - [ ] Step 1: Check for a monorepo root instruction file - [ ] Step 2: Check for related documents - [ ] Step 3: Detect the local file state - [ ] Step 4: Confirm how to use the existing file when Mode 2 or Mode 3 was detected - [ ] Step 5: Choose the branch inside Mode 2 or Mode 3 when needed - [ ] Step 6: Run the selected mode playbook - [ ] Step 7: Fill remaining behavioral gaps with parallel discovery if needed - [ ] Step 8: Run the final editorial pass - [ ] Step 9: Show the full labeled preview and collect review feedback - [ ] Step 10: Write the confirmed file when this path writes output - [ ] Step 11: Run the post-write quality check when a file was written - [ ] Step 12: Print the completion summary Important sequencing rule: - **Step 1**, **Step 2**, and **Step 3** determine the local file state and detect the mode. - **Step 4** and **Step 5** confirm the user's intent and choose the branch inside that detected mode. - **Step 6** executes exactly one mode playbook. - **Step 7** runs only if required template fields still have unresolved behavioral gaps. - **Step 8** through **Step 12** finish the preview, write, and review flow. If a narrower branch explicitly tells you to skip a later step, follow that branch. Otherwise, keep this order. --- ## Stage 1 — Detect the Starting State Complete Stage 1 before you ask any interview question or enter any mode-specific path. - Do not silently pick a mode. - Always tell the user which mode you detected. - Confirm before you continue. ### Step 1: Check for a monorepo root instruction file Before you assess 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` or `CLAUDE.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 or CLAUDE.md] --> <!-- Only package-specific overrides and additions are defined here. --> ``` 4. During the interview, at the start of each turn, state what the root file already covers for that section before asking any questions: > "The root `AGENTS.md` or `CLAUDE.md` defines [summary of this section's content]. 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 is missing or different. ### Step 2: Check for related documents After Step 1 and before local file-state detection, check for canonical companion documents that either: - help enforce the behavior-layer boundary, or - belong in the final `## Related Documentation` section. Check these companion documents in order: 1. Check for `openspec/config.yml` or `openspec/config.yaml`. - If either file exists, read it to understand the project's stack and patterns. - Note its existence for the `## Related Documentation` section. - Announce: "Found `openspec/config.yml` or `openspec/config.yaml` — I'll use it to maintain the behavior/project-DNA boundary." 2. Check for `ARCHITECTURE.md`. - If it exists, read it to understand the system structure. - Note its existence for the `## Related Documentation` section. - Announce: "Found `ARCHITECTURE.md` — I'll use it when behavior guidance depends on system structure." 3. Check for other canonical companion documents, especially `CONSTRAINTS.md`, `EPISTEMIC-MAP.md`, and `JARGON.md`. - If one exists, read it only when the document is likely to materially affect behavior guidance, approval boundaries, or agent-facing terminology. - Note any that exist for the final `## Related Documentation` section. Apply these limits during this check: - Do not turn this step into a broad handbook scan. - Detect canonical companion documents. Do not absorb their full contents into `AGENTS.md`. - Read only what is needed to keep the behavior file accurate, scoped, and well-linked. ### Step 3: Detect the local file state Requires: Steps 1 and 2 are complete. Detect the local `AGENTS.md` or `CLAUDE.md` state. Run this check in order: 1. Check whether a local `AGENTS.md` or `CLAUDE.md` exists in the current directory. 2. If neither file exists, select **Mode 1: Create**. 3. If a local file exists, read it before classifying the mode. 4. After you read the file, classify it exactly once: - If it is empty or near-blank, meaning fewer than about 10 meaningful lines, select **Mode 1: Create** with overwrite confirmation. Ask: *"AGENTS.md exists but appears empty — should I populate it from scratch, or preserve any current content?"* - If it contains the canonical template shape from `./assets/template.md`, meaning two or more canonical section headings in recognizably template-based form, select **Mode 3: Refresh**. - If it contains real content in an unrecognized shape, select **Mode 2: Import**. Treat `./assets/template.md` as the canonical structure reference for recognition, refresh, and audit behavior. Use section headings exactly as defined there, preserve the template's canonical order for all required sections, and keep optional headings such as `## Optional review-specific rules` and `## Maintenance guidance` only when the template allows them. Use the diagram below as a quick classification aid. The ordered list above is authoritative. ```text Local `AGENTS.md` or `CLAUDE.md` in current directory? │ ├── No │ └── MODE 1: Create │ Full interview from scratch. │ └── Yes ├── Read the file first └── Then classify: ├── Empty or near-blank (< about 10 meaningful lines) │ └── MODE 1: Create │ Ask: "AGENTS.md exists but appears empty — should I populate it from scratch, or preserve any current content?" ├── Canonical template shape from `./assets/template.md` │ └── MODE 3: Refresh │ Two or more canonical section headings in recognizably template-based form. └── Real content in an unrecognized shape └── MODE 2: Import ``` Done when: the file state and detected mode are explicit. --- ## Stage 2 — Confirm the Operating Path Complete Stage 2 before you start discovery, drift scanning, or any mode-specific interview. ### Step 4: Confirm how to use the existing file Requires: Step 3 is complete. If Step 3 detected **Mode 2**, ask this first: > "Before I start, this file has content that does not follow the canonical template. > Would you like to **start fresh**, treating the existing file as a reference only > *(recommended for an import)*, or **work with the existing file**?" If Step 3 detected **Mode 3**, ask this first: > "Before I start, this file already follows the canonical template. > Would you like to **work with the existing file** *(recommended for a refresh)*, > or **start fresh**, treating it as a reference only?" If the user chooses **start fresh**, switch immediately to **Mode 1: Create**. - Treat the existing file as a read-only reference. - Carry forward any content from the existing file that is still accurate. - Do not silently discard it. - Use the template to control the new file’s top-level structure, not to decide whether existing guidance may remain. - If existing guidance passes the Final Inclusion Rule but has no dedicated template heading, place it in the canonical section that governs that behavior. - Do not add a top-level section or discard the guidance only because the template does not name it. - Regenerate the structure from scratch. - Then go to **Step 6a**. If the user chooses **work with the existing file**: - if Step 3 detected **Mode 2**, go to **Step 5a** - if Step 3 detected **Mode 3**, go to **Step 5b** If Step 3 already selected **Mode 1**, skip Step 4 and Step 5. Go directly to **Step 6a**. Done when: the choice between **start fresh** and **work with the existing file** is explicit whenever Mode 2 or Mode 3 was detected. ### Step 5a: Choose the Mode 2 branch Requires: Step 4 routed here from **Mode 2**. Present these three options before you modify or synthesize anything: > "This AGENTS.md has existing content with a structure I don't recognize. > 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 a canonical > companion document 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 append a template-aligned > `AGENTS.md` block 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." Branch routing: - If the user chooses **(a)**, go to **Step 6b**. - If the user chooses **(b)**, go to **Step 6c**. - If the user chooses **(c)**, go to **Step 6d**. - Do not start any branch until the user has chosen one. Done when: the Mode 2 branch is explicit. ### Step 5b: Choose the Mode 3 refresh path Requires: Step 4 routed here from **Mode 3**. Only after the Mode 3 intent gate is satisfied, choose exactly one refresh path: - **Targeted refresh** — use this when the request is already within this skill's boundary and is clearly bounded, such as: - one known contradiction to fix - one section to update from newly confirmed evidence - one outdated rule to remove or soften - one narrow addition that belongs in an existing section - one wrapper or conversion update where the surrounding structure is unchanged - **Full refresh** — use this when the request is broad, the file may have drifted in several places, or the narrow update reveals a contradiction, cross-section dependency, or inconsistency that requires broader review. Branch routing: - If the request qualifies for targeted refresh, go to **Step 6e**. - Otherwise, go to **Step 6f**. Done when: the Mode 3 refresh path is explicit before refresh analysis begins. --- ## Stage 3 — Run the Selected Mode Playbook Run exactly one Step 6 branch. ### Shared interview block for interview-based paths Use the interview only after Stages 1 and 2 are complete. Run it conversationally. Do not dump all questions at once. Group questions into natural topic turns that map directly to the canonical template in `./assets/template.md`. That template is the source of truth for section names, section order, required-versus-optional sections, placeholder handling, and default scaffolding. If the user describes a workflow, infer related behavioral constraints and confirm them instead of asking again. Keep questions proportional to the request size. Do not ask for information that strong repository evidence already answers. Ask only for material that belongs in the template. Do not invent extra AGENTS.md sections to hold answers the template does not define. If a topic is optional in the template, confirm whether it should be kept, adapted, or omitted based on what `./assets/template.md` allows. When consolidating answers across turns, map them back into the exact canonical sections defined in `./assets/template.md`. **Turn 1 — What to optimize for** - What durable priorities should the agent optimize for in this repository? *(Examples: follow repo workflows instead of guessing, prefer small scoped changes, make work traceable, stay aligned with existing patterns.)* - Are there repository-specific priorities that materially affect agent behavior? - Should the agent emphasize simplicity, speed, safety, reviewability, or some other standing priority? **Turn 2 — How to communicate** - How should the agent communicate? *(Examples: concise, expository, conversational, adaptive)* - Should the agent explain its reasoning, or just act? - When making changes, are there required reporting expectations beyond what the template already says? *(Examples: show diffs, show full files, inline comments, separate explanation block?)* - How should the agent handle missing information or uncertainty? *(Examples: state assumptions and proceed narrowly, always aske bfore proceeding, ask for scope-changing uncertainty only?)* **Turn 3 — How to work** - Before making changes, what must the agent read, confirm, or state first? - While making changes, are there standing workflow expectations beyond the template defaults? - Before completing a task, what verification, scope checks, or safety checks must always happen? - If the repo uses OpenSpec or another spec-driven workflow, capture the behavior here only as durable agent workflow guidance, and link to canonical docs for deeper process details. **Turn 4 — Repository-specific commands and entry points** - What commands should the agent prefer for setup, build, test, lint/format, and task running? - Are there path conventions, package-manager rules, or command invocation patterns that are easy to get wrong? - Are there any commands the agent should avoid in favor of specific repo entry points? **Turn 5 — Decision Heuristics** - When should the agent ask vs. proceed autonomously? *Good prompts: "deleting files", "changing public APIs", "modifying migrations", "adding new dependencies".* - If scope grows mid-task, what is the default action? - If evidence is incomplete or multiple implementations are valid, should the agent choose, ask, or present tradeoffs? **Turn 6 — Approval and safety boundaries** - What actions require approval before proceeding because they are risky, costly, hard to reverse, or affect shared systems? - What hard safety boundaries must always be preserved? *Examples: never commit secrets, ask before schema or migration changes, do not act on production without approval.* - Are there sandboxing, remote-environment, publishing, or externally relied-on information boundaries that should be documented here? **Turn 7 — Quality bar for finished work** - What checks are required before work is considered done? - What evidence should the agent report back? - Are there review or handoff expectations specific to this repo? **Turn 8 — Optional review-specific rules, related documentation, and maintenance guidance** - Does this repository use `AGENTS.md` to guide code review behavior strongly enough to keep `## Optional review-specific rules`, or should that optional section be omitted? - Which canonical documents should appear in `## Related Documentation`, if they actually exist? - Is there repository-specific maintenance guidance to add under `## Maintenance guidance`, or should the template defaults stand as written? ### Shared smart-defaults block for interview-based paths Use Smart Defaults only to reduce avoidable interview load after you have already checked for stronger evidence. A Smart Default is a confirmation prompt, not standing policy. Use one only when: - the relevant template field still needs an answer - direct user input does not already answer it - repository evidence does not already answer it - the default helps the user confirm a likely convention faster than asking from scratch Do not use Smart Defaults to introduce new policy, broaden scope, or carry ecosystem assumptions into the generated file. Apply these rules: 1. **Stronger evidence wins first.** If direct user input, repository evidence, the canonical template, or still-consistent existing guidance already answers the field, do not offer a default for that field. 2. **Offer defaults as prompts, not conclusions.** Phrase the default as something to confirm, reject, or refine. Do not present it as adopted policy. 3. **Keep the default proportional to the evidence.** Prefer narrow prompts that test one likely convention at a time. Do not turn one repository signal into a broad workflow bundle. 4. **Keep examples illustrative.** The example prompts below show common patterns. They are not an exhaustive checklist and they are not required in every run. 5. **Do not preserve a default after the user or repository disproves it.** Replace it with the stronger answer, or leave `<!-- TODO: fill in -->` if the field still cannot be confirmed. #### Example prompt patterns Use patterns like these only when they match the repository evidence already gathered. **If the repo appears to use a PNPM monorepo:** - "I found signs of a PNPM workspace. Should I treat workspace-root and package-scoped dependency changes differently in the generated guidance?" - "Do you want the agent to prefer workspace-aware task commands when package selection matters?" **If the repo appears to use GitHub Actions for CI:** - "I found GitHub Actions workflows. Should the generated guidance require the agent to report or wait on specific CI checks before considering work complete?" - "Are there required status checks or PR gates that should appear in the file?" **If the repo appears to use Conventional Commits:** - "I found commit-convention signals. Should the file tell the agent to use Conventional Commits, and are there repo-specific types or breaking-change rules to note?" - "Are scope usage or footer conventions important enough to make explicit?" **If the repo appears to use OpenSpec or another spec-driven workflow:** - "I found signs of a spec-driven workflow. Which parts of that workflow are durable agent behavior that belong in `AGENTS.md`, and which parts should stay in canonical project documentation?" - "For non-trivial changes, should the agent start with the documented spec workflow before implementation?" Done when: likely conventions are confirmed, rejected, or replaced with stronger evidence, and no unconfirmed default has been carried into standing guidance. ### Step 6a: Run Mode 1 — Create Use this branch for a fresh repo, an empty or near-blank file that the user wants populated, or an explicit **start fresh** choice. Run this branch in order: 1. Run the **Shared interview block for interview-based paths**. 2. Run the **Shared smart-defaults block for interview-based paths**.