accelint-onboard-openspec

What this skill does

# Onboard OpenSpec

Guide the user through a conversational interview to produce a complete,
project-specific `openspec/config.yaml` configured for the QRSPI methodology.

## NEVER Do When Onboarding OpenSpec

- **NEVER run codebase inference serially when subagents are available** — Phase 3 spawns parallel subagents for different discovery domains. Serial scanning wastes time on codebases with many config files spread across directories. Spawn all 4 discovery agents simultaneously.

## Companion Skill

This skill produces the **project DNA layer** of the agent instruction stack:
structural facts about what the project is. It is the companion to the
`accelint-onboard-agents` skill, which produces the **behavior layer** (`AGENTS.md` /
`CLAUDE.md`): how the agent acts, communicates, and makes decisions.

If during this interview the user volunteers behavioral content (commit
conventions, workflow steps, decision heuristics, tool preferences), acknowledge
it and redirect: *"That's behavioral — it belongs in AGENTS.md. I'll note it
here for reference, but the `accelint-onboard-agents` skill is the right place to
capture it."* Do not write behavioral content into `config.yaml`.

```
AGENTS.md / CLAUDE.md  → accelint-onboard-agents skill  → HOW the agent behaves
openspec/config.yaml   → this skill             → WHAT the project is
```

---

## Mental Model

The config has two jobs:
1. **`context:`** — Objective facts about the codebase injected into every AI
   artifact. Think of it as the "DNA" that makes AI suggestions feel native to
   the project. Facts only, no opinions.
2. **`rules:`** — Per-artifact checkpoints (proposal / design / tasks / spec)
   that encode the team's quality bar.

## Phases

### Phase 0 — File State Detection

Before any interview question is asked, check whether `openspec/config.yaml`
exists and assess its state. Never silently pick a mode — always announce the
detected mode to the user and confirm before proceeding.

**Step 1 — Check for Related Documents**

Before detecting config.yaml state, check for related onboarding documents:

1. **Check for ARCHITECTURE.md**
   - If exists: Read it to understand deployment and infrastructure
   - Use it to pre-fill answers for Turn 2 (infrastructure/deployment questions)
   - Note its existence for the "Related Documentation" section
   - Announce: "Found ARCHITECTURE.md — I'll use it to avoid asking questions
     about deployment that are already documented."

Note: AGENTS.md and README.md should NOT influence config.yml generation since
they contain behavioral/usage info, not project DNA.

**Step 2 — Detect Config State**

After checking related documents, assess the config file state:

```
Does openspec/config.yaml exist?
│
├── No → MODE 1: Create
│         Full interview from scratch.
│
└── Yes → Read the file, then assess:
          │
          ├── Empty or near-blank (schema: line only, no context/rules)?
          │     → MODE 1: Create (with overwrite confirmation)
          │       Ask: "config.yaml exists but appears empty — should I
          │       populate it from scratch, or preserve any current content?"
          │
          ├── Contains recognised fields?
          │   (context: block present, rules: block with known artifact keys)
          │     → MODE 3: Refresh
          │       Abbreviated interview covering only detected drift and
          │       unresolved # TODO: fill in markers.
          │
          └── Contains real content in an unrecognised shape?
                → MODE 2: Import
                  Present three options (A / B / C) before proceeding.
```

**Recognised shape** = file is valid YAML with at least a `context:` key
whose value is a non-empty string, or a `rules:` key with at least one
of the known artifact IDs (`proposal`, `specs`, `design`, `tasks`).

---

#### Mode 1: Create

Run the full Phase 1 → Phase 2 → Phase 3 → Phase 4 interview. This is the
happy path for a fresh repo.

---

#### Mode 2: Import

The file has real content that was not generated by this skill. Present the
user with three options before touching anything:

> "This `config.yaml` 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 the
> `context:` / `rules:` schema, flag any material that belongs in `AGENTS.md`
> instead (workflow steps, commit conventions, tool preferences), 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 the skill's `context:`
> and `rules:` sections alongside 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 existing content onto `context:` sub-sections and `rules:` artifact
   keys where possible.
3. Flag any content that violates the separation-of-concerns boundary
   (e.g., commit conventions, workflow steps, tool preferences, agent
   decision heuristics) — these belong in `AGENTS.md`. For each violation,
   ask: *"This looks behavioral — it belongs in AGENTS.md. Should I move it
   there and remove it from config.yaml?"*
4. Run a targeted interview covering only the gaps (context sub-sections
   with no existing coverage; artifact keys with no rules).
5. Show a merged preview before writing. 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 write the generated `context:`
and `rules:` blocks alongside existing content. Add a comment at the top:
`# Sections below added by accelint-onboard-openspec 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

The file matches the skill's expected schema — 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 |
   |--------|---------------|
   | Runtime / Node version changed | `.nvmrc`, `.node-version`, `Dockerfile` |
   | New packages / frameworks added | `package.json` deps, workspace roots |
   | TypeScript config tightened | `tsconfig.json` — new `strict*` flags |
   | New packages in monorepo | `pnpm-workspace.yaml`, `turbo.json` |
   | Build tooling changed | `vite.config.*`, `tsup.config.*` |
   | CI/CD workflows added | `.github/workflows/` |
   | New domain concepts | New top-level directories, new entity types in source |
   | Anti-patterns deprecated | `@deprecated` tags, `// TODO: replace` comments added |

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] context 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 only the changed sections in the
   preview before writing. Do not re-emit unchanged sections.

---

### Phase 1 — Discovery Interview

Run the interview conversationally. Don't dump all questions at once. Group them
into natural topic turns. If the user mentions a stack, infer related tooling and
confirm rather than asking again.

**Turn 1 — Project Identity**
- What is the project name and its primary purpose?
- Monorepo, single package, or something else? If monorepo, what workspaces?
- Build system / task orchestration? (Turbo, Nx, Make, npm scripts, Makefile…)
- Package manager and any private registr