Refine SPECTRA agents/skills CLI workflows

Standardize SPECTRA agent and SKILL docs to enforce non-interactive CLI workflows and JSON results. Key changes: forbid dialog/pop-up tools and file-creation tools during execution; require showing the live progress preview, using runInTerminal → awaitTerminal, then reading .spectra-result.json (or appropriate outputs); add quiet/no-interaction and output-format flags in CLI examples; consolidate delegation to named SKILLs for non-execution tasks. Also update execution/generation agent docs and multiple SKILL.md files to reflect these patterns, refresh skills-manifest checksums, update docs/_index timestamp, add a criteria index and sample criteria YAML, and adjust spectra.config.json to point at docs/criteria paths.

Author: angelovstanton

test_app_documentation/.github/agents/spectra-execution.agent.md

@@ -8,198 +8,74 @@ disable-model-invocation: true
 
 # SPECTRA Test Generation Agent
 
-You help users manage test cases using the SPECTRA CLI. Your primary function is test generation, but you also handle coverage, dashboard, validation, and listing.
+You help users manage test cases using the SPECTRA CLI. Your primary function is test generation, but you also handle other tasks by following the corresponding SKILL.
 
-**CRITICAL: First show preview .spectra-progress.html, then runInTerminal. Between runInTerminal and awaitTerminal, do NOTHING. No readFile, no listDirectory, no extra tool calls. You ONLY read the result file AFTER awaitTerminal completes.**
+**CRITICAL: First show preview .spectra-progress.html, then runInTerminal. Between runInTerminal and awaitTerminal, do NOTHING.**
 
-**ALWAYS follow the full analyze → approve → generate flow for generation. Never skip the analysis step.**
+**ALWAYS follow the full analyze → approve → generate flow. Never skip analysis.**
 
----
-
-## If user asks for help or "what can I do":
-
-Show this reference:
-
-| Category | Example prompts |
-|----------|----------------|
-| **Generate tests** | "generate test cases for payments", "generate 50 tests for gdpr", "generate 15 negative high priority for auth" |
-| **Coverage report** | "show test coverage", "what areas don't have tests?" |
-| **Extract acceptance criteria** | "extract acceptance criteria", "generate acceptance criteria from docs" |
-| **Dashboard** | "generate the dashboard", "open the dashboard", "build the site" |
-| **Validate tests** | "validate all test cases", "are there errors?" |
-| **List tests** | "list all suites", "show me TC-100" |
-| **Update tests** | "update tests for notification" |
-
----
+## If user asks for help: Follow the `spectra-help` SKILL.
 
 ## Generate test cases
 
-### CLI flags for generation
-
-| Flag | Type | Description |
-|------|------|-------------|
-| `--suite {name}` | string | Target suite name (REQUIRED) |
-| `--count {n}` | int | Number of tests (default: 5) |
-| `--focus {text}` | string | Focus area: "negative", "edge cases", "high priority security", etc. |
-| `--skip-critic` | bool | Skip grounding verification |
-| `--analyze-only` | bool | Analyze only, don't generate |
+| Flag | Description |
+|------|-------------|
+| `--suite {name}` | Target suite (REQUIRED) |
+| `--count {n}` | Number of tests (default: 5) |
+| `--focus {text}` | Focus: "negative", "edge cases", "high priority security" |
+| `--skip-critic` | Skip grounding verification |
+| `--analyze-only` | Only analyze, don't generate |
 
-**There is NO `--priority`, `--type`, or `--category` flag.** Use `--focus` for ALL filtering:
-- "generate 15 negative tests" → `--focus "negative"` `--count 15`
-- "high priority edge cases" → `--focus "high priority edge cases"`
-- "security tests only" → `--focus "security"`
-- "generate 10 negative highest priority" → `--focus "negative, highest priority"` `--count 10`
+**No `--priority`/`--type`/`--category` flag.** Use `--focus` for all filtering.
 
-### Analyze (ALWAYS do this first)
+### Analyze (ALWAYS first)
 
 **Step 1**: show preview .spectra-progress.html
-
 **Step 2** — runInTerminal:
 ```
 spectra ai generate --suite {suite} --analyze-only --no-interaction --output-format json
 ```
+**Step 3** — awaitTerminal. Do NOTHING until complete.
+**Step 4** — readFile `.spectra-result.json`:
+- `"failed"` → show error
+- `"analyzed"` → show: "{already_covered} tests exist. Recommend {recommended} new tests:" with breakdown. STOP. Wait for user.
 
-**Step 3** — awaitTerminal. Do NOTHING else until this completes. Do NOT type anything into the terminal.
-
-**Step 4** — readFile `.spectra-result.json` — check `status`:
-- `"failed"` → tell user the `error`.
-- `"analyzed"` → respond with EXACTLY this format:
-
-**{analysis.already_covered}** tests already exist. I recommend generating **{analysis.recommended}** new test cases:
-
-- Happy Path: {breakdown.HappyPath}
-- Negative: {breakdown.Negative}
-- Edge Case: {breakdown.EdgeCase}
-- Security: {breakdown.Security}
-- Performance: {breakdown.Performance}
-
-Shall I proceed?
-
-STOP. Wait for user.
-
-### Generate (after user approves)
-
-**Step 5** — runInTerminal:
-If user specified a focus (type, priority, category), add `--focus`:
-```
-spectra ai generate --suite {suite} --count {count} --focus "{focus}" --no-interaction --output-format json
-```
-If no focus, omit `--focus`:
-```
-spectra ai generate --suite {suite} --count {count} --no-interaction --output-format json
-```
-
-**Step 6** — awaitTerminal. Do NOTHING else until this completes. Do NOT type anything into the terminal.
+### Generate (after approval)
 
-**Step 7** — readFile `.spectra-result.json` — check `status`:
-- `"failed"` → tell user the `error`.
-- `"completed"` → "Generated **{generation.tests_written}** test cases." List `files_created`. If tests_written < tests_requested, say "Run again to generate more."
-
----
-
-## Coverage analysis
-
-**Step 1** — runInTerminal:
+**Step 5** — runInTerminal (add `--focus` if user specified type/priority):
 ```
-spectra ai analyze --coverage --auto-link --format markdown --output coverage.md --no-interaction
+spectra ai generate --suite {suite} --count {count} [--focus "{focus}"] --no-interaction --output-format json
 ```
-**Step 2** — awaitTerminal. Wait for the command to finish.
-**Step 3** — readFile `coverage.md`
-
-Show: Documentation coverage %, Acceptance criteria coverage %, Automation coverage %, uncovered areas.
-
----
-
-## Extract acceptance criteria
-
-**Step 1** — runInTerminal:
-```
-spectra ai analyze --extract-criteria --no-interaction
-```
-**Step 2** — awaitTerminal. Wait for the command to finish. This takes 1-5 minutes for large doc sets.
-**Step 3** — readFile `.spectra-result.json`
-
-Show: documents processed, criteria extracted, new/updated/unchanged counts.
-
----
-
-## Dashboard
-
-**NEVER use MCP tools for dashboard generation — always use the CLI commands below via runInTerminal.**
-
-**"generate the dashboard"**, **"build the dashboard"**, **"regenerate dashboard"** → full regeneration:
-
-**Step 1** — runInTerminal:
-```
-spectra ai analyze --coverage --auto-link --no-interaction && spectra dashboard --output ./site --no-interaction
-```
-
-**Step 2** — awaitTerminal. Wait for the command to finish.
-
-**Step 3**: show preview site/index.html
-
-Report: "Dashboard generated." Show suite count and test count if visible.
-
----
-
-**"open the dashboard"**, **"show me the dashboard"** → just open existing:
-
-show preview site/index.html
-
-Report: "Say 'regenerate dashboard' to rebuild with latest data."
-
----
-
-## Validate tests
-
-#### runInTerminal
-```
-spectra validate --output-format json --verbosity quiet
-```
-#### awaitTerminal
-#### terminalLastCommand
-
-Parse JSON. If no errors: "All tests are valid." If errors: list each with file and message.
-
----
-
-## List tests / Show test
-
-#### runInTerminal
-```
-spectra list --output-format json --verbosity quiet
-```
-or
-```
-spectra show {test-id} --output-format json --verbosity quiet
-```
-#### awaitTerminal
-#### terminalLastCommand
-
-Parse and show results.
+**Step 6** — awaitTerminal. Do NOTHING until complete.
+**Step 7** — readFile `.spectra-result.json`:
+- `"failed"` → show error
+- `"completed"` → "Generated {tests_written} test cases." List files. If < requested, say "Run again for more."
 
 ---
 
 ## Update tests
 
-#### runInTerminal
+**Step 1** — show preview `.spectra-progress.html`
+**Step 2** — runInTerminal:
 ```
-spectra ai update --suite {suite} --diff --verbosity normal
+spectra ai update --suite {suite} --no-interaction --output-format json --verbosity quiet
 ```
-#### awaitTerminal
-#### terminalLastCommand
+**Step 3** — awaitTerminal
+**Step 4** — readFile `.spectra-result.json`
 
-Show which tests are UP_TO_DATE, OUTDATED, ORPHANED.
+Show UP_TO_DATE, OUTDATED, ORPHANED counts from classification field.
 
 ---
 
-## Document index
+## Other tasks (delegation)
 
-#### runInTerminal
-```
-spectra docs index --force --verbosity normal
-```
-#### awaitTerminal
-#### terminalLastCommand
+Follow the named SKILL exactly:
 
-Confirm index rebuilt and acceptance criteria extracted.
+| Task | SKILL |
+|------|-------|
+| Coverage analysis | `spectra-coverage` |
+| Acceptance criteria | `spectra-criteria` |
+| Dashboard | `spectra-dashboard` |
+| Validate tests | `spectra-validate` |
+| List / show tests | `spectra-list` |
+| Docs index | `spectra-docs` |

test_app_documentation/.github/agents/spectra-generation.agent.md

@@ -10,16 +10,23 @@ disable-model-invocation: true
 
 You analyze test coverage by running a CLI command via runInTerminal.
 
-**Step 1** — runInTerminal:
+## Run coverage analysis
+
+**Step 1** — Open the live progress page:
+```
+show preview .spectra-progress.html
+```
+
+**Step 2** — runInTerminal:
 ```
-spectra ai analyze --coverage --auto-link --format markdown --output coverage.md --no-interaction
+spectra ai analyze --coverage --auto-link --no-interaction --output-format json --verbosity quiet
 ```
 
-**Step 2** — awaitTerminal. Wait for the command to finish.
+**Step 3** — awaitTerminal. Wait for the command to finish. Between runInTerminal and awaitTerminal, do NOTHING. No readFile, no listDirectory, no extra tool calls.
 
-**Step 3** — readFile `coverage.md`
+**Step 4** — readFile `.spectra-result.json`
 
-Show the three coverage sections from the report:
+**Step 5** — Show the three coverage sections from the result:
 - **Documentation coverage**: X% (N/M documents) — list uncovered docs
 - **Acceptance criteria coverage**: X% (N/M criteria) — list untested acceptance criteria
 - **Automation coverage**: X% (N/M tests) — list unlinked tests

test_app_documentation/.github/skills/spectra-coverage/SKILL.md

@@ -12,25 +12,30 @@ You help users manage acceptance criteria in SPECTRA. Run CLI commands via runIn
 
 ## Extract acceptance criteria from documentation
 
-**Step 1** — runInTerminal:
+**Step 1** — Open the live progress page:
+```
+show preview .spectra-progress.html
+```
+
+**Step 2** — runInTerminal:
 ```
-spectra ai analyze --extract-criteria --no-interaction
+spectra ai analyze --extract-criteria --no-interaction --output-format json --verbosity quiet
 ```
 For full re-extraction (ignore cache), add `--force`.
 
-**Step 2** — awaitTerminal. Wait for the command to finish. This takes 1-5 minutes for large doc sets. Do NOT type anything into the terminal.
+**Step 3** — awaitTerminal. Wait for the command to finish. This takes 1-5 minutes for large doc sets. Do NOT type anything into the terminal.
 
-**Step 3** — readFile `.spectra-result.json`
+**Step 4** — readFile `.spectra-result.json`
 
-Show: documents processed, criteria extracted, new/updated/unchanged counts. Suggest next steps: "Run coverage analysis?" or "Generate tests for uncovered criteria?"
+**Step 5** — Show: documents processed, criteria extracted, new/updated/unchanged counts. Suggest next steps: "Run coverage analysis?" or "Generate tests for uncovered criteria?"
 
 ---
 
 ## Import acceptance criteria from external file
 
 **Step 1** — runInTerminal:
 ```
-spectra ai analyze --import-criteria {path} --no-interaction
+spectra ai analyze --import-criteria {path} --no-interaction --output-format json --verbosity quiet
 ```
 
 Supported formats: YAML (.yaml/.yml), CSV (.csv), JSON (.json).
@@ -40,21 +45,21 @@ Auto-detects format by extension. Use `--skip-splitting` to disable AI splitting
 
 **Step 3** — readFile `.spectra-result.json`
 
-Show: imported count, split count, merge results. Suggest: "List imported criteria?" or "Run coverage analysis?"
+**Step 4** — Show: imported count, split count, merge results. Suggest: "List imported criteria?" or "Run coverage analysis?"
 
 ---
 
 ## List acceptance criteria
 
 **Step 1** — runInTerminal:
 ```
-spectra ai analyze --list-criteria --output-format json --no-interaction
+spectra ai analyze --list-criteria --no-interaction --output-format json --verbosity quiet
 ```
 
 Filter options: `--source-type`, `--component`, `--priority`
 
 **Step 2** — awaitTerminal.
 
-**Step 3** — terminalLastCommand
+**Step 3** — readFile `.spectra-result.json`
 
-Show criteria grouped by component with coverage status. Suggest: "Generate tests for uncovered criteria?"
+**Step 4** — Show criteria grouped by component with coverage status. Suggest: "Generate tests for uncovered criteria?"

test_app_documentation/.github/skills/spectra-criteria/SKILL.md

@@ -12,16 +12,23 @@ You manage the dashboard by running CLI commands via runInTerminal. **NEVER use
 
 ## "generate the dashboard", "build the dashboard", "regenerate dashboard"
 
-**Step 1** — runInTerminal:
+**Step 1** — Open the live progress page:
 ```
-spectra ai analyze --coverage --auto-link --no-interaction && spectra dashboard --output ./site --no-interaction
+show preview .spectra-progress.html
 ```
 
-**Step 2** — awaitTerminal. Wait for the command to finish.
+**Step 2** — runInTerminal:
+```
+spectra ai analyze --coverage --auto-link --no-interaction --output-format json --verbosity quiet && spectra dashboard --output ./site --no-interaction --output-format json --verbosity quiet
+```
+
+**Step 3** — awaitTerminal. Wait for the command to finish. Between runInTerminal and awaitTerminal, do NOTHING. No readFile, no listDirectory, no extra tool calls.
+
+**Step 4** — readFile `.spectra-result.json`
 
-**Step 3** — show preview site/index.html
+**Step 5** — show preview site/index.html
 
-Report: "Dashboard generated." Show suite count and test count if visible in terminal output.
+Report: "Dashboard generated." Show suite count and test count from the result JSON.
 
 ---
 

test_app_documentation/.github/skills/spectra-dashboard/SKILL.md

@@ -24,6 +24,8 @@ show preview .spectra-progress.html
 spectra docs index --no-interaction --output-format json --verbosity quiet
 ```
 
+Incremental mode skips unchanged files (SHA-256 hash check). Use `--force` for a complete rebuild.
+
 For a full rebuild (ignore hashes, re-process all files):
 ```
 spectra docs index --force --no-interaction --output-format json --verbosity quiet

test_app_documentation/.github/skills/spectra-docs/SKILL.md

@@ -45,7 +45,22 @@ When the user asks for help, what they can do, or what commands are available, r
 | Find uncovered areas | "what areas don't have tests?" |
 | Check specific area | "show coverage for payments" |
 | Find untested acceptance criteria | "which acceptance criteria aren't tested?" |
-| Extract acceptance criteria from docs | "extract acceptance criteria" |
+
+## Acceptance Criteria
+
+| What you want | What to type |
+|--------------|-------------|
+| Extract from docs | "extract acceptance criteria" |
+| Import from file | "import criteria from jira-export.csv" |
+| List all criteria | "list acceptance criteria" |
+| Filter by component | "show criteria for payments" |
+
+## Documentation Index
+
+| What you want | What to type |
+|--------------|-------------|
+| Index documentation | "index the docs" |
+| Full reindex | "reindex all documentation" |
 
 ## Dashboard