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. Drift detection — scan the codebase for changes since the file was last updated:

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 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.:

- 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 (ARCHITECTURE.md, AGENTS.md/CLAUDE.md, README.md) before including its link. 4. Validate the generated YAML — after writing, read the file back and verify:

• No tabs (YAML requires spaces for indentation)
• Values with special characters are properly quoted
• No syntax errors (unmatched brackets, quotes, etc.)
• The file can be conceptually parsed as valid YAML

If validation reveals issues, fix them immediately and rewrite the file. 5. Print a brief summary of what was configured, what was inferred vs answered directly, and which # TODO fields still need human input.

---

YAML Generation Safety Rules

CRITICAL: YAML syntax is strict about special characters. Follow these rules when generating config.yaml to avoid syntax errors:

Quoting Requirements

Rule: Values that start with special YAML characters need quoting.

Special characters: |, >, ", ', (, ), [, ], {, }, *, &, !, %, @, ` ``

Examples:

# Parentheses at start of value
❌ description: (internal) auth module     # Syntax error
✅ description: "(internal) auth module"   # Quoted

# Square brackets (looks like YAML list syntax)
❌ tag: [PKG:auth]                         # YAML thinks it's a list
✅ tag: "[PKG:auth]"                       # Quoted string

# Pipe character (YAML thinks it's block scalar)
❌ pattern: some|other                     # Syntax error
✅ pattern: "some|other"                   # Quoted

# Colon in value (YAML thinks it's a nested key)
❌ note: Time: 5pm                         # Syntax error
✅ note: "Time: 5pm"                       # Quoted

# Value containing quotes - escape with opposite quote type
✅ command: 'npm run "test:unit"'          # Single quotes protect doubles
✅ command: "npm run 'test:unit'"          # Double quotes protect singles

Multi-line String Handling

Use block scalar indicators for multi-line content:

# Literal block (preserves newlines) - preferred for context field
context: |
  Line 1
  Line 2
  Line 3

# Folded block (folds newlines into spaces) - rarely needed
description: >
  This is a long
  description that
  flows together.

Indentation Rules

• Use spaces only — never tabs
• Consistent indent — typically 2 spaces per level
• Block scalars — content inside | or > must be indented relative to the key

Rules for List Values

# Simple list items - no quotes needed for plain text
rules:
  proposal:
    - Keep proposals under 100 lines
    - Include scope boundaries

# List items with special chars - quote them
rules:
  tasks:
    - "Tag with [PKG:name] format"        # Quotes protect [ and ]
    - 'Use "Test:" prefix for validation' # Single quotes protect inner "

Validation Checklist

After generating the config, mentally verify: 1. No bare (, ), |, ", ' immediately after colons (unless using | or > for multiline) 2. No tab characters anywhere in the file 3. Consistent 2-space indentation throughout 4. All list items (-) aligned at the same indent level within their parent 5. Quoted strings use matching quote types

If any of these rules are violated, the YAML will fail to parse.

---

Config Template

Use this exact structure. Fill every [placeholder] with content from the interview or codebase inference. If a field cannot be resolved by either means, replace its placeholder with # TODO: fill in — never omit the field. Every section is load-bearing for downstream AI artifact quality.

schema: spec-driven

# Project Context
# Injected into every AI-generated artifact (proposal, design, spec, tasks).
# QRSPI principle: objective research layer — facts only, no opinions.

context: |
  # ═══════════════════════════════════════════════════════════════════════════
  # STACK FACTS
  # ═══════════════════════════════════════════════════════════════════════════

  ## Project Identity
  [project name and one-sentence purpose]
  [repo structure: monorepo / single-package / workspaces list]
  [build system and task orchestration]
  [package manager + registries]

  ## Tech Stack
  - Runtime:            [e.g., Node.js 20 LTS]
  - Language:           [e.g., TypeScript 5.4, strict mode, exactOptionalPropertyTypes]
  - Framework:          [e.g., Next.js 14 App Router]
  - Key Libraries:      [domain-specific dependencies with versions]
  - Data Layer:         [databases, ORMs, data formats, query builders]
  - Testing:            [framework, utilities, coverage tooling]
  - Linting/Formatting: [tools and config files in use]
  - Build Tools:        [bundlers, compilers, transpilers]
  - CI/CD:              [platform and key workflow names]
  - Versioning:         [release strategy and changelog tooling]

  ## Architecture Patterns
  - Organisation: [feature-based / layer-based / domain-driven / other]
  - Shared code:  [path to shared utilities / packages]
  - Path aliases: [list of aliases and their resolved paths]
  - Key patterns: [design patterns in common use]

  ## Domain Concepts
  - [Entity or concept]: [one-line definition]
  - [Entity or concept]: [one-line definition]
  - [Entity or concept]: [one-line definition]

  ## Performance Targets
  - [metric]: [target value and context]

  ### TypeScript/JavaScript Performance (if applicable)
  - Hot paths:    [functions executed >1000 times per interaction or >100 times/sec]
  - Frame budget: [for real-time systems: 60fps = 16.67ms, 120fps = 8.33ms]
  - Constraints:  Bounded iteration (explicit limits on loops/queues), O(n) or better algorithmic complexity

  # ═══════════════════════════════════════════════════════════════════════════
  # PATTERNS TO FOLLOW
  # ═══════════════════════════════════════════════════════════════════════════

  ## Code Patterns
  - Exports:        [named / default / mixed — and when each applies]
  - Naming:         [files, variables, functions, constants, types]
  - Error handling: [throw / Result<T,E> / boundaries / other]
  - Validation:     [approach and library]
  - Constants:      Use `as const` objects, never `enum`
  - Classes:        Prefer functions over classes unless state management required or extending existing class
  - Return values:  Return zero values (empty array, empty string, 0) instead of null/undefined
  - Type safety:    Avoid `any` (use `unknown` or generics); avoid `enum` (use `as const` objects); use `type` over `interface`
  - Immutability:   Prefer `const`, immutable data structures, pure functions
  - Documentation:  Comprehensive JSDoc for all exported code (@param, @returns, @template, @example)
  - Order:          Internal functions, variables and types should be defined before they are used (internal/export types -> internal/export constants -> internal/export functions)

  ## Architecture Patterns
  - [pattern name]: [brief description of how it's used here]

  ## Testing Patterns
  - Pattern:        AAA (Arrange, Act, Assert) with clear boundaries
  - Property-based: (If available) Use `fast-check` for encode/decode pairs, validators, normalizers, pure functions
  - Test scope:     Never test library internals; never export internals to test them; never mock own pure functions
  - Structure:      [describe/it nesting convention]
  - File location:  [co-located / __tests__ / other]
  - Test doubles:   Hierarchy: real implementation > fakes > stubs > spies > mocks
  - Fixtures:       [factory functions / fixture files / inline data]
  - Assertions:     [preferred assertion style]
  - Nesting:        Max 2 levels of describe blocks — use descriptive test names instead
  - Verification:   MUST run `tsc --noEmit` on test files before marking complete
  - Benchmarks:     [approach if any]

  # NOTE: Commit message convention, PR workflow, and tool preferences
  # are behavioral — they belong in AGENTS.md, not here.

  # ═══════════════════════════════════════════════════════════════════════════
  # PATTERNS TO AVOID
  # ═══════════════════════════════════════════════════════════════════════════

  ## Code Anti-Patterns
  - Using `any` instead of `unknown` or generics
  - Using `enum` instead of `as const` objects
  - Using `interface` when `type` works (prefer type)
  - Returning `null`/`undefined` instead of zero values (empty arrays, empty strings, 0, false)
  - Not validating external data with schemas
  - Deep nesting instead of early returns

  - [anti-pattern]: [why it's banned or deprecated]

  ## Performance Anti-Patterns
  - Chaining array methods (`.filter().map().reduce()`) — use single reduce pass
  - Using `Array.includes()` for repeated lookups (use `Set.has()` for O(1) lookups)
  - Recomputing constants inside loops (hoist invariants outside)
  - Unbounded loops or queues (set explicit limits to prevent runaway resource consumption)
  - Placing `try/catch` in hot paths (V8 cannot inline, 3-5x slowdown)

  - [anti-pattern]: [why it's banned or deprecated]

  ## Testing Anti-Patterns
  - Testing library internals (e.g., verifying Array.prototype.map works)
  - Exporting internal functions just to test them
  - Loose assertions in tests (toBeTruthy, toBeDefined)
  - Nested describe blocks >2 levels deep
  - Testing implementation details instead of behavior

  - [anti-pattern]: [why it's banned or deprecated]

  ## Documentation Anti-Patterns
  - Missing JSDoc on exported functions/types
  - Documenting HOW instead of WHAT/WHY in JSDoc
  - Vague comment markers (`// TODO: fix this` instead of `// TODO: Replace with binary search for O(log n)`)

# ═══════════════════════════════════════════════════════════════════════════
# PER-ARTIFACT RULES
# ═══════════════════════════════════════════════════════════════════════════

rules:
  proposal:
    # QRSPI: Scope definition, not a plan.
    - State the requirement or ticket driving this change
    - Define scope boundaries — explicitly list what is OUT of scope
    - Keep under 100 lines (tight and focused)
    [user-specific proposal rules]

  design:
    # QRSPI: The "brain surgery" checkpoint — reviewed before any code is written.
    # Target ~200 lines capturing current state, desired state, open questions.

    # Required sections (in this order):
    - Start with "Current State": what the code does today, key files, entry
      points, relevant data flows
    - "Desired End State": what changes after this work, what stays the same
    - "Patterns to Follow": ONLY if specific files/functions to reference exist
      for this change's domain
    - "Patterns to Avoid": ONLY if specific anti-patterns apply to this change
    - "Open Questions": genuine uncertainties requiring human input. If none,
      state explicitly "No unresolved questions."
    - "Resolved Decisions": numbered (Decision 1, Decision 2…) with Choice,
      Rationale, Alternatives Considered

    # Technical depth:
    - Use ASCII diagrams for data flows, state machines, architecture
    - Call out performance implications where relevant
    [user-specific design rules]

    # Constraints:
    - Keep under 250 lines total

  tasks:
    # QRSPI: Vertical slicing for early failure detection.

    # Vertical slicing (strong preference):
    - Order as vertical slices — each task delivers a testable end-to-end path
    - Do NOT group by architectural layer unless explicitly justified
    - Horizontal (layer-by-layer) only for pure infrastructure; include
      justification in the task description when used
    - Each task MUST include an explicit "Test:" line describing what to verify
      before proceeding to the next task
    - Prefer 3–5 major slices; more than 5 suggests scope is too large

    # Granularity:
    - Max 2 hours per task; break larger work into subtasks
    [user-specific task tagging, e.g., [PKG:name] or [MODULE:name]]
    - Call out inter-task dependencies explicitly
    [user-specific rollback requirements]
    [user-specific deployment test gates]

  spec:
    - Use Given/When/Then for behaviour specifications
    - Include concrete example data relevant to the domain
    - Document edge cases explicitly
    [user-specific spec rules]

# ═══════════════════════════════════════════════════════════════════════════
# RELATED DOCUMENTATION
# ═══════════════════════════════════════════════════════════════════════════
# Include only files that actually exist in the repository:
# - ARCHITECTURE.md: System overview, deployment, component interactions, data flows
# - AGENTS.md: Agent behavior rules, workflow procedures, communication style
# - README.md: Installation, quick start, usage guide

---

Interaction Principles

• Conversational, not interrogative. Bundle related questions into a single

turn. Use natural language, not bullet-dump forms.

• Infer and confirm. "You mentioned Vitest — I'll assume you're using

@testing-library/react for component tests; correct?" is better than asking from scratch.

• Examples reduce ambiguity. When asking about naming conventions, give an

example first so the user can pattern-match.

• Iterative. Let the user amend answers. Don't lock them into the first

response.

• Preview before writing. Always show the full generated config and get

explicit confirmation before touching the filesystem.

• Infer before asking, ask before omitting. Always attempt codebase

inference for any unanswered field. If inference fails, surface a # TODO rather than dropping the section. A config with explicit TODOs is actionable; a config with missing sections silently degrades every artifact it drives.

Changelog

[1.3.0] - 2026-05-11

Changed

• CRITICAL PERFORMANCE FIX: Replaced serial codebase inference with parallel sub-agent discovery
• Rationale: Phase 3 now spawns 4 discovery agents simultaneously (Stack & Build, Testing & Quality, Architecture & Patterns, CI/CD & Versioning) instead of scanning config files one-by-one. Dramatically reduces discovery time on large codebases with many config files spread across directories.
• Pattern borrowed from accelint-architecture-doc skill's proven parallel discovery architecture

Added

• Added "NEVER Do" anti-pattern warning about serial scanning when subagents are available
• Created Phase 3 parallel discovery agent specifications:
• Agent A: Stack & Build Tooling
• Agent B: Testing & Code Quality
• Agent C: Architecture & Code Patterns
• Agent D: CI/CD & Versioning

Version

• Bumped from 1.2.0 → 1.3.0

OpenSpec Onboarding Skill

Generates openspec/config.yaml files through a conversational interview. The skill asks questions about your tech stack, architecture, and domain concepts, then runs parallel codebase inference to fill gaps. The output is a complete configuration file for the QRSPI (Question, Research, Spec, Plan, Implement) methodology.

Overview

OpenSpec needs an openspec/config.yaml file that defines project context and per-artifact rules. This skill creates it by:

• Asking targeted questions about tech stack, architecture, domain concepts, and team conventions
• Spawning four discovery agents simultaneously to infer missing details from your codebase
• Detecting whether to create, import, or refresh based on existing file state
• Enforcing YAML quoting rules and validating syntax

The configuration gets injected into every AI-generated proposal, design document, task list, and specification.

When to use

Use this skill when starting a new project with OpenSpec, migrating an existing project to the OpenSpec workflow, updating configuration after tech stack changes, onboarding team members, or refreshing stale configuration.

The skill detects the current state and adapts.

Quick start

Prerequisites

You need Claude Code with agent spawning for parallel inference. A git repository is recommended but not required.

Basic usage

1. Invoke the skill:

   /accelint-onboard-openspec

2. Answer interview questions grouped by topic (project identity, tech stack, architecture, domain concepts, code patterns)

3. Review the generated preview with inferred values and TODO markers

4. Confirm to write openspec/config.yaml to disk

The entire process takes 5-10 minutes depending on project complexity and interview depth.

Configuration modes

The skill has three modes based on file state:

Mode 1: Create

Triggers when: openspec/config.yaml doesn't exist or is empty

Runs a complete interview covering all configuration sections. Questions are grouped into natural conversation turns rather than dumped as a questionnaire.

Outputs a fresh configuration file with all context sections populated.

Mode 2: Import

Triggers when: openspec/config.yaml exists with unrecognized structure

Presents three options:

• (a) Restructure - Map existing content onto QRSPI schema, flag behavioral content for AGENTS.md, run targeted interview to fill gaps
• (b) Append - Run full interview and add new sections alongside existing content
• (c) Dry run - Generate output without writing to filesystem

This protects existing custom configuration while letting you adopt the QRSPI structure.

Mode 3: Refresh

Triggers when: openspec/config.yaml exists with recognized QRSPI schema

Runs an abbreviated interview:

• Drift detection: scans for tech stack changes (new dependencies, updated TypeScript config, new CI workflows)
• Unresolved TODOs: finds # TODO: fill in markers left from previous runs

Only asks about changed areas. Unchanged sections stay untouched.

Interview structure

The interview covers 10 topics:

Questions within each topic are bundled. The skill infers related tooling from stack answers (mention Vitest and it assumes testing-library for React components).

Parallel codebase inference

After the interview, four discovery agents run simultaneously:

Agent A: Stack & Build Tooling

Analyzes:

• Runtime version (.nvmrc, .node-version, package.json#engines)
• TypeScript configuration (tsconfig.json — compiler options, path aliases)
• Package manager (lockfile detection)
• Monorepo workspaces (pnpm-workspace.yaml, turbo.json)
• Build tools (vite.config.*, webpack.config.*)

Agent B: Testing & Code Quality

Analyzes:

• Test framework (vitest.config.*, jest.config.*, pytest.ini)
• Linting and formatting (.eslintrc*, biome.json, .prettierrc*)
• Test structure patterns (describe/it nesting, file location)
• Type checking configuration for test files
• Mock cleanup settings (Vitest)

Agent C: Architecture & Code Patterns

Analyzes:

• Architecture organization (directory tree structure)
• Path aliases (tsconfig.json#paths, vite.config#resolve.alias)
• Design patterns (factory, repository, observer — inferred from source)
• Export style (named vs default — tallied from samples)
• Naming conventions (file names, identifiers)
• Error handling approach (throw, Result, Either, boundaries)

Agent D: CI/CD & Versioning

Analyzes:

• CI/CD platform (.github/workflows/, .circleci/)
• Versioning strategy (.changeset/, commitlint.config.*)
• Anti-patterns (ESLint rule overrides, @deprecated annotations)

All agents run concurrently. The skill merges their findings before showing you the preview.

Configuration schema

The generated openspec/config.yaml has this structure:

schema: spec-driven

context: |
  # Project DNA — injected into every AI artifact
  
  ## Stack Facts
  - Project identity, tech stack, architecture patterns
  - Domain concepts with one-line definitions
  - Performance targets and constraints
  
  ## Patterns to Follow
  - Code patterns (exports, naming, error handling)
  - Architecture patterns
  - Testing patterns with AAA structure
  
  ## Patterns to Avoid
  - Code anti-patterns with rationale
  - Performance anti-patterns
  - Testing anti-patterns

rules:
  proposal:
    - Scope definition checkpoints
    - Out-of-scope boundaries
  
  design:
    - Required sections (Current State, Desired End State, etc.)
    - Technical depth requirements
    - Line limits
  
  tasks:
    - Vertical slicing preference
    - Granularity limits (max 2 hours per task)
    - Test verification requirements
  
  spec:
    - Given/When/Then format
    - Concrete example data
    - Edge case documentation

Every section matters. Missing fields degrade the AI artifacts that use this config. Unresolved fields get marked # TODO: fill in rather than omitted.

YAML safety features

The skill enforces YAML generation rules:

Automatic quoting

Values starting with special characters get quoted:

tag: "[PKG:auth]"           # Square brackets protected
description: "(internal)"    # Parentheses protected
pattern: "some|other"        # Pipe character protected
note: "Time: 5pm"            # Colon in value protected

Block scalar indicators

Multi-line content uses literal block scalars:

context: |
  Line 1
  Line 2
  Line 3

Validation checklist

Before writing, the skill checks:

• No tab characters (YAML needs spaces)
• Quote matching
• Consistent 2-space indentation
• List items aligned at same level
• Special characters quoted where needed

After writing, it reads the file back to verify it's valid YAML.

Smart defaults

The skill suggests stack-specific conventions. Next.js + TypeScript + Tailwind gets questions about App Router vs Pages Router, Server Component boundaries, and "use client" directive placement. React + Vitest assumes userEvent over fireEvent and role-based queries. Python + FastAPI asks about Pydantic v1 vs v2 and dependency injection. Node.js + Prisma asks about transaction patterns and soft-delete conventions.

This reduces open-ended questions.

Companion skill: accelint-onboard-agent

This skill produces the project DNA layer (structural facts). Its companion accelint-onboard-agent produces the behavior layer (AGENTS.md / CLAUDE.md) covering how the agent acts, communicates, and makes decisions.

If you volunteer behavioral content during the OpenSpec interview (commit conventions, workflow steps, tool preferences), the skill will redirect you:

"That's behavioral - it belongs in AGENTS.md. I'll note it here for reference, but the accelint-onboard-agent skill is where to capture it."

The two skills don't overlap.

Best practices

Answer honestly about unknowns

If you don't know an answer, say so. The skill will try codebase inference. Fields that can't be resolved get marked # TODO: fill in for later.

Review inferred values

The preview labels all inferred values with their source:

- Runtime: Node.js 20 LTS   # inferred from .nvmrc

Check these before confirming. Inference can misread unconventional project structures.

Complete TODOs after generation

If the final config has # TODO: fill in markers, edit the file directly. These usually represent performance targets, team-specific rules, or domain concept definitions that can't be inferred from code.

Use refresh mode for updates

When the tech stack changes, re-run the skill. It detects drift automatically and only asks about changed sections.

Keep context factual

The context: block gets injected into every AI artifact. Put objective facts there, not opinions or procedures. Guidelines like "use semantic tokens" belong in the patterns section, not as prose.

Validation and quality

After generation, the skill:

1. Shows a labeled preview with inference sources and TODO markers 2. Asks for confirmation before writing to disk 3. Writes the file without inference comment clutter 4. Validates the YAML by reading it back 5. Reports what was configured, what was inferred vs answered, and which TODOs remain

This catches syntax errors before they hit disk.

Troubleshooting

"Config file has unrecognized structure"

The skill found content that doesn't match the expected schema. Choose (a) Restructure to migrate to QRSPI format, (b) Append to keep existing structure and add new sections, or (c) Dry run to preview without modifying the file.

"YAML syntax error after generation"

The validation caught a parse error. It's automatically fixed before the final write. If you see this, the safety checks worked.

"Agent spawning failed"

Parallel inference needs Claude Code agent support. Without it, the skill falls back to serial discovery (slower, same output).

"Inference marked too many fields as TODO"

This happens when the project has unconventional structure or the skill can't find expected config files. Edit the file directly to fill TODOs, or re-run with more detailed interview answers.

Version history

See CHANGELOG.md for details.

Current version: 1.3.0

• Parallel sub-agent discovery (4x faster inference)
• Anti-pattern warning for serial scanning
• Performance improvements for large codebases

License

Apache-2.0

Related skills

• accelint-onboard-agent - Generate behavioral configuration (AGENTS.md / CLAUDE.md)
• accelint-readme-writer - Generate README documentation
• accelint-architecture-doc - Create architecture.md with parallel discovery (pattern reference for this skill)