Onboard OpenSpec

openspec/config.yaml

Companion Skill

accelint-onboard-agents

AGENTS.md

CLAUDE.md

accelint-onboard-agents

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

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

openspec/config.yaml

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.

context:

rules:

proposal

specs

design

tasks

Mode 1: Create

Mode 2: Import

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

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

   .

context:

rules:

# Sections below added by accelint-onboard-openspec skill

Mode 3: Refresh

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

• 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…)

• 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.)

• 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.)

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

• 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?

• Export style: named exports, default exports, or mixed?
• Naming conventions: files, variables, functions, constants? Example: "kebab-case files, camelCase vars, SCREAMING_SNAKE_CASE for enums, 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

.

• 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?

• "Do you need proposals to call out database migration impact?"
• "Do you need proposals to flag API breaking changes?"
• "Any security review checklist items?"

• "Docker / Kubernetes resource changes to document?"
• "Performance implications section required?"
• "Specific architecture diagram style (ASCII, Mermaid)?"

• 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

• 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/

  )

• userEvent

  over

  fireEvent

  preference

• screen

  query priority (role > label > testid)

• render

  wrapper for providers

• Pydantic v1 vs v2 (different field-validator syntax)
• Dependency injection for DB sessions (

  Depends

  )
• Alembic migration workflow

• lifespan

  vs

  startup

  /

  shutdown

  event hooks

• prisma.$transaction

  patterns
• Soft-delete vs hard-delete convention
• Migration naming convention

Phase 3 — Codebase Inference (fill gaps before generating)

.nvmrc

.node-version

package.json#engines

Dockerfile

tsconfig.json

package-lock.json

yarn.lock

pnpm-lock.yaml

bun.lockb

package.json#workspaces

pnpm-workspace.yaml

turbo.json

nx.json

vite.config.*

webpack.config.*

tsup.config.*

esbuild

package.json

vitest.config.*

jest.config.*

pytest.ini

pyproject.toml#tool.pytest

.eslintrc*

biome.json

.prettierrc*

ruff.toml

.github/workflows/

.circleci/

Jenkinsfile

.changeset/

CHANGELOG.md

commitlint.config.*

.releaserc*

tsconfig.json#compilerOptions.paths

vite.config#resolve.alias

src/

throw

Result

Either

tryCatch

eslint

off

warn

// TODO: replace

@deprecated

- Runtime: Node.js 20 LTS   # inferred from .nvmrc
- Language: TypeScript 5.4, strict, exactOptionalPropertyTypes   # inferred from tsconfig.json

# TODO: fill in

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.
4. Print a brief summary of what was configured, what was inferred vs answered directly, and which

   # TODO

   fields still need human input.

Config Template

[placeholder]

# TODO: fill in

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]

  # ═══════════════════════════════════════════════════════════════════════════
  # 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:    [enum pattern or constant object pattern]

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

  ## Testing Patterns
  - Structure:    [describe/it nesting convention]
  - File location:[co-located / __tests__ / other]
  - Fixtures:     [factory functions / fixture files / inline data]
  - Assertions:   [preferred assertion style]
  - 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
  # ═══════════════════════════════════════════════════════════════════════════

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

# ═══════════════════════════════════════════════════════════════════════════
# 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]

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.