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:
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.
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:
- 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:
- Read the file in full.
- Map existing content onto
context: sub-sections and rules: artifact
keys where possible.
- 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?"
- Run a targeted interview covering only the gaps (context sub-sections
with no existing coverage; artifact keys with no rules).
- 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:
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
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 |
Unresolved TODOs — find all # TODO: fill in markers left from the
previous run and surface them as targeted questions.
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")
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
- 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.
- Ask: "Does this look right? Any sections to correct or expand before I write
the file?"
- 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.
- 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.
- 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:
- No bare
(, ), |, ", ' immediately after colons (unless using | or > for multiline)
- No tab characters anywhere in the file
- Consistent 2-space indentation throughout
- All list items (
-) aligned at the same indent level within their parent
- 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, false) instead of null/undefined
- Leaf functions: Leaf functions (bottom of call stack) should be pure — same inputs produce same outputs, no side effects. Centralize state manipulation in parent/orchestrator functions.
- 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)
- Parameter order: Data-last ordering — place the data being operated on as the final parameter. Enables partial application and composition.
- Composition: Use curried functions when the same first parameter(s) recur across call sites.
## 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.
1---
2name: accelint-onboard-openspec
3description: Interactively onboard a project to OpenSpec by running a structured interview and generating a complete QRSPI-configured openspec/config.yaml. Use this skill whenever a user mentions "openspec config", "config.yaml for openspec", "set up openspec", "onboard to openspec", "generate openspec config", "QRSPI config", or asks how to configure OpenSpec for their project — even if they just say "help me set up openspec" or "I want to use openspec". Always prefer this skill over ad-hoc config generation.
4license: Apache-2.0
5metadata:
6 source: https://skillmd.com/skills/gohypergiant/accelint-onboard-openspec
7 author: accelint
8 version: "1.5.0"
9---
10
11# Onboard OpenSpec
12
13Guide the user through a conversational interview to produce a complete,
14project-specific `openspec/config.yaml` configured for the QRSPI methodology.
15
16## NEVER Do When Onboarding OpenSpec
17
18- **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.
19
20## Companion Skill
21
22This skill produces the **project DNA layer** of the agent instruction stack:
23structural facts about what the project is. It is the companion to the
24`accelint-onboard-agents` skill, which produces the **behavior layer** (`AGENTS.md` /
25`CLAUDE.md`): how the agent acts, communicates, and makes decisions.
26
27If during this interview the user volunteers behavioral content (commit
28conventions, workflow steps, decision heuristics, tool preferences), acknowledge
29it and redirect: *"That's behavioral — it belongs in AGENTS.md. I'll note it
30here for reference, but the `accelint-onboard-agents` skill is the right place to
31capture it."* Do not write behavioral content into `config.yaml`.
32
33```
34AGENTS.md / CLAUDE.md → accelint-onboard-agents skill → HOW the agent behaves
35openspec/config.yaml → this skill → WHAT the project is
36```
37
38---
39
40## Mental Model
41
42The config has two jobs:
431. **`context:`** — Objective facts about the codebase injected into every AI
44 artifact. Think of it as the "DNA" that makes AI suggestions feel native to
45 the project. Facts only, no opinions.
462. **`rules:`** — Per-artifact checkpoints (proposal / design / tasks / spec)
47 that encode the team's quality bar.
48
49## Phases
50
51### Phase 0 — File State Detection
52
53Before any interview question is asked, check whether `openspec/config.yaml`
54exists and assess its state. Never silently pick a mode — always announce the
55detected mode to the user and confirm before proceeding.
56
57**Step 1 — Check for Related Documents**
58
59Before detecting config.yaml state, check for related onboarding documents:
60
611. **Check for ARCHITECTURE.md**
62 - If exists: Read it to understand deployment and infrastructure
63 - Use it to pre-fill answers for Turn 2 (infrastructure/deployment questions)
64 - Note its existence for the "Related Documentation" section
65 - Announce: "Found ARCHITECTURE.md — I'll use it to avoid asking questions
66 about deployment that are already documented."
67
68Note: AGENTS.md and README.md should NOT influence config.yml generation since
69they contain behavioral/usage info, not project DNA.
70
71**Step 2 — Detect Config State**
72
73After checking related documents, assess the config file state:
74
75```
76Does openspec/config.yaml exist?
77│
78├── No → MODE 1: Create
79│ Full interview from scratch.
80│
81└── Yes → Read the file, then assess:
82 │
83 ├── Empty or near-blank (schema: line only, no context/rules)?
84 │ → MODE 1: Create (with overwrite confirmation)
85 │ Ask: "config.yaml exists but appears empty — should I
86 │ populate it from scratch, or preserve any current content?"
87 │
88 ├── Contains recognised fields?
89 │ (context: block present, rules: block with known artifact keys)
90 │ → MODE 3: Refresh
91 │ Abbreviated interview covering only detected drift and
92 │ unresolved # TODO: fill in markers.
93 │
94 └── Contains real content in an unrecognised shape?
95 → MODE 2: Import
96 Present three options (A / B / C) before proceeding.
97```
98
99**Recognised shape** = file is valid YAML with at least a `context:` key
100whose value is a non-empty string, or a `rules:` key with at least one
101of the known artifact IDs (`proposal`, `specs`, `design`, `tasks`).
102
103---
104
105#### Mode 1: Create
106
107Run the full Phase 1 → Phase 2 → Phase 3 → Phase 4 interview. This is the
108happy path for a fresh repo.
109
110---
111
112#### Mode 2: Import
113
114The file has real content that was not generated by this skill. Present the
115user with three options before touching anything:
116
117> "This `config.yaml` has existing content with a structure I don't
118> recognise. How would you like to proceed?
119>
120> **(a) Restructure** — I'll import your existing content, map it onto the
121> `context:` / `rules:` schema, flag any material that belongs in `AGENTS.md`
122> instead (workflow steps, commit conventions, tool preferences), run a
123> targeted interview to fill gaps, and produce a merged file ready to replace
124> the current one.
125>
126> **(b) Append** — I'll run the full interview and add the skill's `context:`
127> and `rules:` sections alongside your existing content without modifying
128> what's already there.
129>
130> **(c) Dry run** — I'll run the full interview and show you exactly what I
131> would have generated, with no changes to the filesystem. Use this to
132> evaluate fit before committing."
133
134**If option (a) is chosen:**
1351. Read the file in full.
1362. Map existing content onto `context:` sub-sections and `rules:` artifact
137 keys where possible.
1383. Flag any content that violates the separation-of-concerns boundary
139 (e.g., commit conventions, workflow steps, tool preferences, agent
140 decision heuristics) — these belong in `AGENTS.md`. For each violation,
141 ask: *"This looks behavioral — it belongs in AGENTS.md. Should I move it
142 there and remove it from config.yaml?"*
1434. Run a targeted interview covering only the gaps (context sub-sections
144 with no existing coverage; artifact keys with no rules).
1455. Show a merged preview before writing. Existing content is labelled
146 `# from existing file`; new content is labelled `# new`.
147
148**If option (b) is chosen:**
149Run the full Phase 1 → Phase 4 interview and write the generated `context:`
150and `rules:` blocks alongside existing content. Add a comment at the top:
151`# Sections below added by accelint-onboard-openspec skill`.
152
153**If option (c) is chosen:**
154Run the full Phase 1 → Phase 4 interview and present the output in the
155conversation. Explicitly state: "No files were changed." Offer to re-run
156as (a) or (b) if the user is satisfied.
157
158---
159
160#### Mode 3: Refresh
161
162The file matches the skill's expected schema — it was likely produced by a
163previous run. Run an abbreviated interview covering only:
164
1651. **Extract external findings** — check if the invoking prompt includes a `findings:` list:
166 - Parse the prompt for a `findings:` section (a bulleted list of factual statements)
167 - Each finding is phrased as something already known to be true, never as an instruction
168 - Example: "config.yaml's Anti-Patterns section says to avoid polling, but two archived changes chose polling for stated reasons"
169 - Store these findings for merging in step 4
170
1712. **Drift detection** — scan the codebase for changes since the file was
172 last updated:
173
174 | Signal | Where to look |
175 |--------|---------------|
176 | Runtime / Node version changed | `.nvmrc`, `.node-version`, `Dockerfile` |
177 | New packages / frameworks added | `package.json` deps, workspace roots |
178 | TypeScript config tightened | `tsconfig.json` — new `strict*` flags |
179 | New packages in monorepo | `pnpm-workspace.yaml`, `turbo.json` |
180 | Build tooling changed | `vite.config.*`, `tsup.config.*` |
181 | CI/CD workflows added | `.github/workflows/` |
182 | New domain concepts | New top-level directories, new entity types in source |
183 | Anti-patterns deprecated | `@deprecated` tags, `// TODO: replace` comments added |
184
1853. **Unresolved TODOs** — find all `# TODO: fill in` markers left from the
186 previous run and surface them as targeted questions.
187
1884. **Merge and announce all findings** before asking anything:
189 - Combine external findings (from step 1) with drift findings (from step 2) and TODOs (from step 3)
190 - Present the merged list to the user:
191 > "I found [N] external findings, [M] context sections that may have drifted, and [P] unresolved TODOs.
192 > I'll only ask about those — the rest looks current."
193 - If external findings exist, note their source (e.g., "from completed OpenSpec change")
194
1955. After the targeted interview, show only the changed sections in the
196 preview before writing. Do not re-emit unchanged sections.
197
198---
199
200### Phase 1 — Discovery Interview
201
202Run the interview conversationally. Don't dump all questions at once. Group them
203into natural topic turns. If the user mentions a stack, infer related tooling and
204confirm rather than asking again.
205
206**Turn 1 — Project Identity**
207- What is the project name and its primary purpose?
208- Monorepo, single package, or something else? If monorepo, what workspaces?
209- Build system / task orchestration? (Turbo, Nx, Make, npm scripts, Makefile…)
210- Package manager and any private registries? (npm, pnpm, yarn, bun…)
211
212**Turn 2 — Tech Stack** *(ask as a grouped block, not one by one)*
213- Runtime and version (Node.js 20, Bun 1.x, Python 3.12, etc.)
214- Language + config (TypeScript strict? `exactOptionalPropertyTypes`? Python type
215 hints?)
216- Framework(s) and version (React 18, Next.js 14, Express, FastAPI, etc.)
217- Key domain libraries (Deck.gl, Apache Arrow, Prisma, SQLAlchemy, etc.)
218- Data layer (Postgres, MongoDB, DynamoDB, ORM/query builder, data formats)
219- Testing setup (Vitest, Jest, Pytest, testing-library, Playwright, etc.)
220- Linting / formatting (ESLint, Biome, Prettier, Black, Ruff, etc.)
221- Build tools (Vite, tsup, esbuild, Webpack, etc.)
222- CI/CD (GitHub Actions, CircleCI, etc.)
223- Versioning approach (Changesets, standard-version, conventional commits, etc.)
224
225**Turn 3 — Architecture**
226- How is the codebase organised? (feature-based, layer-based, domain-driven?)
227- Where does shared/utility code live?
228- Any path aliases? (`@/`, `~/`, `src/`, `#lib/`, etc.)
229- Design patterns commonly in use? (factory, repository, observer, CQRS, etc.)
230
231**Turn 4 — Domain Concepts**
232- What are the 3–5 most important domain entities?
233 *Example prompt: "For a mapping app this might be Layer, Source, Viewport,
234 Feature, Style."*
235- Any domain-specific terminology the AI should know?
236- Any specialised concepts with non-obvious meanings in this codebase?
237 *Example: "orchestration" means something specific to us — it's the runtime
238 layer that merges style with data, not a general workflow term.*
239
240**Turn 5 — Performance**
241- Any concrete performance targets? (p95 < 200 ms, 60 fps, < 50 MB heap, etc.)
242- Known hot paths or performance-critical areas?
243- Memory or bundle-size constraints?
244
245**Turn 6 — Code Patterns**
246- Export style: named exports, default exports, or mixed?
247- Naming conventions: files, variables, functions, constants?
248 *Example: "kebab-case files, camelCase vars, SCREAMING_SNAKE_CASE for
249 constants, PascalCase for types."*
250- Error handling: throw, `Result<T,E>`, error boundaries, something else?
251- Testing structure: `describe/it`, `test/expect`, AAA pattern?
252- Test file location: co-located with source or a separate `__tests__/` tree?
253- Fixture / factory approach for test data?
254
255> **Note:** Commit message convention is a workflow procedure — it belongs in
256> `AGENTS.md`, not here. If the user raises it now, capture it mentally and
257> surface it in the `accelint-onboard-agents` skill. Do not add it to `config.yaml`.
258
259**Turn 7 — Anti-Patterns**
260- Any patterns explicitly banned in code review?
261- Deprecated patterns still in the codebase that new code should NOT emulate?
262- Known performance traps specific to this stack?
263
264**Turn 8 — Proposal Rules**
265What does YOUR team require in a proposal? Good prompts:
266- "Do you need proposals to call out database migration impact?"
267- "Do you need proposals to flag API breaking changes?"
268- "Any security review checklist items?"
269
270**Turn 9 — Design Rules**
271Project-specific design concerns to encode? Good prompts:
272- "Docker / Kubernetes resource changes to document?"
273- "Performance implications section required?"
274- "Specific architecture diagram style (ASCII, Mermaid)?"
275
276**Turn 10 — Task Rules**
277- How do you tag tasks by package or module?
278 *Example: `[PKG:auth]`, `[MODULE:pipeline]`, GitHub labels…*
279- Rollback plan required for database changes?
280- Deployment-specific test gates (smoke tests, canary checks)?
281
282---
283
284### Phase 2 — Smart Defaults
285
286After each stack answer, surface relevant conventions to confirm. Use these
287examples as a pattern; extend to other stacks as appropriate.
288
289**Next.js + TypeScript + Tailwind → suggest confirming:**
290- App Router vs Pages Router and which patterns apply
291- Server Component vs Client Component boundary rules
292- `"use client"` directive placement convention
293- API route organisation (`app/api/` vs `pages/api/`)
294
295**React + Vitest + testing-library → suggest confirming:**
296- `userEvent` over `fireEvent` preference
297- `screen` query priority (role > label > testid)
298- `render` wrapper for providers
299
300**Python + FastAPI → suggest confirming:**
301- Pydantic v1 vs v2 (different field-validator syntax)
302- Dependency injection for DB sessions (`Depends`)
303- Alembic migration workflow
304- `lifespan` vs `startup`/`shutdown` event hooks
305
306**Node.js + Prisma → suggest confirming:**
307- `prisma.$transaction` patterns
308- Soft-delete vs hard-delete convention
309- Migration naming convention
310
311---
312
313### Phase 3 — Parallel Codebase Inference
314
315After the interview, spawn parallel discovery subagents to fill remaining config
316gaps. All config sections are load-bearing — a missing field degrades every
317downstream AI artifact, so inference is always preferable to omission.
318
319Spawn discovery subagents in parallel — don't scan serially. Each agent focuses
320on one inference domain and returns structured findings. Wait for all agents to
321complete, then merge results before Phase 4.
322
323**Spawn these agents simultaneously:**
324
325**Agent A — Stack & Build Tooling**
326- Runtime / Node version: `.nvmrc`, `.node-version`, `package.json#engines`, `Dockerfile`
327- TypeScript config: `tsconfig.json` (compilerOptions flags, paths aliases)
328- Package manager: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`
329- Monorepo workspaces: `package.json#workspaces`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`
330- Build tools: `vite.config.*`, `webpack.config.*`, `tsup.config.*`, `esbuild` scripts
331- Return: runtime version, TS config flags, package manager, workspace list, build tools
332
333**Agent B — Testing & Code Quality**
334- Test framework: `vitest.config.*`, `jest.config.*`, `pytest.ini`, `pyproject.toml#tool.pytest`
335- Linting / formatting: `.eslintrc*`, `biome.json`, `.prettierrc*`, `ruff.toml`
336- Test structure: Sample test files — describe/it nesting depth, file location relative to source
337- Test file type checking: CI scripts, package.json — check if `tsc --noEmit` runs on `*.test.ts` files
338- Property-based testing: Check for `fast-check` in dependencies
339- Vitest mock cleanup: `vitest.config.ts` — check for `clearMocks`, `mockReset`, `restoreMocks`
340- Return: test framework, code quality tools, test structure patterns, type checking config
341
342**Agent C — Architecture & Code Patterns**
343- Architecture organisation: Directory tree of `src/` or workspace roots — infer feature-based vs layer-based
344- Path aliases: `tsconfig.json#compilerOptions.paths`, `vite.config#resolve.alias`
345- Design patterns: Sample source files — look for factory functions, repository objects, observer hooks
346- Export style: Sample 3–5 source files; tally named vs default exports
347- Naming conventions: Sample file names, exported identifiers; describe what you observe
348- Error handling: Grep for `throw`, `Result`, `Either`, `tryCatch`, error boundary components
349- TypeScript baseline patterns: If `tsconfig.json` exists, flag that TS/JS baseline patterns should be included
350- Return: architecture style, path aliases, design patterns, export conventions, naming patterns, error handling approach
351
352**Agent D — CI/CD & Versioning**
353- CI/CD: `.github/workflows/`, `.circleci/`, `Jenkinsfile`
354- Versioning: `.changeset/`, `CHANGELOG.md`, `commitlint.config.*`, `.releaserc*`
355- Anti-patterns: `eslint` rule overrides marked `off` or `warn`, comments like `// TODO: replace`, `@deprecated`
356- Return: CI/CD platform, versioning approach, documented anti-patterns
357
358**After all agents complete:** merge their findings into a unified inference map.
359Tag each field as `INFERRED [source]` or `UNKNOWN`. Fields tagged `UNKNOWN`
360should be marked as `# TODO: fill in` in the config preview.
361
362**For each field resolved via inference**, note the source in the preview with a
363trailing comment, e.g.:
364
365```yaml
366- Runtime: Node.js 20 LTS # inferred from .nvmrc
367- Language: TypeScript 5.4, strict, exactOptionalPropertyTypes # inferred from tsconfig.json
368```
369
370**If a field genuinely cannot be inferred** (e.g., performance targets, domain
371concepts, team-specific rules), mark it with `# TODO: fill in` rather than
372omitting it. The user can resolve these after reviewing the preview. Do not
373silently drop a section — an explicit TODO is a prompt to act; an absent section
374is an invisible gap.
375
376---
377
378### Phase 4 — Generation
379
3801. **Show a labeled preview** of the full config before writing anything.
381 Inferred values carry their source comment; unresolved fields carry
382 `# TODO: fill in`. This gives the user a complete picture of confidence level
383 across every field.
3842. Ask: *"Does this look right? Any sections to correct or expand before I write
385 the file?"*
3863. After confirmation, write to `openspec/config.yaml` (create directory if
387 needed), **stripping the inference source comments** — they are for review
388 only, not the final file. **For the Related Documentation section:** only include
389 links to files that actually exist in the repository. Check for each file
390 (ARCHITECTURE.md, AGENTS.md/CLAUDE.md, README.md) before including its link.
3914. **Validate the generated YAML** — after writing, read the file back and verify:
392 - No tabs (YAML requires spaces for indentation)
393 - Values with special characters are properly quoted
394 - No syntax errors (unmatched brackets, quotes, etc.)
395 - The file can be conceptually parsed as valid YAML
396 If validation reveals issues, fix them immediately and rewrite the file.
3975. Print a brief summary of what was configured, what was inferred vs answered
398 directly, and which `# TODO` fields still need human input.
399
400---
401
402## YAML Generation Safety Rules
403
404**CRITICAL:** YAML syntax is strict about special characters. Follow these rules when generating config.yaml to avoid syntax errors:
405
406### Quoting Requirements
407
408**Rule:** Values that start with special YAML characters need quoting.
409
410Special characters: `|`, `>`, `"`, `'`, `(`, `)`, `[`, `]`, `{`, `}`, `*`, `&`, `!`, `%`, `@`, `` ` ``
411
412**Examples:**
413```yaml
414# Parentheses at start of value
415❌ description: (internal) auth module # Syntax error
416✅ description: "(internal) auth module" # Quoted
417
418# Square brackets (looks like YAML list syntax)
419❌ tag: [PKG:auth] # YAML thinks it's a list
420✅ tag: "[PKG:auth]" # Quoted string
421
422# Pipe character (YAML thinks it's block scalar)
423❌ pattern: some|other # Syntax error
424✅ pattern: "some|other" # Quoted
425
426# Colon in value (YAML thinks it's a nested key)
427❌ note: Time: 5pm # Syntax error
428✅ note: "Time: 5pm" # Quoted
429
430# Value containing quotes - escape with opposite quote type
431✅ command: 'npm run "test:unit"' # Single quotes protect doubles
432✅ command: "npm run 'test:unit'" # Double quotes protect singles
433```
434
435### Multi-line String Handling
436
437Use block scalar indicators for multi-line content:
438
439```yaml
440# Literal block (preserves newlines) - preferred for context field
441context: |
442 Line 1
443 Line 2
444 Line 3
445
446# Folded block (folds newlines into spaces) - rarely needed
447description: >
448 This is a long
449 description that
450 flows together.
451```
452
453### Indentation Rules
454
455- **Use spaces only** — never tabs
456- **Consistent indent** — typically 2 spaces per level
457- **Block scalars** — content inside `|` or `>` must be indented relative to the key
458
459### Rules for List Values
460
461```yaml
462# Simple list items - no quotes needed for plain text
463rules:
464 proposal:
465 - Keep proposals under 100 lines
466 - Include scope boundaries
467
468# List items with special chars - quote them
469rules:
470 tasks:
471 - "Tag with [PKG:name] format" # Quotes protect [ and ]
472 - 'Use "Test:" prefix for validation' # Single quotes protect inner "
473```
474
475### Validation Checklist
476
477After generating the config, mentally verify:
4781. No bare `(`, `)`, `|`, `"`, `'` immediately after colons (unless using `|` or `>` for multiline)
4792. No tab characters anywhere in the file
4803. Consistent 2-space indentation throughout
4814. All list items (`-`) aligned at the same indent level within their parent
4825. Quoted strings use matching quote types
483
484If any of these rules are violated, the YAML will fail to parse.
485
486---
487
488## Config Template
489
490Use this exact structure. Fill every `[placeholder]` with content from the
491interview or codebase inference. If a field cannot be resolved by either means,
492replace its placeholder with `# TODO: fill in` — never omit the field. Every
493section is load-bearing for downstream AI artifact quality.
494
495```yaml
496schema: spec-driven
497
498# Project Context
499# Injected into every AI-generated artifact (proposal, design, spec, tasks).
500# QRSPI principle: objective research layer — facts only, no opinions.
501
502context: |
503 # ═══════════════════════════════════════════════════════════════════════════
504 # STACK FACTS
505 # ═══════════════════════════════════════════════════════════════════════════
506
507 ## Project Identity
508 [project name and one-sentence purpose]
509 [repo structure: monorepo / single-package / workspaces list]
510 [build system and task orchestration]
511 [package manager + registries]
512
513 ## Tech Stack
514 - Runtime: [e.g., Node.js 20 LTS]
515 - Language: [e.g., TypeScript 5.4, strict mode, exactOptionalPropertyTypes]
516 - Framework: [e.g., Next.js 14 App Router]
517 - Key Libraries: [domain-specific dependencies with versions]
518 - Data Layer: [databases, ORMs, data formats, query builders]
519 - Testing: [framework, utilities, coverage tooling]
520 - Linting/Formatting: [tools and config files in use]
521 - Build Tools: [bundlers, compilers, transpilers]
522 - CI/CD: [platform and key workflow names]
523 - Versioning: [release strategy and changelog tooling]
524
525 ## Architecture Patterns
526 - Organisation: [feature-based / layer-based / domain-driven / other]
527 - Shared code: [path to shared utilities / packages]
528 - Path aliases: [list of aliases and their resolved paths]
529 - Key patterns: [design patterns in common use]
530
531 ## Domain Concepts
532 - [Entity or concept]: [one-line definition]
533 - [Entity or concept]: [one-line definition]
534 - [Entity or concept]: [one-line definition]
535
536 ## Performance Targets
537 - [metric]: [target value and context]
538
539 ### TypeScript/JavaScript Performance (if applicable)
540 - Hot paths: [functions executed >1000 times per interaction or >100 times/sec]
541 - Frame budget: [for real-time systems: 60fps = 16.67ms, 120fps = 8.33ms]
542 - Constraints: Bounded iteration (explicit limits on loops/queues), O(n) or better algorithmic complexity
543
544 # ═══════════════════════════════════════════════════════════════════════════
545 # PATTERNS TO FOLLOW
546 # ═══════════════════════════════════════════════════════════════════════════
547
548 ## Code Patterns
549 - Exports: [named / default / mixed — and when each applies]
550 - Naming: [files, variables, functions, constants, types]
551 - Error handling: [throw / Result<T,E> / boundaries / other]
552 - Validation: [approach and library]
553 - Constants: Use `as const` objects, never `enum`
554 - Classes: Prefer functions over classes unless state management required or extending existing class
555 - Return values: Return zero values (empty array, empty string, 0, false) instead of null/undefined
556 - Leaf functions: Leaf functions (bottom of call stack) should be pure — same inputs produce same outputs, no side effects. Centralize state manipulation in parent/orchestrator functions.
557 - Type safety: Avoid `any` (use `unknown` or generics); avoid `enum` (use `as const` objects); use `type` over `interface`
558 - Immutability: Prefer `const`, immutable data structures, pure functions
559 - Documentation: Comprehensive JSDoc for all exported code (@param, @returns, @template, @example)
560 - Order: Internal functions, variables and types should be defined before they are used (internal/export types -> internal/export constants -> internal/export functions)
561 - Parameter order: Data-last ordering — place the data being operated on as the final parameter. Enables partial application and composition.
562 - Composition: Use curried functions when the same first parameter(s) recur across call sites.
563
564 ## Architecture Patterns
565 - [pattern name]: [brief description of how it's used here]
566
567 ## Testing Patterns
568 - Pattern: AAA (Arrange, Act, Assert) with clear boundaries
569 - Property-based: (If available) Use `fast-check` for encode/decode pairs, validators, normalizers, pure functions
570 - Test scope: Never test library internals; never export internals to test them; never mock own pure functions
571 - Structure: [describe/it nesting convention]
572 - File location: [co-located / __tests__ / other]
573 - Test doubles: Hierarchy: real implementation > fakes > stubs > spies > mocks
574 - Fixtures: [factory functions / fixture files / inline data]
575 - Assertions: [preferred assertion style]
576 - Nesting: Max 2 levels of describe blocks — use descriptive test names instead
577 - Verification: MUST run `tsc --noEmit` on test files before marking complete
578 - Benchmarks: [approach if any]
579
580 # NOTE: Commit message convention, PR workflow, and tool preferences
581 # are behavioral — they belong in AGENTS.md, not here.
582
583 # ═══════════════════════════════════════════════════════════════════════════
584 # PATTERNS TO AVOID
585 # ═══════════════════════════════════════════════════════════════════════════
586
587 ## Code Anti-Patterns
588 - Using `any` instead of `unknown` or generics
589 - Using `enum` instead of `as const` objects
590 - Using `interface` when `type` works (prefer type)
591 - Returning `null`/`undefined` instead of zero values (empty arrays, empty strings, 0, false)
592 - Not validating external data with schemas
593 - Deep nesting instead of early returns
594
595 - [anti-pattern]: [why it's banned or deprecated]
596
597 ## Performance Anti-Patterns
598 - Chaining array methods (`.filter().map().reduce()`) — use single reduce pass
599 - Using `Array.includes()` for repeated lookups (use `Set.has()` for O(1) lookups)
600 - Recomputing constants inside loops (hoist invariants outside)
601 - Unbounded loops or queues (set explicit limits to prevent runaway resource consumption)
602 - Placing `try/catch` in hot paths (V8 cannot inline, 3-5x slowdown)
603
604 - [anti-pattern]: [why it's banned or deprecated]
605
606 ## Testing Anti-Patterns
607 - Testing library internals (e.g., verifying Array.prototype.map works)
608 - Exporting internal functions just to test them
609 - Loose assertions in tests (toBeTruthy, toBeDefined)
610 - Nested describe blocks >2 levels deep
611 - Testing implementation details instead of behavior
612
613 - [anti-pattern]: [why it's banned or deprecated]
614
615 ## Documentation Anti-Patterns
616 - Missing JSDoc on exported functions/types
617 - Documenting HOW instead of WHAT/WHY in JSDoc
618 - Vague comment markers (`// TODO: fix this` instead of `// TODO: Replace with binary search for O(log n)`)
619
620# ═══════════════════════════════════════════════════════════════════════════
621# PER-ARTIFACT RULES
622# ═══════════════════════════════════════════════════════════════════════════
623
624rules:
625 proposal:
626 # QRSPI: Scope definition, not a plan.
627 - State the requirement or ticket driving this change
628 - Define scope boundaries — explicitly list what is OUT of scope
629 - Keep under 100 lines (tight and focused)
630 [user-specific proposal rules]
631
632 design:
633 # QRSPI: The "brain surgery" checkpoint — reviewed before any code is written.
634 # Target ~200 lines capturing current state, desired state, open questions.
635
636 # Required sections (in this order):
637 - Start with "Current State": what the code does today, key files, entry
638 points, relevant data flows
639 - "Desired End State": what changes after this work, what stays the same
640 - "Patterns to Follow": ONLY if specific files/functions to reference exist
641 for this change's domain
642 - "Patterns to Avoid": ONLY if specific anti-patterns apply to this change
643 - "Open Questions": genuine uncertainties requiring human input. If none,
644 state explicitly "No unresolved questions."
645 - "Resolved Decisions": numbered (Decision 1, Decision 2…) with Choice,
646 Rationale, Alternatives Considered
647
648 # Technical depth:
649 - Use ASCII diagrams for data flows, state machines, architecture
650 - Call out performance implications where relevant
651 [user-specific design rules]
652
653 # Constraints:
654 - Keep under 250 lines total
655
656 tasks:
657 # QRSPI: Vertical slicing for early failure detection.
658
659 # Vertical slicing (strong preference):
660 - Order as vertical slices — each task delivers a testable end-to-end path
661 - Do NOT group by architectural layer unless explicitly justified
662 - Horizontal (layer-by-layer) only for pure infrastructure; include
663 justification in the task description when used
664 - Each task MUST include an explicit "Test:" line describing what to verify
665 before proceeding to the next task
666 - Prefer 3–5 major slices; more than 5 suggests scope is too large
667
668 # Granularity:
669 - Max 2 hours per task; break larger work into subtasks
670 [user-specific task tagging, e.g., [PKG:name] or [MODULE:name]]
671 - Call out inter-task dependencies explicitly
672 [user-specific rollback requirements]
673 [user-specific deployment test gates]
674
675 spec:
676 - Use Given/When/Then for behaviour specifications
677 - Include concrete example data relevant to the domain
678 - Document edge cases explicitly
679 [user-specific spec rules]
680
681# ═══════════════════════════════════════════════════════════════════════════
682# RELATED DOCUMENTATION
683# ═══════════════════════════════════════════════════════════════════════════
684# Include only files that actually exist in the repository:
685# - ARCHITECTURE.md: System overview, deployment, component interactions, data flows
686# - AGENTS.md: Agent behavior rules, workflow procedures, communication style
687# - README.md: Installation, quick start, usage guide
688```
689
690---
691
692## Interaction Principles
693
694- **Conversational, not interrogative.** Bundle related questions into a single
695 turn. Use natural language, not bullet-dump forms.
696- **Infer and confirm.** "You mentioned Vitest — I'll assume you're using
697 `@testing-library/react` for component tests; correct?" is better than asking
698 from scratch.
699- **Examples reduce ambiguity.** When asking about naming conventions, give an
700 example first so the user can pattern-match.
701- **Iterative.** Let the user amend answers. Don't lock them into the first
702 response.
703- **Preview before writing.** Always show the full generated config and get
704 explicit confirmation before touching the filesystem.
705- **Infer before asking, ask before omitting.** Always attempt codebase
706 inference for any unanswered field. If inference fails, surface a `# TODO`
707 rather than dropping the section. A config with explicit TODOs is actionable;
708 a config with missing sections silently degrades every artifact it drives.