feat: add design.md companion files (opt-in) (#226)

Adds design.md companion file support (opt-in via config), building on testing.md companions (#225) and YAML language support (#224).

Author: corvid-agent

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`testing.md` companion file** — a new default companion file scaffolded alongside every spec. Contains sections for automated test locations, manual QA checklists, and edge cases/boundary conditions. Generated by `specsync generate`, `specsync add-spec`, and `specsync new --full` (#225).
+- **`design.md` companion file (opt-in)** — layout, component hierarchy, design tokens, and asset references. Enabled via `[companions] design = true` in `.specsync/config.toml`. Generated alongside other companions when enabled (#226).
+- **YAML as source language** — `Language::Yaml` variant added to export extraction. Detects `.yaml`/`.yml` files and extracts top-level mapping keys as symbols (#224).
+
 ## [4.1.3] - 2026-04-11
 
 ### Fixed

README.md

@@ -8,7 +8,7 @@
 [![Downloads](https://img.shields.io/crates/d/specsync.svg)](https://crates.io/crates/specsync)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Bidirectional spec-to-code validation with cross-project references, dependency graphs, and AI-powered generation.** Written in Rust. Single binary. 11 languages. VS Code extension.
+**Bidirectional spec-to-code validation with cross-project references, dependency graphs, and AI-powered generation.** Written in Rust. Single binary. 12 languages. VS Code extension.
 
 [Quick Start](#quick-start) • [Spec Format](#spec-format) • [CLI](#cli-reference) • [VS Code Extension](#vs-code-extension) • [Cross-Project Refs](#cross-project-references) • [GitHub Action](#github-action) • [Config](#configuration) • [Docs Site](https://corvidlabs.github.io/spec-sync)
 
@@ -48,6 +48,7 @@ Auto-detected from file extensions. Same spec format for all.
 | **Dart** | Top-level (no `_` prefix), class/mixin/enum/typedef | `*_test.dart` |
 | **PHP** | `class/interface/trait/enum`, `public` function/const, skips `private/protected` and `__` magic methods | `*Test.php` |
 | **Ruby** | `class`/`module`, `public` methods with visibility tracking, `attr_accessor`/`attr_reader`/`attr_writer`, constants | `*_test.rb`, `*_spec.rb` |
+| **YAML** | Top-level mapping keys (anchors, aliases supported) | — |
 
 ---
 
@@ -293,7 +294,7 @@ specsync [command] [flags]
 | `report` | Per-module coverage report with stale and incomplete detection |
 | `generate` | Scaffold specs for modules missing one (`--provider` for AI-powered content) |
 | `scaffold <name>` | Scaffold spec + auto-detect source files + register in registry |
-| `add-spec <name>` | Scaffold a single spec + companion files (`requirements.md`, `tasks.md`, `context.md`) |
+| `add-spec <name>` | Scaffold a single spec + companion files (`requirements.md`, `tasks.md`, `context.md`, `testing.md`, and `design.md` if enabled) |
 | `deps` | Validate cross-module dependency graph (cycles, missing deps, undeclared imports) |
 | `changelog <range>` | Generate changelog of spec changes between two git refs |
 | `comment` | Post spec-sync check summary as a PR comment (same validation pipeline as `check`). `--pr N` to post, omit to print |
@@ -399,14 +400,23 @@ Remote resolution fetches `specsync-registry.toml` from each referenced repo and
 
 ## Companion Files
 
-When you run `specsync generate` or `specsync add-spec`, three companion files are created alongside each spec:
+When you run `specsync generate` or `specsync add-spec`, four companion files are created alongside each spec, plus one opt-in:
 
 | File | Author | Validated? | Purpose |
 |------|--------|-----------|---------|
 | `{module}.spec.md` | Dev/Architect | Yes — against code | Technical contract |
 | `tasks.md` | Anyone | No | Work coordination |
 | `context.md` | Dev/Agent | No | Architecture notes |
 | `requirements.md` | Product/Design | No | The ask, acceptance criteria |
+| `testing.md` | QA/Dev | No | Test strategy, edge cases, manual checklists |
+| `design.md` *(opt-in)* | Design/Frontend | No | Layout, component hierarchy, design tokens |
+
+`design.md` is opt-in — enable it in `.specsync/config.toml`:
+
+```toml
+[companions]
+design = true
+```
 
 All scaffolded by SpecSync, all human-filled. Only the spec gets bidirectional validation.
 
@@ -472,6 +482,43 @@ spec: auth.spec.md
 <!-- Free-form notes, links, context -->
 ```
 
+**`testing.md`** — Test strategy and QA checklist:
+
+```markdown
+---
+spec: auth.spec.md
+---
+
+## Automated Tests
+<!-- Test file locations and what they cover -->
+
+## Manual QA Checklist
+- [ ] <!-- Manual verification steps -->
+
+## Edge Cases
+<!-- Boundary conditions, race conditions, unusual inputs -->
+```
+
+**`design.md`** *(opt-in)* — Design and layout documentation:
+
+```markdown
+---
+spec: auth.spec.md
+---
+
+## Layout
+<!-- Page/component layout, responsive breakpoints, positioning -->
+
+## Components
+<!-- Component tree, props, slots -->
+
+## Tokens
+<!-- Design token overrides from global design system -->
+
+## Assets
+<!-- Icons, images, illustrations needed -->
+```
+
 These files are designed for team coordination and AI agent context — they give any contributor (human or AI) the full picture of where a module stands.
 
 ---
@@ -858,7 +905,8 @@ src/
     ├── csharp.rs       C# public items
     ├── dart.rs         Dart public items
     ├── php.rs          PHP public items
-    └── ruby.rs         Ruby public items
+    ├── ruby.rs         Ruby public items
+    └── yaml.rs         YAML top-level keys
 ```
 
 **Design:** Single binary, no runtime deps. Frontmatter parsed with regex (no YAML library). Language backends use regex, not ASTs — works without compilers installed. Release builds use LTO + strip + opt-level 3.

docs/src/architecture.md

@@ -39,7 +39,8 @@ src/
     ├── csharp.rs         C# public items
     ├── dart.rs           Dart public items
     ├── php.rs            PHP public classes/functions
-    └── ruby.rs           Ruby public methods/classes
+    ├── ruby.rs           Ruby public methods/classes
+    └── yaml.rs           YAML top-level keys
 ```
 
 ---

docs/src/cli.md

@@ -85,7 +85,7 @@ Exposes tools: `specsync_check`, `specsync_generate`, `specsync_coverage`, `spec
 
 ### `add-spec`
 
-Scaffold a single spec with companion files (`requirements.md`, `tasks.md`, `context.md`).
+Scaffold a single spec with companion files (`requirements.md`, `tasks.md`, `context.md`, `testing.md`, and `design.md` if enabled).
 
 ```bash
 specsync add-spec auth                     # creates specs/auth/auth.spec.md + companions
@@ -166,7 +166,7 @@ Quick-create a minimal spec with auto-detected source files. Faster than `add-sp
 
 ```bash
 specsync new auth                          # creates specs/auth/auth.spec.md
-specsync new auth --full                   # also creates companion files (requirements.md, tasks.md, context.md)
+specsync new auth --full                   # also creates companion files (requirements.md, tasks.md, context.md, testing.md, and design.md if enabled)
 ```
 
 Scans `sourceDirs` for files matching the module name to auto-populate the `files:` frontmatter field.

docs/src/quickstart.md

@@ -81,12 +81,15 @@ specs/
 │   ├── auth.spec.md        ← The spec (validated)
 │   ├── requirements.md     ← User stories & acceptance criteria
 │   ├── tasks.md            ← Work items & sign-offs
-│   └── context.md          ← Architecture notes & key files
+│   ├── context.md          ← Architecture notes & key files
+│   ├── testing.md          ← Test strategy & QA checklist
+│   └── design.md           ← (opt-in) Layout & design tokens
 ├── database/
 │   ├── database.spec.md
 │   ├── requirements.md
 │   ├── tasks.md
-│   └── context.md
+│   ├── context.md
+│   └── testing.md
 └── ...
 ```
 

docs/src/workflow.md

@@ -65,6 +65,7 @@ Creates `specs/auth/` with five files:
 | `tasks.md` | Outstanding work items, review sign-offs | Anyone |
 | `context.md` | Design decisions, key files, current status | Developer / Agent |
 | `testing.md` | Test strategy, QA checklists, edge cases | QA / Developer |
+| `design.md` *(opt-in)* | Layout, component hierarchy, design tokens | Design / Frontend |
 
 The spec file is the only one SpecSync validates against code. The companion files provide structured context for humans and AI agents working on the module.
 

specs/exports/exports.spec.md

@@ -15,6 +15,7 @@ files:
   - src/exports/csharp.rs
   - src/exports/php.rs
   - src/exports/ruby.rs
+  - src/exports/yaml.rs
   - src/exports/ast/mod.rs
   - src/exports/ast/typescript.rs
   - src/exports/ast/python.rs
@@ -29,7 +30,7 @@ depends_on:
 
 ## Purpose
 
-Language-aware export extraction from source files. Auto-detects the programming language from file extension and extracts public/exported symbol names using regex-based parsing or tree-sitter AST analysis. Supports 11 languages: TypeScript/JS, Rust, Go, Python, Swift, Kotlin, Java, C#, Dart, PHP, and Ruby.
+Language-aware export extraction from source files. Auto-detects the programming language from file extension and extracts public/exported symbol names using regex-based parsing or tree-sitter AST analysis. Supports 12 languages: TypeScript/JS, Rust, Go, Python, Swift, Kotlin, Java, C#, Dart, PHP, Ruby, and YAML.
 
 ## Public API
 
@@ -79,6 +80,7 @@ Each language backend exposes a single `extract_exports(content: &str) -> Vec<St
 | C# | `csharp.rs` | `public class/struct/interface/enum/record/delegate` types and `public` members; handles `static`, `partial`, `sealed`, `abstract`, `virtual`, `override`, `async` modifiers |
 | PHP | `php.rs` | `class/interface/trait/enum` types (always public); `public`/unqualified `function` and `const` declarations; skips `private`/`protected` members and `__` magic methods; handles `abstract`, `final`, `readonly`, `static` modifiers; strips `//`, `/* */`, and `#` comments |
 | Ruby | `ruby.rs` | `class`/`module` declarations; top-level `def` (always public); class methods with visibility tracking (`public`→`private`→`protected`→`public` toggles); `CONSTANT` assignments; `attr_accessor`/`attr_reader`/`attr_writer` symbols; skips `_`-prefixed names and `initialize`; strips `#` and `=begin/=end` comments |
+| YAML | `yaml.rs` | Top-level mapping keys from `.yaml`/`.yml` files; supports anchors and aliases |
 
 ## Invariants
 
@@ -104,6 +106,7 @@ Each language backend exposes a single `extract_exports(content: &str) -> Vec<St
 16. Go backend deduplicates methods that might also match top-level declarations
 17. PHP backend treats types (class/interface/trait/enum) as always public; methods and constants require `public` or unqualified visibility; `private`/`protected` are excluded; magic methods (`__construct`, `__toString`, etc.) are excluded
 18. Ruby backend tracks visibility state via `public`/`private`/`protected` toggle statements; defaults to public; `initialize` is excluded; `_`-prefixed names are excluded; `attr_accessor`/`attr_reader`/`attr_writer` emit attribute names as symbols
+19. YAML backend extracts top-level mapping keys; no test file patterns (YAML files are not test files)
 
 ## Behavioral Examples
 
@@ -230,3 +233,4 @@ Each language backend exposes a single `extract_exports(content: &str) -> Vec<St
 | 2026-03-25 | Initial spec |
 | 2026-03-28 | Document get_exported_symbols_with_level |
 | 2026-03-29 | Add PHP and Ruby language support |
+| 2026-04-12 | Add YAML language support (yaml.rs) |

specs/generator/generator.spec.md

@@ -16,7 +16,7 @@ depends_on:
 
 ## Purpose
 
-Scaffolds spec files and companion files (tasks.md, context.md) for unspecced modules. Supports both template-based generation (using a default or custom `_template.spec.md`) and AI-powered generation that reads source code and calls an LLM to produce meaningful specs.
+Scaffolds spec files and companion files (tasks.md, context.md, requirements.md, testing.md, and optionally design.md) for unspecced modules. Supports both template-based generation (using a default or custom `_template.spec.md`) and AI-powered generation that reads source code and calls an LLM to produce meaningful specs.
 
 ## Public API
 
@@ -26,7 +26,7 @@ Scaffolds spec files and companion files (tasks.md, context.md) for unspecced mo
 |----------|-----------|---------|-------------|
 | `generate_specs_for_unspecced_modules` | `root, report, config, provider` | `usize` | Generate specs for all unspecced modules, returning count of generated specs |
 | `generate_specs_for_unspecced_modules_paths` | `root, report, config, provider` | `Vec<String>` | Generate specs for all unspecced modules, returning paths of generated files |
-| `generate_companion_files_for_spec` | `spec_dir, module_name` | `()` | Generate tasks.md and context.md companion files alongside a spec |
+| `generate_companion_files_for_spec` | `spec_dir, module_name, design_enabled` | `()` | Generate companion files (tasks.md, context.md, requirements.md, testing.md, and design.md if enabled) alongside a spec |
 | `find_files_for_module` | `root, module_name, config` | `Vec<String>` | Find source files for a module by checking config definitions, subdirectories, then flat files |
 | `generate_spec` | `module_name, source_files, root, specs_dir` | `String` | Generate a spec from a template (custom or language-aware default) |
 | `generate_spec_from_custom_template` | `template_dir, module_name, source_files, root` | `String` | Generate a spec using files from a custom template directory |
@@ -38,7 +38,7 @@ Scaffolds spec files and companion files (tasks.md, context.md) for unspecced mo
 2. Custom templates at `specs/_template.spec.md` take precedence over the built-in default
 3. Template generation fills in module name, version (1), status (draft), and discovered source files
 4. Module title is derived from the module name with dashes converted to title case (e.g. "api-gateway" -> "Api Gateway")
-5. Companion files (tasks.md, context.md) are only created if they don't already exist
+5. Companion files (tasks.md, context.md, requirements.md, testing.md, and design.md when enabled) are only created if they don't already exist
 6. AI generation falls back to template on failure (with a warning to stderr)
 7. Source file paths in frontmatter are relative to the project root
 8. Module source files are discovered by checking subdirectory-based modules first, then flat files
@@ -49,7 +49,7 @@ Scaffolds spec files and companion files (tasks.md, context.md) for unspecced mo
 
 - **Given** a module "auth" with source files in `src/auth/` and no existing spec
 - **When** `generate_specs_for_unspecced_modules` is called
-- **Then** creates `specs/auth/auth.spec.md`, `specs/auth/tasks.md`, and `specs/auth/context.md`
+- **Then** creates `specs/auth/auth.spec.md`, `specs/auth/tasks.md`, `specs/auth/context.md`, `specs/auth/requirements.md`, and `specs/auth/testing.md`
 
 ### Scenario: Skip existing spec
 
@@ -95,3 +95,4 @@ Scaffolds spec files and companion files (tasks.md, context.md) for unspecced mo
 |------|--------|
 | 2026-03-25 | Initial spec |
 | 2026-04-07 | Document find_files_for_module, generate_spec, generate_spec_from_custom_template, generate_companion_files_from_template |
+| 2026-04-12 | Update companion files list to include requirements.md, testing.md, and opt-in design.md; add design_enabled parameter |

specs/types/types.spec.md

@@ -22,7 +22,7 @@ Core data structures and enums shared across the entire spec-sync codebase. Defi
 | Type | Description |
 |------|-------------|
 | `AiProvider` | Supported AI provider presets: Claude, Cursor, Copilot, Ollama, Anthropic, OpenAi, Custom |
-| `Language` | Detected source language for export extraction: TypeScript, Rust, Go, Python, Swift, Kotlin, Java, CSharp, Dart, Php, Ruby |
+| `Language` | Detected source language for export extraction: TypeScript, Rust, Go, Python, Swift, Kotlin, Java, CSharp, Dart, Php, Ruby, Yaml |
 | `OutputFormat` | CLI output format: Text (colored terminal, default), Json (machine-readable), Markdown (PR comments / agent consumption) |
 | `ExportLevel` | Export extraction granularity: Type (top-level declarations only) or Member (all public symbols, default) |
 | `SpecStatus` | Spec lifecycle status: draft, review, active, stable, deprecated, archived. Parsed from frontmatter `status` field |
@@ -47,6 +47,7 @@ Core data structures and enums shared across the entire spec-sync codebase. Defi
 | `RuleFilter` | Filter to restrict which specs a custom rule applies to — optional status and module regex match |
 | `LifecycleConfig` | Lifecycle configuration for transition guards and history tracking (guards map, track_history flag) |
 | `TransitionGuard` | A transition guard — min_score, require_sections, no_stale, stale_threshold, message |
+| `CompanionConfig` | Configuration for companion file generation — controls opt-in companions like design.md |
 
 ### Exported AiProvider Functions
 
@@ -173,3 +174,4 @@ Core data structures and enums shared across the entire spec-sync codebase. Defi
 | 2026-04-10 | Document CustomRule, CustomRuleType, RuleSeverity, RuleFilter for declarative custom validation rules |
 | 2026-04-11 | Document SpecStatus lifecycle methods (all, ordinal, next, prev, valid_transitions, can_transition_to) |
 | 2026-04-11 | Move parsed_status to Frontmatter section; fix next/prev descriptions to include deprecated/archived |
+| 2026-04-12 | Document CompanionConfig struct for opt-in companion file settings |

src/commands/import.rs

@@ -146,7 +146,11 @@ fn cmd_import_single(root: &Path, source: &str, id: &str, repo_override: Option<
         Ok(_) => {
             let rel = spec_file.strip_prefix(root).unwrap_or(&spec_file).display();
             println!("  {} Created {rel}", "✓".green());
-            generator::generate_companion_files_for_spec(&spec_dir, &item.module_name);
+            generator::generate_companion_files_for_spec(
+                &spec_dir,
+                &item.module_name,
+                config.companions.design,
+            );
             println!(
                 "\n{} Run {} to validate and fill in the details.",
                 "Tip:".cyan().bold(),
@@ -249,7 +253,11 @@ fn cmd_import_all_issues(root: &Path, repo_override: Option<&str>, label: Option
             Ok(_) => {
                 let rel = spec_file.strip_prefix(root).unwrap_or(&spec_file).display();
                 println!("{} #{} → {}", "✓".green(), issue.number, rel);
-                generator::generate_companion_files_for_spec(&spec_dir, &item.module_name);
+                generator::generate_companion_files_for_spec(
+                    &spec_dir,
+                    &item.module_name,
+                    config.companions.design,
+                );
                 stats.imported += 1;
             }
             Err(e) => {
@@ -349,7 +357,11 @@ fn cmd_import_from_dir(root: &Path, dir: &Path) {
             Ok(_) => {
                 let rel = spec_file.strip_prefix(root).unwrap_or(&spec_file).display();
                 println!("{} → {}", "✓".green(), rel);
-                generator::generate_companion_files_for_spec(&spec_dir, &item.module_name);
+                generator::generate_companion_files_for_spec(
+                    &spec_dir,
+                    &item.module_name,
+                    config.companions.design,
+                );
                 stats.imported += 1;
             }
             Err(e) => {