accelint-onboard-openspec

# 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. **Extract external findings** — check if the invoking prompt includes a `findings:` list: - Parse the prompt for a `findings:` section (a bulleted list of factual statements) - Each finding is phrased as something already known to be true, never as an instruction - Example: "config.yaml's Anti-Patterns section says to avoid polling, but two archived changes chose polling for stated reasons" - Store these findings for merging in step 4 2. **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 | 3. **Unresolved TODOs** — find all `# TODO: fill in` markers left from the previous run and surface them as targeted questions. 4. **Merge and announce all findings** before asking anything: - Combine external findings (from step 1) with drift findings (from step 2) and TODOs (from step 3) - Present the merged list to the user: > "I found [N] external findings, [M] context sections that may have drifted, and [P] unresolved TODOs. > I'll only ask about those — the rest looks current." - If external findings exist, note their source (e.g., "from completed OpenSpec change") 5. 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 registries? (npm, pnpm, yarn, bun…) **Turn 2 — Tech Stack** *(ask as a grouped block, not one by one)* - Runtime and version (Node.js 20, Bun 1.x, Python 3.12, etc.) - Language + config (TypeScript strict? `exactOptionalPropertyTypes`? Python type hints?) - Framework(s) and version (React 18, Next.js 14, Express, FastAPI, etc.) - Key domain libraries (Deck.gl, Apache Arrow, Prisma, SQLAlchemy, etc.) - Data layer (Postgres, MongoDB, DynamoDB, ORM/query builder, data formats) - Testing setup (Vitest, Jest, Pytest, testing-library, Playwright, etc.) - Linting / formatting (ESLint, Biome, Prettier, Black, Ruff, etc.) - Build tools (Vite, tsup, esbuild, Webpack, etc.) - CI/CD (GitHub Actions, CircleCI, etc.) - Versioning approach (Changesets, standard-version, conventional commits, etc.) **Turn 3 — Architecture** - How is the codebase organised? (feature-based, layer-based, domain-driven?) - Where does shared/utility code live? - Any path aliases? (`@/`, `~/`, `src/`, `#lib/`, etc.) - Design patterns commonly in use? (factory, repository, observer, CQRS, etc.) **Turn 4 — Domain Concepts** - What are the 3–5 most important domain entities? *Example prompt: "For a mapping app this might be Layer, Source, Viewport, Feature, Style."* - Any domain-specific terminology the AI should know? - Any specialised concepts with non-obvious meanings in this codebase? *Example: "orchestration" means something specific to us — it's the runtime layer that merges style with data, not a general workflow term.* **Turn 5 — Performance** - Any concrete performance targets? (p95 < 200 ms, 60 fps, < 50 MB heap, etc.) - Known hot paths or performance-critical areas? - Memory or bundle-size constraints? **Turn 6 — Code Patterns** - Export style: named exports, default exports, or mixed? - Naming conventions: files, variables, functions, constants? *Example: "kebab-case files, camelCase vars, SCREAMING_SNAKE_CASE for constants, PascalCase for types."* - Error handling: throw, `Result<T,E>`, error boundaries, something else? - Testing structure: `describe/it`, `test/expect`, AAA pattern? - Test file location: co-located with source or a separate `__tests__/` tree? - Fixture / factory approach for test data? > **Note:** Commit message convention is a workflow procedure — it belongs in > `AGENTS.md`, not here. If the user raises it now, capture it mentally and > surface it in the `accelint-onboard-agents` skill. Do not add it to `config.yaml`. **Turn 7 — Anti-Patterns** - Any patterns explicitly banned in code review? - Deprecated patterns still in the codebase that new code should NOT emulate? - Known performance traps specific to this stack? **Turn 8 — Proposal Rules** What does YOUR team require in a proposal? Good prompts: - "Do you need proposals to call out database migration impact?" - "Do you need proposals to flag API breaking changes?" - "Any security review checklist items?" **Turn 9 — Design Rules** Project-specific design concerns to encode? Good prompts: - "Docker / Kubernetes resource changes to document?" - "Performance implications section required?" - "Specific architecture diagram style (ASCII, Mermaid)?" **Turn 10 — Task Rules** - How do you tag tasks by package or module? *Example: `[PKG:auth]`, `[MODULE:pipeline]`, GitHub labels…* - Rollback plan required for database changes? - Deployment-specific test gates (smoke tests, canary checks)? --- ### Phase 2 — Smart Defaults After each stack answer, surface relevant conventions to confirm. Use these examples as a pattern; extend to other stacks as appropriate. **Next.js + TypeScript + Tailwind → suggest confirming:** - App Router vs Pages Router and which patterns apply - Server Component vs Client Component boundary rules - `"use client"` directive placement convention - API route organisation (`app/api/` vs `pages/api/`) **React + Vitest + testing-library → suggest confirming:** - `userEvent` over `fireEvent` preference - `screen` query priority (role > label > testid) - `render` wrapper for providers **Python + FastAPI → suggest confirming:** - Pydantic v1 vs v2 (different field-validator syntax) - Dependency injection for DB sessions (`Depends`) - Alembic migration workflow - `lifespan` vs `startup`/`shutdown` event hooks **Node.js + Prisma → suggest confirming:** - `prisma.$transaction` patterns - Soft-delete vs hard-delete convention - Migration naming convention --- ### Phase 3 — Parallel Codebase Inference After the interview, spawn parallel discovery subagents to fill remaining config gaps. All config sections are load-bearing — a missing field degrades every downstream AI artifact, so inference is always preferable to omission. Spawn discovery subagents in parallel — don't scan serially. Each agent focuses on one inference domain and returns structured findings. Wait for all agents to complete, then merge results before Phase 4. **Spawn these agents simultaneously:** **Agent A — Stack & Build Tooling** - Runtime / Node version: `.nvmrc`, `.node-version`, `package.json#engines`, `Dockerfile` - TypeScript config: `tsconfig.json` (compilerOptions flags, paths aliases) - Package manager: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb` - Monorepo workspaces: `package.json#workspaces`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json` - Build tools: `vite.config.*`, `webpack.config.*`, `tsup.config.*`, `esbuild` scripts - Return: runtime version, TS config flags, package manager, workspace list, build tools **Agent B — Testing & Code Quality** - Test framework: `vitest.config.*`, `jest.config.*`, `pytest.ini`, `pyproject.toml#tool.pytest` - Linting / formatting: `.eslintrc*`, `biome.json`, `.prettierrc*`, `ruff.toml` - Test structure: Sample test files — describe/it nesting depth, file location relative to source - Test file type checking: CI scripts, package.json — check if `tsc --noEmit` runs on `*.test.ts` files - Property-based testing: Check for `fast-check` in dependencies - Vitest mock cleanup: `vitest.config.ts` — check for `clearMocks`, `mockReset`, `restoreMocks` - Return: test framework, code quality tools, test structure patterns, type checking config **Agent C — Architecture & Code Patterns** - Architecture organisation: Directory tree of `src/` or workspace roots — infer feature-based vs layer-based - Path aliases: `tsconfig.json#compilerOptions.paths`, `vite.config#resolve.alias` - Design patterns: Sample source files — look for factory functions, repository objects, observer hooks - Export style: Sample 3–5 source files; tally named vs default exports - Naming conventions: Sample file names, exported identifiers; describe what you observe - Error handling: Grep for `throw`, `Result`, `Either`, `tryCatch`, error boundary components - TypeScript baseline patterns: If `tsconfig.json` exists, flag that TS/JS baseline patterns should be included - Return: architecture style, path aliases, design patterns, export conventions, naming patterns, error handling approach **Agent D — CI/CD & Versioning** - CI/CD: `.github/workflows/`, `.circleci/`, `Jenkinsfile` - Versioning: `.changeset/`, `CHANGELOG.md`, `commitlint.config.*`, `.releaserc*` - Anti-patterns: `eslint` rule overrides marked `off` or `warn`, comments like `// TODO: replace`, `@deprecated` - Return: CI/CD platform, versioning approach, documented anti-patterns **After all agents complete:** merge their findings into a unified inference map. Tag each field as `INFERRED [source]` or `UNKNOWN`. Fields tagged `UNKNOWN` should be marked as `# TODO: fill in` in the config preview. **For each field resolved via inference**, note the source in the preview with a trailing comment, e.g.: ```yaml - Runtime: Node.js 20 LTS # inferred from .nvmrc - Language: TypeScript 5.4, strict, exactOptionalPropertyTypes # inferred from tsconfig.json ``` **If a field genuinely cannot be inferred** (e.g., performance targets, domain concepts, team-specific rules), mark it with `# TODO: fill in` rather than omitting it. The user can resolve these after reviewing the preview. Do not silently drop a section — an explicit TODO is a prompt to act; an absent section is an invisible gap. --- ### Phase 4 — Generation 1. **Show a labeled preview** of the full config before writing anything. Inferred values carry their source comment; unresolved fields carry `# TODO: fill in`. This gives the user a complete picture of confidence level across every field. 2. Ask: *"Does this look right? Any sections to correct or expand before I write the file?"* 3. After confirmation, write to `openspec/config.yaml` (create directory if needed), **stripping the inference source comments** — they are for review only, not the final file. **For the Related Documentation section:** only include links to files that actually exist in the repository. Check for each file