Merge branch '032-quickstart-skill-usage-guide' - quickstart SKILL & USAGE.md offline guide

Author: angelovstanton

CHANGELOG.md

@@ -5,6 +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]
+
+### 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.
+- `ProfileFormatLoader.LoadEmbeddedUsageGuide()` for resolving the bundled `USAGE.md` content.
+- Generation and execution agent prompts now defer onboarding requests to the `spectra-quickstart` SKILL.
+
 ## [1.35.0] - 2026-04-10
 
 ### Added

CLAUDE.md

@@ -209,6 +209,7 @@ spectra config list-automation-dirs                 # List dirs with existence s
 - **Tests:** xUnit with structured results (never throw on validation errors)
 
 ## Recent Changes
+- 032-quickstart-skill-usage-guide: ✅ COMPLETE - Quickstart SKILL & USAGE.md offline guide. New `spectra-quickstart` SKILL (12th bundled SKILL) — workflow-oriented onboarding that responds to "help me get started", "tutorial", "walk me through" with 12 workflow walkthroughs and example conversations. Teaching-only (no CLI execution); delegates actual workflow execution to the corresponding workflow SKILLs. New `USAGE.md` bundled doc written to project root by `spectra init` (offline mirror of the quickstart SKILL, free of in-chat tool references). Both artifacts hash-tracked by the existing `update-skills` system. New `ProfileFormatLoader.LoadEmbeddedUsageGuide()` method. New `InitHandler.CreateUsageGuideAsync` (gated by `--skip-skills`). Generation and execution agent prompts gain a `**QUICKSTART**` delegation line directing onboarding intents to the new SKILL. Updated SKILL count test (11→12). 7 new tests (quickstart SKILL content, USAGE.md content + offline-clean assertions, init creates both files, --skip-skills skips both files, both agents reference quickstart). 1434 total tests passing.
 - 030-prompt-templates: ✅ COMPLETE - Customizable root prompt templates. Introduced `.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 with built-in defaults as embedded resources. New `PlaceholderResolver`, `PromptTemplateParser`, `PromptTemplateLoader`, `BuiltInTemplates` in `Spectra.CLI/Prompts/`. Replaced hardcoded prompts in `BehaviorAnalyzer`, `CopilotGenerationAgent`, `CriteriaExtractor`, `CriticPromptBuilder` with template-driven approach (legacy fallback preserved). New `analysis.categories` config section with 6 default categories (happy_path, negative, edge_case, boundary, error_handling, security). New `spectra prompts list/show/reset/validate` CLI commands with JSON output. New `spectra-prompts` SKILL (11th bundled SKILL). Init creates `.spectra/prompts/` with defaults. `update-skills` tracks template hashes for safe updates. 65+ new tests. 1417 total tests passing.
 - 029-spectra-update-skill: ✅ COMPLETE - Added spectra-update SKILL (10th bundled SKILL) for test update workflow via Copilot Chat. SKILL wraps `spectra ai update` with progress page, result file, classification breakdown (UP_TO_DATE, OUTDATED, ORPHANED, REDUNDANT). Agent delegation tables updated (both generation and execution agents delegate update requests to SKILL). Extended `UpdateResult` with `success`, `totalTests`, `testsFlagged`, `flaggedTests`, `duration` fields. Generation agent inline update section replaced with delegation row. 6 new tests (SKILL content, step format, do-NOTHING instruction, tools list, agent delegation). Documentation updated (SKILL count 9→10). Version 1.35.0.
 - 028-coverage-criteria-fix: ✅ COMPLETE - Coverage semantics fix & criteria-generation pipeline. Fixed `TestCaseParser` to propagate `Criteria` field from frontmatter to `TestCase` (was missing). Wired criteria loading into `GenerateHandler`: loads per-doc `.criteria.yaml` files matching suite name and component, formats as context string, passes to `CopilotGenerationAgent.BuildFullPrompt()` via new `criteriaContext` parameter on `GenerateTestsAsync()`. `TestFileWriter` now always writes `criteria: []` field (even when empty) for visibility. Audit confirmed coverage analyzers already correct: `DocumentationCoverageAnalyzer` checks test existence via `source_refs`, `AcceptanceCriteriaCoverageAnalyzer` reads both `criteria` and legacy `requirements` fields. 4 new regression tests. 1354 total tests passing.

PROJECT-KNOWLEDGE.md

@@ -25,7 +25,7 @@ User → VS Code Copilot Chat → MCP Server → Test Execution → Reports
 | Component | Purpose |
 |-----------|---------|
 | **dashboard-site/** | Static HTML/JS dashboard template with D3.js visualizations |
-| **SKILLs** (10 files) | VS Code Copilot Chat integration — each SKILL wraps CLI commands |
+| **SKILLs** (12 files) | VS Code Copilot Chat integration — each SKILL wraps CLI commands or guides users |
 | **Agents** (2 files) | Copilot Chat agent prompts for generation and execution workflows |
 
 ## Technology Stack
@@ -187,7 +187,7 @@ criteria:
 
 ## VS Code Copilot Chat Integration
 
-### 10 Bundled SKILLs
+### 12 Bundled SKILLs
 | SKILL | Purpose |
 |-------|---------|
 | `spectra-generate` | Test generation (analyze → approve → generate flow) |
@@ -197,9 +197,17 @@ criteria:
 | `spectra-validate` | Test validation |
 | `spectra-list` | Test listing and browsing |
 | `spectra-init-profile` | Generation profile setup |
-| `spectra-help` | Command reference |
+| `spectra-help` | Command reference (terse, flag-oriented) |
 | `spectra-criteria` | Criteria extraction, import, listing |
 | `spectra-docs` | Documentation indexing with progress page |
+| `spectra-prompts` | Prompt template management (list/show/reset/validate) |
+| `spectra-quickstart` | Workflow-oriented onboarding & walkthroughs (12 workflows with example conversations) |
+
+### Bundled Project-Root Docs
+- `CUSTOMIZATION.md` — configuration & customization reference (profiles, prompts, branding).
+- `USAGE.md` — workflow guide for Copilot Chat usage (offline mirror of `spectra-quickstart`).
+
+Both are written by `spectra init` and tracked by the SKILL manifest hash system so `spectra update-skills` refreshes unmodified copies and preserves user edits.
 
 ### 2 Agent Prompts (Delegation Model)
 | Agent | Purpose |

README.md

@@ -134,6 +134,14 @@ spectra validate --output-format json --no-interaction
 
 See [Getting Started](docs/getting-started.md) for auth setup and detailed instructions.
 
+### Using SPECTRA from VS Code Copilot Chat
+
+After `spectra init`, the bundled `spectra-quickstart` SKILL turns Copilot Chat into a guided onboarding entry point. Open Copilot Chat in VS Code and ask:
+
+> "Help me get started"
+
+The assistant walks you through every workflow (test generation, criteria extraction, coverage, dashboard, execution, customization) with copyable example prompts. For an offline reference covering the same workflows, see the auto-generated [`USAGE.md`](USAGE.md) at your project root.
+
 ## Architecture
 
 ```

specs/032-quickstart-skill-usage-guide/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Quickstart SKILL & Usage Guide
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-04-10
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items pass on first iteration.
+- File paths (`.github/skills/spectra-quickstart/SKILL.md`, `USAGE.md`) are referenced as user-visible artifacts, not implementation details — they're the *deliverable* the user finds on disk after `init`.
+- Ready to proceed to `/speckit.plan`.

specs/032-quickstart-skill-usage-guide/contracts/init-contract.md

@@ -0,0 +1,93 @@
+# Contract: `spectra init` and `spectra update-skills` output for feature 032
+
+This document captures the user-visible contract changes introduced by this feature. There are no new commands or flags — only new files produced by existing commands.
+
+## `spectra init`
+
+### New artifacts written
+
+After a successful `spectra init` (without `--skip-skills`), the following NEW files MUST exist on disk:
+
+| Path | Purpose |
+|------|---------|
+| `.github/skills/spectra-quickstart/SKILL.md` | Quickstart SKILL (workflow-oriented onboarding for Copilot Chat) |
+| `USAGE.md` | Offline workflow reference (project-root markdown doc) |
+
+### Manifest updates
+
+The `.spectra/skills-manifest.json` file MUST contain SHA-256 hashes for both new files:
+
+```json
+{
+  "version": "1.0",
+  "files": {
+    "...existing entries...": "...",
+    ".github/skills/spectra-quickstart/SKILL.md": "<sha256-hex>",
+    "USAGE.md": "<sha256-hex>"
+  }
+}
+```
+
+### `--skip-skills` behavior
+
+When `spectra init --skip-skills` is invoked, NEITHER new file is created and NEITHER manifest entry is added. This matches the existing `--skip-skills` semantics for the other 11 SKILLs and for `CUSTOMIZATION.md`.
+
+### `--force` behavior
+
+When `spectra init --force` is invoked on a project that already has these files, both files are overwritten with the latest bundled content (matching existing `--force` semantics for `CUSTOMIZATION.md` and other bundled files).
+
+## `spectra update-skills`
+
+### Refresh behavior
+
+For each of the two new manifest entries:
+
+1. Compute the SHA-256 of the on-disk file.
+2. Compare against the manifest hash.
+3. **If equal** → file is unmodified by the user; overwrite with the current embedded content; update the manifest hash.
+4. **If not equal** → file has been customized; skip; do not touch the manifest.
+5. **If file missing** → write fresh from the embedded content; record hash.
+
+This is identical to the existing `update-skills` behavior for `CUSTOMIZATION.md` and the other SKILLs.
+
+### Output / reporting
+
+The existing `update-skills` summary table MUST include rows for the two new files showing one of: `created`, `updated`, `skipped (customized)`, `up-to-date`.
+
+## Quickstart SKILL frontmatter contract
+
+The bundled `spectra-quickstart.md` file MUST begin with a YAML frontmatter block:
+
+```yaml
+---
+name: SPECTRA Quickstart
+description: Guided onboarding and workflow walkthroughs for SPECTRA via Copilot Chat.
+---
+```
+
+The `name` and `description` fields are consumed by Copilot Chat to surface the SKILL to the user. The description MUST clearly identify it as an onboarding/walkthrough SKILL so the LLM picks it for "help me get started"-style intents.
+
+## Quickstart SKILL content contract
+
+The body of `spectra-quickstart.md` MUST contain (verifiable by tests):
+
+1. The literal string `## Available tools`.
+2. A workflow overview listing 11 distinct workflow names.
+3. A `## Workflow N:` header for each of the 11 workflows (N = 1..11).
+4. A `## Quick Troubleshooting` section.
+5. A `## Example user requests that trigger this SKILL` section with at least 10 trigger phrases.
+
+## USAGE.md content contract
+
+The body of `USAGE.md` MUST contain (verifiable by tests):
+
+1. The literal heading `# SPECTRA Usage Guide — VS Code Copilot Chat` (or similar — the existence of "SPECTRA Usage Guide" is sufficient).
+2. A `## Prerequisites` section.
+3. Sections covering all 11 workflows (verified by counting heading occurrences for the 11 workflow names: `Generating Test Cases`, `Extracting Acceptance Criteria`, `Importing Criteria`, `Coverage Analysis`, `Generating Dashboard`, `Validating Tests`, `Updating Tests`, `Executing Tests`, `Creating a Custom Profile`, `Indexing Documentation`, `Customizing SPECTRA`).
+4. A `## Troubleshooting` section.
+5. A "Complete Pipeline" or "Start to Finish" section describing the end-to-end flow.
+6. NO references to in-chat tool names (`runInTerminal`, `awaitTerminal`, `readFile`, `browser/openBrowserPage`).
+
+## Agent prompt contract
+
+After this feature lands, both `spectra-generation.agent.md` and `spectra-execution.agent.md` MUST contain a textual reference to `spectra-quickstart` (verifiable by tests with a substring assertion).

specs/032-quickstart-skill-usage-guide/data-model.md

@@ -0,0 +1,86 @@
+# Phase 1 — Data Model: Quickstart SKILL & Usage Guide
+
+This feature has no runtime data model — it ships static content. The "entities" are the artifacts produced and the manifest entries that track them.
+
+## Entities
+
+### 1. Quickstart SKILL file
+
+| Field | Value |
+|-------|-------|
+| **Embedded resource id** | `Spectra.CLI.Skills.Content.Skills.spectra-quickstart.md` |
+| **Source path** | `src/Spectra.CLI/Skills/Content/Skills/spectra-quickstart.md` |
+| **Output path** | `.github/skills/spectra-quickstart/SKILL.md` (in user project) |
+| **Manifest key** | `.github/skills/spectra-quickstart/SKILL.md` |
+| **Auto-loaded** | Yes — by `SkillResourceLoader.LoadAllSkills()` |
+| **Typed accessor** | `SkillContent.Quickstart` |
+| **Frontmatter** | `name: SPECTRA Quickstart`, `description: Guided onboarding and workflow walkthroughs for SPECTRA via Copilot Chat.` |
+| **Required content sections** | Tools list, workflow overview (11 workflows), per-workflow detail with example conversations, troubleshooting, trigger phrases |
+
+### 2. USAGE.md doc file
+
+| Field | Value |
+|-------|-------|
+| **Embedded resource id** | `Spectra.CLI.Skills.Content.Docs.USAGE.md` |
+| **Source path** | `src/Spectra.CLI/Skills/Content/Docs/USAGE.md` |
+| **Output path** | `USAGE.md` (project root) |
+| **Manifest key** | `USAGE.md` |
+| **Loader** | `ProfileFormatLoader.LoadEmbeddedUsageGuide()` (new method, mirrors `LoadEmbeddedCustomizationGuide`) |
+| **Required content sections** | Prerequisites, getting started, 11 workflows in offline form, troubleshooting, complete pipeline walk-through |
+
+### 3. SkillsManifest entries (existing entity, two new keys)
+
+The existing `SkillsManifest.Files` dictionary gains two new entries on init:
+
+```json
+{
+  "files": {
+    ".github/skills/spectra-quickstart/SKILL.md": "<sha256>",
+    "USAGE.md": "<sha256>"
+  }
+}
+```
+
+`update-skills` consults this manifest: if the user's on-disk file hash matches the manifest hash, the file is unmodified and may be refreshed; if it differs, the user has customized it and the file is skipped.
+
+### 4. Agent prompt files (existing entities, edited)
+
+| File | Change |
+|------|--------|
+| `src/Spectra.CLI/Skills/Content/Agents/spectra-generation.agent.md` | Add one delegation line: onboarding intents → spectra-quickstart SKILL |
+| `src/Spectra.CLI/Skills/Content/Agents/spectra-execution.agent.md` | Add one delegation line: onboarding intents → spectra-quickstart SKILL |
+
+## Relationships
+
+```
+spectra init
+   │
+   ├── writes ──► .github/skills/spectra-quickstart/SKILL.md  (from EmbeddedResource)
+   │                            │
+   │                            └── tracked by ──► SkillsManifest.Files[".github/skills/spectra-quickstart/SKILL.md"]
+   │
+   └── writes ──► USAGE.md  (from EmbeddedResource)
+                  │
+                  └── tracked by ──► SkillsManifest.Files["USAGE.md"]
+
+spectra update-skills
+   │
+   ├── for each manifest entry, compare on-disk hash vs stored hash
+   ├── if unchanged: refresh from EmbeddedResource, update stored hash
+   └── if changed:   skip (user customization preserved)
+
+Copilot Chat (user types "help me get started")
+   │
+   ├── generation agent receives intent
+   │     │
+   │     └── delegates to ──► spectra-quickstart SKILL
+   │
+   └── quickstart SKILL presents 11-workflow overview + example conversations
+```
+
+## State / lifecycle
+
+- **Created** by `spectra init` (or by `spectra update-skills` when missing).
+- **Updated** by `spectra update-skills` only when the user has not modified the file.
+- **Deleted** by manual user action (not managed by SPECTRA).
+- **No runtime mutation** — content is static between releases.