accelint-onboard-agents

What this skill does

# 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