chore: repo cleanup, stale doc fixes, CHANGELOG backfill

Repo hygiene
- Delete stale tracked artifacts: nupkgs/ (old v1.14/v1.15 packages
  that pre-date the *.nupkg gitignore rule), coverage/ (Mar 15 cobertura
  reports), docs/PROJECT-KNOWLEDGE.md (stale shadow of root version
  that diverged weeks ago — root is canonical)
- Add coverage/ to .gitignore so it stops getting committed

AGENTS.md
- Replaced with a 5-line stub pointing to CLAUDE.md (the auto-maintained
  agent context). Old AGENTS.md had multiple stale references:
  Spectra.GitHub project (doesn't exist), Spectra.Tests (split into 3
  test projects long ago), spectra.profile.md at repo root (replaced
  by profiles/_default.yaml), and a "Recent Changes" section that
  ended at spec 010 (24+ specs ago). Keeps the agents.md filename
  convention while routing readers to the live source of truth.

architecture-v5.md
- Added a status header clarifying it's the original design spec, not
  the current state. Points readers at CLAUDE.md, PROJECT-KNOWLEDGE.md,
  and specs/ for current architecture.

CONTRIBUTING.md
- Removed reference to non-existent spec-kit/adr/ directory; replaced
  with the spec-kit workflow (specs/NNN-feature/) that actually exists.

CHANGELOG.md
- Backfilled the missing 1.36.0 entry covering all three features
  released in this version: spec 030 (customizable prompt templates,
  11th SKILL), spec 031 (visible default profile & customization
  guide), spec 032 (quickstart SKILL & USAGE.md offline guide).
  Also notes the three Dependabot bumps merged today.

Documentation accuracy fixes
- README.md: 'requirements'→'acceptance criteria' in coverage
  section, '10 SKILLs'→'12 SKILLs', extracts 'requirements'→
  'acceptance criteria'
- docs/test-format.md: requirements field→criteria field throughout
  the example, the fields table, the coverage mapping, and the
  _index.json example
- docs/configuration.md: removed legacy requirements_file column;
  scan example uses criteria_file
- docs/architecture/overview.md: 'Requirements'→'Acceptance Criteria'
  in the three coverage dimensions list
- docs/cli-reference.md: spectra init now reports the actual artifacts
  it creates (12 SKILLs, profiles, prompts, CUSTOMIZATION.md, USAGE.md);
  removed the 'spectra mcp start' subcommand reference (the command
  doesn't exist — MCP is the separate spectra-mcp global tool)
- docs/skills-integration.md: '9 SKILL files'→'12 SKILL files', added
  rows for spectra-update, spectra-prompts, spectra-quickstart
- docs/execution-agent/overview.md, copilot-cli.md, generic-mcp.md,
  claude.md: replaced all 'spectra mcp start' / 'spectra mcp call'
  references with the correct spectra-mcp standalone tool invocation
  and JSON-RPC stdio examples; copilot-cli.md no longer points at a
  nonexistent .github/skills/spectra-execution/SKILL.md (the agent
  prompt lives in .github/agents/spectra-execution.agent.md)

Author: angelovstanton

.gitignore

@@ -27,6 +27,7 @@ packages/
 
 # Test results
 TestResults/
+coverage/
 
 # SPECTRA lock files
 .spectra.lock

AGENTS.md

@@ -1,116 +1,26 @@
 # AGENTS.md
 
-## Project Overview
+> **This file exists for the [agents.md](https://agents.md) convention** so external coding agents can find a project guide by name. The authoritative agent context for SPECTRA is **[`CLAUDE.md`](CLAUDE.md)** — it is auto-maintained by the spec-kit workflow and reflects the current technology stack, project structure, recent changes, and conventions.
 
-SPECTRA is an AI-native test generation and execution framework built in C# / .NET. It has two independent subsystems:
+## Quick orientation
 
-1. **Spectra.CLI** — AI agent that generates and maintains manual test cases from documentation. Uses the GitHub Copilot SDK as its AI runtime.
-2. **Spectra.MCP** — Deterministic MCP execution engine that any LLM orchestrator can drive to execute test suites.
+SPECTRA is an AI-native test generation and execution framework written in C# / .NET 8. Three projects under `src/`:
 
-Both share **Spectra.Core** for parsing, validation, models, and indexing.
+- **`Spectra.CLI`** — CLI tool for test generation, coverage, dashboard, validation. Uses the GitHub Copilot SDK as its sole AI runtime.
+- **`Spectra.MCP`** — Deterministic MCP execution server for AI-driven test execution.
+- **`Spectra.Core`** — Shared models, parsing, validation, indexing, coverage analyzers.
 
-## Architecture
+Tests are split mirror-style across `tests/Spectra.CLI.Tests/`, `tests/Spectra.Core.Tests/`, and `tests/Spectra.MCP.Tests/`.
 
-Read `spec-kit/architecture.md` before making any structural changes. It is the authoritative source for all design decisions.
+## Where to look next
 
-Key architectural rules:
-- Tests are Markdown files with YAML frontmatter in `tests/{suite}/`
-- Documentation lives in `docs/` — the CLI reads from docs, writes to tests
-- The MCP server never parses all Markdown files at runtime — it reads `_index.json`
-- The AI generation agent reads `docs/_index.md` (document index) instead of scanning all docs at runtime
-- The AI agent never writes files directly — all output goes through tool handlers that validate first
-- Every MCP response includes `next_expected_action` and is fully self-contained
-- State machine transitions are enforced — the MCP server rejects invalid tool call sequences
-
-## Project Structure
-
-```
-src/
-├── Spectra.CLI/              # .NET CLI application
-│   ├── Commands/             # Command handlers (init, validate, index, docs, ai generate, etc.)
-│   ├── Agent/                # Copilot SDK integration
-│   │   ├── Tools/            # Custom tools for the AI agent
-│   │   └── Skills/           # Skill loader
-│   ├── Source/               # Document map builder, document index service, source doc reader
-│   ├── Index/                # _index.json builder and reader
-│   ├── Validation/           # Test case validation, dedup
-│   ├── Review/               # Interactive terminal review UI
-│   ├── Provider/             # Multi-provider chain with fallback
-│   ├── Git/                  # Branch/commit operations
-│   ├── Config/               # Configuration loader
-│   └── IO/                   # File writers
-├── Spectra.MCP/              # ASP.NET Core MCP server
-│   ├── Tools/                # MCP tool handlers
-│   ├── Engine/               # State machine, execution queue
-│   └── Storage/              # SQLite repository
-├── Spectra.Core/             # Shared library
-│   ├── Models/               # TestCase, Suite, RunState, etc.
-│   ├── Parsing/              # Markdown + YAML frontmatter parser
-│   ├── Validation/           # Schema validation rules
-│   └── Index/                # Index read/write
-└── Spectra.GitHub/           # GitHub integration (Octokit)
-
-spec-kit/                     # Architecture specs and ADRs
-tests/                        # Sample test suites (used for integration testing)
-docs/                         # Sample docs (used for testing generation)
-```
-
-## Conventions
-
-- **Language:** C# 12, .NET 8+
-- **Naming:** PascalCase for types and methods, camelCase for locals
-- **Async:** All I/O operations are async. Use `Async` suffix on method names.
-- **Nullability:** Nullable reference types enabled project-wide
-- **Tests:** xUnit for unit tests. Project: `Spectra.Tests`
-- **Configuration:** `spectra.config.json` at repo root. Model: `SpectraConfig` in Spectra.Core
-
-## Key Types
-
-When these exist, understand them before modifying related code:
-
-- `TestCase` — Parsed Markdown test with frontmatter metadata
-- `TestSuite` — Collection of tests in a folder with an _index.json
-- `MetadataIndex` — The _index.json model
-- `DocumentMap` — Lightweight listing of all docs in source folder
-- `DocumentIndex` — Pre-built document index with rich metadata (sections, entities, tokens, hashes)
-- `DocumentIndexEntry` — Per-document metadata in the index
-- `DocumentIndexService` — Orchestrates incremental/full index builds
-- `ExecutionRun` — A test execution run with state
-- `TestHandle` — Opaque reference to a test in a run
-- `SpectraConfig` — Root configuration model
-
-## Architecture Reference
-
-**Always read `spec-kit/architecture.md` before making structural changes.** It is the authoritative source for all design decisions: models, MCP tools, state machine, CLI commands, configuration schema, and data flows.
-
-## Spec-Driven Development
-
-This project uses [GitHub Spec Kit](https://github.com/github/spec-kit) for specification-driven development. Specs, plans, and tasks live in `.specify/`. Follow the spec-kit workflow for new features.
-
-## Implementation Guidelines
-
-### Spectra.Core
-- Models are plain C# records/classes, no framework dependencies
-- Parsing uses Markdig + YamlDotNet
-- Validation returns structured results (ParseResult with errors list), never throws
-
-### Spectra.CLI
-- Commands use System.CommandLine
-- Each command is a thin orchestrator — business logic lives in services
-- AI tools are registered via `AIFunctionFactory.Create()` from Microsoft.Extensions.AI
-- The Copilot SDK session is created by `CopilotSessionFactory`
-- Tool handlers validate before accepting — they are the safety gate
-
-### Spectra.MCP
-- MCP tools are ASP.NET Core endpoints using ModelContextProtocol.AspNetCore
-- State machine transitions must be validated before executing
-- SQLite access goes through a repository pattern
-- Every response includes run_status, progress, and next_expected_action
-
-## Active Technologies
-- C# 12, .NET 8+ + Spectra.CLI (command integration), Spectra.Core (config, parsing), System.CommandLine (interactive prompts) (004-test-generation-profile)
-- File-based (spectra.profile.md at repo root, _profile.md in suites) (004-test-generation-profile)
-
-## Recent Changes
-- 010-document-index: Added persistent `docs/_index.md` with per-document metadata, incremental updates via SHA-256 hashing, `spectra docs index` command, auto-refresh before AI generation
-- 004-test-generation-profile: Added C# 12, .NET 8+ + Spectra.CLI (command integration), Spectra.Core (config, parsing), System.CommandLine (interactive prompts)
+| You want to... | Read |
+|---|---|
+| Understand the current architecture, file layout, conventions | [`CLAUDE.md`](CLAUDE.md) |
+| Build and run locally | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) |
+| Use SPECTRA from VS Code Copilot Chat | [`USAGE.md`](USAGE.md) |
+| Customize prompts, profiles, branding | [`CUSTOMIZATION.md`](CUSTOMIZATION.md) |
+| Project knowledge and component reference | [`PROJECT-KNOWLEDGE.md`](PROJECT-KNOWLEDGE.md) |
+| Original architecture design spec | [`architecture-v5.md`](architecture-v5.md) (historical) |
+| Contribute | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+| Feature specifications | [`specs/`](specs/) (one directory per feature, numbered 001..NNN) |

CHANGELOG.md

@@ -5,13 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.36.0] - 2026-04-10
 
 ### Added
-- `spectra-quickstart` SKILL (12th bundled SKILL) — workflow-oriented onboarding for Copilot Chat. Triggered by phrases like "help me get started", "tutorial", "walk me through". Presents 12 SPECTRA workflows with example conversations.
-- `USAGE.md` — offline workflow reference written to the project root by `spectra init`. Mirrors the quickstart SKILL content in a format suitable for async onboarding, code review, and CI documentation. Hash-tracked by `update-skills` so customizations are preserved.
+- **Quickstart SKILL & USAGE.md** (spec 032) — `spectra-quickstart` is the 12th bundled SKILL: workflow-oriented onboarding for Copilot Chat triggered by phrases like "help me get started", "tutorial", "walk me through". Presents 12 SPECTRA workflows with example conversations. Companion `USAGE.md` written to project root by `spectra init` as an offline workflow reference. Both hash-tracked by `update-skills`. Generation and execution agent prompts defer onboarding requests to the new SKILL.
+- **Visible default profile format & customization guide** (spec 031) — `profiles/_default.yaml` and `CUSTOMIZATION.md` are now created by `spectra init` and bundled as embedded resources. Profile format is visible/editable instead of hardcoded. New `ProfileFormatLoader.LoadEmbeddedDefaultYaml()` and `LoadEmbeddedCustomizationGuide()` methods.
+- **Customizable root prompt templates** (spec 030) — `.spectra/prompts/` directory with 5 markdown templates (behavior-analysis, test-generation, criteria-extraction, critic-verification, test-update) controlling all AI operations. Templates use `{{placeholder}}`, `{{#if}}`, `{{#each}}` syntax. New `analysis.categories` config section with 6 default categories. New `spectra prompts list/show/reset/validate` CLI commands. New `spectra-prompts` SKILL (11th bundled SKILL).
 - `ProfileFormatLoader.LoadEmbeddedUsageGuide()` for resolving the bundled `USAGE.md` content.
-- Generation and execution agent prompts now defer onboarding requests to the `spectra-quickstart` SKILL.
+- Bumped Spectre.Console 0.54.0 → 0.55.0, GitHub.Copilot.SDK 0.2.0 → 0.2.1, Markdig 1.1.1 → 1.1.2 (Dependabot PRs #10, #11, #12).
 
 ## [1.35.0] - 2026-04-10
 

CONTRIBUTING.md

@@ -27,15 +27,15 @@ SPECTRA uses the GitHub Copilot SDK as its sole AI runtime. All AI generation an
 - Follow existing code style
 - Add tests for new functionality
 - Update documentation in `docs/` if the change affects user-facing behavior
-- Update `spec-kit/` if the change affects architecture
+- Use the spec-kit workflow for new features (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, `/speckit.implement`) — specs land under `specs/NNN-feature/`
 - Keep PRs focused — one concern per PR
 
 ### Documentation
 
 User-facing documentation lives in `docs/`. See the [documentation index](README.md#documentation) for the full list. Each piece of information should live in one place — don't duplicate content between files.
 
 ### Architecture Changes
-- Propose significant changes as an ADR (Architecture Decision Record) in `spec-kit/adr/`
+- Propose significant changes via the spec-kit workflow — start with `/speckit.specify`, then `/speckit.plan`
 - Discuss in an Issue before implementing
 
 ## Code of Conduct

README.md

@@ -32,7 +32,7 @@ SPECTRA reads your product documentation, generates comprehensive test suites, a
 
 - **Deterministic execution** — An MCP-based execution engine provides a state machine that any AI orchestrator can drive without holding state.
 
-- **Coverage visibility** — Three-dimensional coverage analysis: documentation, requirements, and automation. Visual dashboard included.
+- **Coverage visibility** — Three-dimensional coverage analysis: documentation, acceptance criteria, and automation. Visual dashboard included.
 
 - **No migration needed** — Integrates with Azure DevOps, Jira, Teams, Slack through their MCP servers. No data sync. No vendor lock-in.
 
@@ -58,7 +58,7 @@ Hallucinated steps are caught and rejected automatically.
 
 Three coverage dimensions tracked automatically:
 - **Documentation** — which docs have linked tests
-- **Requirements** — which requirements are tested
+- **Acceptance Criteria** — which criteria are tested
 - **Automation** — which tests have automation code
 
 ```bash
@@ -86,7 +86,7 @@ Bundled SKILL files let you use SPECTRA through natural language in Copilot Chat
 Say "generate test cases for checkout" and the SKILL handles CLI invocation, JSON parsing, and result presentation.
 
 ```bash
-spectra init                  # Creates 10 SKILLs + 2 agent prompts
+spectra init                  # Creates 12 SKILLs + 2 agent prompts
 spectra update-skills         # Update SKILLs when CLI is upgraded
 ```
 
@@ -105,7 +105,7 @@ dotnet tool install -g Spectra.CLI
 # Initialize (creates config, dirs, SKILL files, agent prompts)
 spectra init
 
-# Build the document index (also extracts requirements automatically)
+# Build the document index (also extracts acceptance criteria automatically)
 spectra docs index
 
 # Generate tests — interactive session with analysis, suggestions, and more

architecture-v5.md

@@ -1,7 +1,9 @@
 # AI-Native Manual Test Management System — Architecture Specification
 
+> **Historical design document.** This is the original architecture spec that guided initial implementation. It is NOT updated as the codebase evolves. For the current state of the system, read [`CLAUDE.md`](CLAUDE.md), [`PROJECT-KNOWLEDGE.md`](PROJECT-KNOWLEDGE.md), and the per-feature specs under [`specs/`](specs/). Treat this file as background reading for deep technical context, not as a source of truth.
+
 **Version:** 3.0 (Final Consolidated)
-**Status:** Ready for implementation scoping
+**Status:** Original design spec — superseded as implementation has evolved
 
 ---