--- name: accelint-onboard-openspec description: 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. license: Apache-2.0 metadata: author: accelint version: "1.5.0" --- # Onboard OpenSpec Guide the user through a conversational interview to produce a complete, project-specific `openspec/config.yaml` configured for the QRSPI methodology. ## NEVER Do When Onboarding OpenSpec - **NEVER run codebase inference serially when subagents are available** — Phase 3 spawns parallel subagents for different discovery domains. Serial scanning wastes time on codebases with many config files spread across directories. Spawn all 4 discovery agents simultaneously. ## Companion Skill This skill produces the **project DNA layer** of the agent instruction stack: structural facts about what the project is. It is the companion to the `accelint-onboard-agents` skill, which produces the **behavior layer** (`AGENTS.md` / `CLAUDE.md`): how the agent acts, communicates, and makes decisions. If during this interview the user volunteers behavioral content (commit conventions, workflow steps, decision heuristics, tool preferences), acknowledge it and redirect: *"That's behavioral — it belongs in AGENTS.md. I'll note it here for reference, but the `accelint-onboard-agents` skill is the right place to capture it."* Do not write behavioral content into `config.yaml`. ``` AGENTS.md / CLAUDE.md → accelint-onboard-agents skill → HOW the agent behaves openspec/config.yaml → this skill → WHAT the project is ``` --- ## Mental Model The config has two jobs: 1. **`context:`** — Objective facts about the codebase injected into every AI artifact. Think of it as the "DNA" that makes AI suggestions feel native to the project. Facts only, no opinions. 2. **`rules:`** — Per-artifact checkpoints (proposal / design / tasks / spec) that encode the team's quality bar. ## Phases ### Phase 0 — File State Detection Before any interview question is asked, check whether `openspec/config.yaml` exists and assess its state. Never silently pick a mode — always announce the detected mode to the user and confirm before proceeding. **Step 1 — Check for Related Documents** Before detecting config.yaml state, check for related onboarding documents: 1. **Check for ARCHITECTURE.md** - If exists: Read it to understand deployment and infrastructure - Use it to pre-fill answers for Turn 2 (infrastructure/deployment questions) - Note its existence for the "Related Documentation" section - Announce: "Found ARCHITECTURE.md — I'll use it to avoid asking questions about deployment that are already documented." Note: AGENTS.md and README.md should NOT influence config.yml generation since they contain behavioral/usage info, not project DNA. **Step 2 — Detect Config State** After checking related documents, assess the config file state: ``` Does openspec/config.yaml exist? │ ├── No → MODE 1: Create │ Full interview from scratch. │ └── Yes → Read the file, then assess: │ ├── Empty or near-blank (schema: line only, no context/rules)? │ → MODE 1: Create (with overwrite confirmation) │ Ask: "config.yaml exists but appears empty — should I │ populate it from scratch, or preserve any current content?" │ ├── Contains recognised fields? │ (context: block present, rules: block with known artifact keys) │ → MODE 3: Refresh │ Abbreviated interview covering only detected drift and │ unresolved # TODO: fill in markers. │ └── Contains real content in an unrecognised shape? → MODE 2: Import Present three options (A / B / C) before proceeding. ``` **Recognised shape** = file is valid YAML with at least a `context:` key whose value is a non-empty string, or a `rules:` key with at least one of the known artifact IDs (`proposal`, `specs`, `design`, `tasks`). --- #### Mode 1: Create Run the full Phase 1 → Phase 2 → Phase 3 → Phase 4 interview. This is the happy path for a fresh repo. --- #### Mode 2: Import The file has real content that was not generated by this skill. Present the user with three options before touching anything: > "This `config.yaml` has existing content with a structure I don't > recognise. How would you like to proceed? > > **(a) Restructure** — I'll import your existing content, map it onto the > `context:` / `rules:` schema, flag any material that belongs in `AGENTS.md` > instead (workflow steps, commit conventions, tool preferences), run a > targeted interview to fill gaps, and produce a merged file ready to replace > the current one. > > **(b) Append** — I'll run the full interview and add the skill's `context:` > and `rules:` sections alongside your existing content without modifying > what's already there. > > **(c) Dry run** — I'll run the full interview and show you exactly what I > would have generated, with no changes to the filesystem. Use this to > evaluate fit before committing." **If option (a) is chosen:** 1. Read the file in full. 2. Map existing content onto `context:` sub-sections and `rules:` artifact keys where possible. 3. Flag any content that violates the separation-of-concerns boundary (e.g., commit conventions, workflow steps, tool preferences, agent decision heuristics) — these belong in `AGENTS.md`. For each violation, ask: *"This looks behavioral — it belongs in AGENTS.md. Should I move it there and remove it from config.yaml?"* 4. Run a targeted interview covering only the gaps (context sub-sections with no existing coverage; artifact keys with no rules). 5. Show a merged preview before writing. Existing content is labelled `# from existing file`; new content is labelled `# new`. **If option (b) is chosen:** Run the full Phase 1 → Phase 4 interview and write the generated `context:` and `rules:` blocks alongside existing content. Add a comment at the top: `# Sections below added by accelint-onboard-openspec skill`. **If option (c) is chosen:** Run the full Phase 1 → Phase 4 interview and present the output in the conversation. Explicitly state: "No files were changed." Offer to re-run as (a) or (b) if the user is satisfied. --- #### Mode 3: Refresh The file matches the skill's expected schema — it was likely produced by a previous run. Run an abbreviated interview covering only: 1. **Extract external findings** — check if the invoking prompt includes a `findings:` list: - Parse the prompt for a `findings:` section (a bulleted list of factual statements) - Each finding is phrased as something already known to be true, never as an instruction - Example: "config.yaml's Anti-Patterns section says to avoid polling, but two archived changes chose polling for stated reasons" - Store these findings for merging in step 4 2. **Drift detection** — scan the codebase for changes since the file was last updated: | Signal | Where to look | |--------|---------------| | Runtime / Node version changed | `.nvmrc`, `.node-version`, `Dockerfile` | | New packages / frameworks added | `package.json` deps, workspace roots | | TypeScript config tightened | `tsconfig.json` — new `strict*` flags | | New packages in monorepo | `pnpm-workspace.yaml`, `turbo.json` | | Build tooling changed | `vite.config.*`, `tsup.config.*` | | CI/CD workflows added | `.github/workflows/` | | New domain concepts | New top-level directories, new entity types in source | | Anti-patterns deprecated | `@deprecated` tags, `// TODO: replace` comments added | 3. **Unresolved TODOs** — find all `# TODO: fill in` markers left from the previous run and surface them as targeted questions. 4. **Merge and announce all findings** before asking anything: - Combine external findings (from step 1) with drift findings (from step 2) and TODOs (from step 3) - Present the merged list to the user: > "I found [N] external findings, [M] context sections that may have drifted, and [P] unresolved TODOs. > I'll only ask about those — the rest looks current." - If external findings exist, note their source (e.g., "from completed OpenSpec change") 5. After the targeted interview, show only the changed sections in the preview before writing. Do not re-emit unchanged sections. --- ### Phase 1 — Discovery Interview Run the interview conversationally. Don't dump all questions at once. Group them into natural topic turns. If the user mentions a stack, infer related tooling and confirm rather than asking again. **Turn 1 — Project Identity** - What is the project name and its primary purpose? - Monorepo, single package, or something else? If monorepo, what workspaces? - Build system / task orchestration? (Turbo, Nx, Make, npm scripts, Makefile…) - Package manager and any private registries? (npm, pnpm, yarn, bun…) **Turn 2 — Tech Stack** *(ask as a grouped block, not one by one)* - Runtime and version (Node.js 20, Bun 1.x, Python 3.12, etc.) - Language + config (TypeScript strict? `exactOptionalPropertyTypes`? Python type hints?) - Framework(s) and version (React 18, Next.js 14, Express, FastAPI, etc.) - Key domain libraries (Deck.gl, Apache Arrow, Prisma, SQLAlchemy, etc.) - Data layer (Postgres, MongoDB, DynamoDB, ORM/query builder, data formats) - Testing setup (Vitest, Jest, Pytest, testing-library, Playwright, etc.) - Linting / formatting (ESLint, Biome, Prettier, Black, Ruff, etc.) - Build tools (Vite, tsup, esbuild, Webpack, etc.) - CI/CD (GitHub Actions, CircleCI, etc.) - Versioning approach (Changesets, standard-version, conventional commits, etc.) **Turn 3 — Architecture** - How is the codebase organised? (feature-based, layer-based, domain-driven?) - Where does shared/utility code live? - Any path aliases? (`@/`, `~/`, `src/`, `#lib/`, etc.) - Design patterns commonly in use? (factory, repository, observer, CQRS, etc.) **Turn 4 — Domain Concepts** - What are the 3–5 most important domain entities? *Example prompt: "For a mapping app this might be Layer, Source, Viewport, Feature, Style."* - Any domain-specific terminology the AI should know? - Any specialised concepts with non-obvious meanings in this codebase? *Example: "orchestration" means something specific to us — it's the runtime layer that merges style with data, not a general workflow term.* **Turn 5 — Performance** - Any concrete performance targets? (p95 < 200 ms, 60 fps, < 50 MB heap, etc.) - Known hot paths or performance-critical areas? - Memory or bundle-size constraints? **Turn 6 — Code Patterns** - Export style: named exports, default exports, or mixed? - Naming conventions: files, variables, functions, constants? *Example: "kebab-case files, camelCase vars, SCREAMING_SNAKE_CASE for constants, PascalCase for types."* - Error handling: throw, `Result`, error boundaries, something else? - Testing structure: `describe/it`, `test/expect`, AAA pattern? - Test file location: co-located with source or a separate `__tests__/` tree? - Fixture / factory approach for test data? > **Note:** Commit message convention is a workflow procedure — it belongs in > `AGENTS.md`, not here. If the user raises it now, capture it mentally and > surface it in the `accelint-onboard-agents` skill. Do not add it to `config.yaml`. **Turn 7 — Anti-Patterns** - Any patterns explicitly banned in code review? - Deprecated patterns still in the codebase that new code should NOT emulate? - Known performance traps specific to this stack? **Turn 8 — Proposal Rules** What does YOUR team require in a proposal? Good prompts: - "Do you need proposals to call out database migration impact?" - "Do you need proposals to flag API breaking changes?" - "Any security review checklist items?" **Turn 9 — Design Rules** Project-specific design concerns to encode? Good prompts: - "Docker / Kubernetes resource changes to document?" - "Performance implications section required?" - "Specific architecture diagram style (ASCII, Mermaid)?" **Turn 10 — Task Rules** - How do you tag tasks by package or module? *Example: `[PKG:auth]`, `[MODULE:pipeline]`, GitHub labels…* - Rollback plan required for database changes? - Deployment-specific test gates (smoke tests, canary checks)? --- ### Phase 2 — Smart Defaults After each stack answer, surface relevant conventions to confirm. Use these examples as a pattern; extend to other stacks as appropriate. **Next.js + TypeScript + Tailwind → suggest confirming:** - App Router vs Pages Router and which patterns apply - Server Component vs Client Component boundary rules - `"use client"` directive placement convention - API route organisation (`app/api/` vs `pages/api/`) **React + Vitest + testing-library → suggest confirming:** - `userEvent` over `fireEvent` preference - `screen` query priority (role > label > testid) - `render` wrapper for providers **Python + FastAPI → suggest confirming:** - Pydantic v1 vs v2 (different field-validator syntax) - Dependency injection for DB sessions (`Depends`) - Alembic migration workflow - `lifespan` vs `startup`/`shutdown` event hooks **Node.js + Prisma → suggest confirming:** - `prisma.$transaction` patterns - Soft-delete vs hard-delete convention - Migration naming convention --- ### Phase 3 — Parallel Codebase Inference After the interview, spawn parallel discovery subagents to fill remaining config gaps. All config sections are load-bearing — a missing field degrades every downstream AI artifact, so inference is always preferable to omission. Spawn discovery subagents in parallel — don't scan serially. Each agent focuses on one inference domain and returns structured findings. Wait for all agents to complete, then merge results before Phase 4. **Spawn these agents simultaneously:** **Agent A — Stack & Build Tooling** - Runtime / Node version: `.nvmrc`, `.node-version`, `package.json#engines`, `Dockerfile` - TypeScript config: `tsconfig.json` (compilerOptions flags, paths aliases) - Package manager: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb` - Monorepo workspaces: `package.json#workspaces`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json` - Build tools: `vite.config.*`, `webpack.config.*`, `tsup.config.*`, `esbuild` scripts - Return: runtime version, TS config flags, package manager, workspace list, build tools **Agent B — Testing & Code Quality** - Test framework: `vitest.config.*`, `jest.config.*`, `pytest.ini`, `pyproject.toml#tool.pytest` - Linting / formatting: `.eslintrc*`, `biome.json`, `.prettierrc*`, `ruff.toml` - Test structure: Sample test files — describe/it nesting depth, file location relative to source - Test file type checking: CI scripts, package.json — check if `tsc --noEmit` runs on `*.test.ts` files - Property-based testing: Check for `fast-check` in dependencies - Vitest mock cleanup: `vitest.config.ts` — check for `clearMocks`, `mockReset`, `restoreMocks` - Return: test framework, code quality tools, test structure patterns, type checking config **Agent C — Architecture & Code Patterns** - Architecture organisation: Directory tree of `src/` or workspace roots — infer feature-based vs layer-based - Path aliases: `tsconfig.json#compilerOptions.paths`, `vite.config#resolve.alias` - Design patterns: Sample source files — look for factory functions, repository objects, observer hooks - Export style: Sample 3–5 source files; tally named vs default exports - Naming conventions: Sample file names, exported identifiers; describe what you observe - Error handling: Grep for `throw`, `Result`, `Either`, `tryCatch`, error boundary components - TypeScript baseline patterns: If `tsconfig.json` exists, flag that TS/JS baseline patterns should be included - Return: architecture style, path aliases, design patterns, export conventions, naming patterns, error handling approach **Agent D — CI/CD & Versioning** - CI/CD: `.github/workflows/`, `.circleci/`, `Jenkinsfile` - Versioning: `.changeset/`, `CHANGELOG.md`, `commitlint.config.*`, `.releaserc*` - Anti-patterns: `eslint` rule overrides marked `off` or `warn`, comments like `// TODO: replace`, `@deprecated` - Return: CI/CD platform, versioning approach, documented anti-patterns **After all agents complete:** merge their findings into a unified inference map. Tag each field as `INFERRED [source]` or `UNKNOWN`. Fields tagged `UNKNOWN` should be marked as `# TODO: fill in` in the config preview. **For each field resolved via inference**, note the source in the preview with a trailing comment, e.g.: ```yaml - Runtime: Node.js 20 LTS # inferred from .nvmrc - Language: TypeScript 5.4, strict, exactOptionalPropertyTypes # inferred from tsconfig.json ``` **If a field genuinely cannot be inferred** (e.g., performance targets, domain concepts, team-specific rules), mark it with `# TODO: fill in` rather than omitting it. The user can resolve these after reviewing the preview. Do not silently drop a section — an explicit TODO is a prompt to act; an absent section is an invisible gap. --- ### Phase 4 — Generation 1. **Show a labeled preview** of the full config before writing anything. Inferred values carry their source comment; unresolved fields carry `# TODO: fill in`. This gives the user a complete picture of confidence level across every field. 2. Ask: *"Does this look right? Any sections to correct or expand before I write the file?"* 3. After confirmation, write to `openspec/config.yaml` (create directory if needed), **stripping the inference source comments** — they are for review only, not the final file. **For the Related Documentation section:** only include links to files that actually exist in the repository. Check for each file (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:** ```yaml # 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: ```yaml # 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 ```yaml # 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. ```yaml 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 / 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.