diff --git a/.gitattributes b/.gitattributes index 6018bc66..a7e167dd 100644 --- a/.gitattributes +++ b/.gitattributes @@ -3,3 +3,4 @@ # Spec 099: golden outputs are compared byte for byte (platform newlines included); git must not convert them. tests/Spectra.CLI.Tests/Golden/099/** -text +tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/** -text diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fcbefd0..71fbe4b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,41 @@ 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). +## [2.7.0] - 2026-10-27 — SPECTRA for the other AI agents (`spectra init --agent`) + +### Added + +- **`spectra init --agent `** installs SPECTRA for GitHub Copilot, Cursor, Devin (`windsurf`), Codex CLI, Gemini CLI + (enterprise), Antigravity CLI (`agy`), Kiro CLI and OpenCode, next to or instead of Claude Code: the 16 skills, the six + subagents in each agent's own format and tool names, and an always-on instructions file (`.github/instructions/`, + `.cursor/rules/`, `.devin/rules/`, `.agents/rules/`, `.kiro/steering/`, or one SPECTRA block in `AGENTS.md` / + `GEMINI.md` pointing at `.spectra/spectra.instructions.md`). `--agent auto` detects the agents already installed, else + the one agent whose folder is in the repository. Names, aliases and detection match BELLATRIX Agent, so both tools can be + installed in one repository. +- A skills folder several agents read is written once, and `.claude/skills/` / `.claude/agents/` are reused by agents + that read them when Claude is installed. +- `.spectra/manifest..json` per agent: re-runs refresh SPECTRA's files, skip files you edited (unless + `--regenerate`) and remove files a newer version no longer installs when you did not edit them. +- `spectra` allowlist entries for the agents that document a project-level one (`.cursor/cli.json`, `.devin/config.json`, + `opencode.json`), merged by key. +- `--dry-run` with `--agent` writes nothing and prints every planned file, decision and skip. +- On an initialised repository `--agent` adds agents without `--force` and leaves `spectra.config.json` and the Claude + files alone. +- New page: [Live verification checklist](docs/live-verification-agents.md) per agent. + +### Unchanged + +- `spectra init` without `--agent` writes exactly the same files as 2.6.0 (pinned by a golden test), plus one notice line + on stderr in human output naming the other agents. Skill, subagent and prompt content for Claude Code, and every + workflow (generation, critic, verdicts, repair, review, execution), are unchanged; the content for the other agents is + the same text with Claude-specific wording replaced at install time. +- `spectra update-skills` refreshes only the Claude install; re-run `spectra init --agent ` for the others. + +### Known limitation + +- The critic's isolated, mandatory run is enforced by the platform only in Claude Code. In the other agents the critic + runs when the agent follows the skill's instruction to start it. A critic gate enforced by the CLI is planned. + ## [2.6.0] - 2026-10-27 — Doc-change update workflow, stable criteria IDs, lower token use ### Highlights diff --git a/CLAUDE.md b/CLAUDE.md index 95b2ed2f..44ca07f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,7 +52,7 @@ dotnet run --project src/Spectra.CLI -- # Run the CLI # Global: --output-format json|human --no-interaction --verbosity quiet --dry-run --no-review # Setup -spectra init [--skip-skills] +spectra init [--skip-skills] [--agent |auto] [--regenerate] # --agent: copilot,cursor,devin,codex,gemini,antigravity,kiro,opencode spectra update-skills spectra config [ []] | spectra config add-automation-dir|remove-automation-dir|list-automation-dirs spectra prompts list|show|validate|reset [] [--raw] [--all] @@ -119,6 +119,7 @@ that drives the system under test is unrelated to SPECTRA's removed execution ad | Spec | Summary | |------|---------| +| 104 | `spectra init --agent` for copilot/cursor/devin/codex/gemini/antigravity/kiro/opencode (`src/Spectra.CLI/Install/`, neutral emit-time transform, `.spectra/manifest..json`); Claude install byte-identical (`ClaudeInstallGoldenTests`) | | 103 | Human review record (merged from `078-human-review-record`): `review-flagged --action`, `reviewed_by/at`, `--re-verify`, suppression, staged `--fix` review | | 102 | Review fixes for 101: critic uses the critic-verification template, case-insensitive ref grouping, no re-critic for unchanged repairs, `created:` lines, `Agent` tool name | | 101 | Token economy: critic gets cited sections (`--full-docs` = old input), critic runs in work subagents, lean skills + `reference.md`, agent frontmatter | diff --git a/Directory.Build.props b/Directory.Build.props index bc60df49..dbdf14ae 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -18,7 +18,7 @@ true - 2.6.0 + 2.7.0 Spectra Contributors Spectra Spectra diff --git a/FINDINGS-multi-client-gap-v2.md b/FINDINGS-multi-client-gap-v2.md new file mode 100644 index 00000000..47ff3fd7 --- /dev/null +++ b/FINDINGS-multi-client-gap-v2.md @@ -0,0 +1,127 @@ +# Findings v2: multi-agent install gap (re-verified on main after #47 and #58) + +**Date:** 2026-10-27 · **Base:** `61ea574` (main after #47, #58, #61, #62) · **Supersedes:** `FINDINGS-multi-client-gap.md` +(2026-06-18) · **Mode:** read-only investigation · **Tags:** CONFIRMED (file:line or doc URL) | INFERRED + +## 1. What changed since v1 (2026-06-18) + +| v1 said | Now | Tag | +|---|---|---| +| 15 skills | **16**: `spectra-review-flagged` was added (and it has **no `name:`** frontmatter key — the only one) | CONFIRMED `Skills/Content/Skills/spectra-review-flagged.md:1-4` | +| 1 agent (`spectra-critic`) | **6** subagents: analyst, critic, extractor, generator, repairer, updater (`*.agent.md`) | CONFIRMED `Skills/Content/Agents/` | +| no reference files | `spectra-generate/reference.md`, `spectra-update/reference.md` beside their SKILL.md | CONFIRMED `SkillInstallLayout.cs:16`, `InitHandler.cs:268-273` | +| critic frontmatter `model: claude-sonnet-4-6`, `disable-model-invocation: true`, `context: fork` | critic: `tools: [{{READONLY_TOOLS}}, Write]`, `model: {{CRITIC_MODEL}}` (rendered from `ai.critic.model`, default `sonnet`); the other five: `model: inherit`. **No `context: fork` / `disable-model-invocation` anywhere.** | CONFIRMED `Agents/*.agent.md` frontmatter, `AgentContent.cs:20-25` | +| "Task tool" wording, `{{GENERATE_TOOLS}}` = `…, Task` | Claude renamed Task → **Agent** (v2.1.63); `{{GENERATE_TOOLS}}` = `Read, Write, Edit, Bash, Glob, Grep, Agent`; prose says "with the Agent tool" | CONFIRMED `SkillResourceLoader.cs:20-22` | +| Codex: AGENTS.md only, "no skill-directory convention" | Codex reads **`.agents/skills//SKILL.md`** (CWD → repo root); `name` + `description` required | CONFIRMED https://learn.chatgpt.com/docs/build-skills | +| Gemini CLI = the consumer Google agent | Consumer Gemini CLI was replaced by **Antigravity CLI (`agy`)**; Gemini CLI stays as the enterprise (Gemini Code Assist) agent | CONFIRMED https://antigravity.google/docs/cli/gcli-migration/ | +| Kiro, OpenCode, Cursor, Devin not covered | covered below | — | +| `.github/agents/` fallback in `SkillInstallLayout.AgentPath` | gone: every agent goes to `.claude/agents/` (one rule) | CONFIRMED `SkillInstallLayout.cs:19-21` | + +## 2. What `spectra init` (no `--agent`) emits today — the Claude install + +Pinned by `tests/Spectra.CLI.Tests/Golden/ClaudeInstallGoldenTests.cs` (40 files, `Golden/104/init-fresh.txt`). + +- **Claude-owned:** `.claude/skills/<16 names>/SKILL.md`, `.claude/skills/{spectra-generate,spectra-update}/reference.md`, + `.claude/agents/<6 names>.agent.md`, `.claude/settings.json` (merge of `Bash(spectra *)`, `Write(.spectra/**)`, + `Edit(.spectra/**)` — `ClaudeSettingsInstaller.cs`). +- **Agent-neutral:** `spectra.config.json`, `docs/criteria/_criteria_index.yaml`, `docs/criteria/sample.criteria.yaml`, + `.spectra/prompts/<5>.md`, `profiles/_default.yaml`, `USAGE.md`, `CUSTOMIZATION.md`, `templates/bug-report.md`, + `.github/workflows/deploy-dashboard.yml`, `.gitignore` (marker-tracked patterns), `.spectra/skills-manifest.json`. +- The skills manifest (`.spectra/skills-manifest.json`, `{version, files{key→sha256}, gitignore_offered}`) records the + Claude files **and** the neutral prompts/profile/USAGE/CUSTOMIZATION; `update-skills` reads it. Hashes are of the + raw content (not line-ending-normalised) — `FileHasher.cs:14-18`. + +## 3. Claude-specific elements in the emitted content + +| Element | Where | Count | +|---|---|---| +| `tools: [...]` with Claude tool names (`Read, Write, Edit, Bash, Glob, Grep, Agent` / `Read, Grep, Glob, Bash`) | skill frontmatter (16), agent frontmatter (6) | 22 files | +| `model: inherit` / `model: {{CRITIC_MODEL}}` | agent frontmatter | 6 | +| missing `name:` (Agent Skills requires `name` = folder) | `spectra-review-flagged` | 1 | +| "with the Agent tool" (start a subagent) | generate, update, criteria skills; generator, repairer, updater agents | 14 hits / 6 files | +| "If you have no Agent tool, or your first Agent call fails…" (nesting fallback) | generator, repairer, updater | 3 | +| "with the Bash tool" | 15 files | 39 hits | +| "with the Write tool" / "the Write tool creates…" | 6 files | 7 hits | +| "with the Read tool", "Grep/Glob" | execute, generate | 3 + 4 | +| `.claude/skills/**` ("do not Glob `.claude/skills/**`") | generate, execute | 2 | +| "Claude Code" (product name in prose/description) | help, quickstart | 4 | +| `.claude/settings.json` (whole file format) | `ClaudeSettingsInstaller` | 1 | +| `context: fork`, `disable-model-invocation`, "Task tool", `CLAUDE.md`, `subagent_type`, `@agent-` | — | **0** (gone since v1) | + +None of these is in the agent-neutral files. The `spectra` CLI commands the skills run are agent-neutral (CONFIRMED v1 §Q4). + +## 4. Provider table (placement verified against official docs) + +Ported from BELLATRIX Agent's `docs/support-matrix.json` / `ProviderEmitters.cs` (same names, aliases, auto-detect +markers), re-checked against each provider's docs on 2026-10-27. `S` = the shared fragment `.spectra/spectra.instructions.md`. + +| Agent (`--agent`) | Instructions (always on) | Skills dirs read (native first) | Subagents | Project allowlist | Docs | +|---|---|---|---|---|---| +| `claude` | none today (unchanged) | `.claude/skills` | `.claude/agents/*.agent.md` | `.claude/settings.json` (today) | https://code.claude.com/docs/en/sub-agents | +| `copilot` | `.github/instructions/spectra.instructions.md` (`applyTo: "**"`) | `.github/skills`, `.claude/skills`, `.agents/skills` | `.github/agents/*.agent.md` (Copilot tool aliases; `agents:` allow-list); reuses `.claude/agents` when Claude is installed | none at project level → skipped | https://docs.github.com/en/copilot/concepts/agents/about-agent-skills · https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents | +| `cursor` | `.cursor/rules/spectra.mdc` (`alwaysApply: true`) | `.cursor/skills`, `.agents/skills`, `.claude/skills`, `.codex/skills` | `.cursor/agents/*.md` (wins a clash with `.claude/agents`; `readonly` boolean, no tool list) | `.cursor/cli.json` `permissions.allow: ["Shell(spectra)"]` | https://cursor.com/docs/subagents · https://cursor.com/docs/cli/reference/permissions | +| `devin` (alias `windsurf`) | `.devin/rules/spectra.md` (`trigger: always_on`) | `.devin/skills`, `.github/skills` | `.devin/agents/*.md` (`allowed-tools`, documented names `read/grep/glob/exec` only) | `.devin/config.json` `permissions.allow: ["Exec(spectra)"]` | https://docs.devin.ai/cli/extensibility · https://docs.devin.ai/cli/extensibility/rules.md · https://docs.devin.ai/cli/subagents.md · https://docs.devin.ai/cli/reference/permissions.md | +| `codex` | `AGENTS.md` marker block → `S` | `.agents/skills` | `.codex/agents/*.toml` (`name`, `description`, `developer_instructions`) | none (sandbox/approval policy only) → skipped | https://learn.chatgpt.com/docs/build-skills · https://developers.openai.com/codex/subagents · https://developers.openai.com/codex/guides/agents-md | +| `gemini` (enterprise) | `GEMINI.md` marker block `@./S` | `.agents/skills`, `.gemini/skills` | `.gemini/agents/*.md` (`kind: local`, Gemini tool names) | workspace policies are documented as **no effect** → skipped | https://geminicli.com/docs/core/subagents/ · https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md · https://geminicli.com/docs/reference/policy-engine | +| `antigravity` (alias `agy`) | `.agents/rules/spectra.md` (`trigger: always_on`; a rule without frontmatter is silently discarded) | `.agents/skills` | `.agents/agents//agent.md` (`tools` default `[]`; documented names only — an unknown name can hang the subagent) | none documented → skipped | https://antigravity.google/docs/rules/ · https://antigravity.google/docs/skills/ · https://antigravity.google/docs/subagents/ | +| `kiro` | `.kiro/steering/spectra.md` (`inclusion: always`) | `.kiro/skills` | `.kiro/agents/*.md` (`tools` category tags; custom agents load steering/skills only via `resources`) | per-agent only → skipped | https://kiro.dev/docs/custom-agents/creating/ · https://kiro.dev/docs/skills/ · https://kiro.dev/docs/tools/ | +| `opencode` | `AGENTS.md` marker block → `S` (shared with Codex) | `.opencode/skills`, `.agents/skills`, `.claude/skills` | `.opencode/agents/*.md` (`mode`, `permission`; file name = agent name) | `opencode.json` `permission.bash["spectra *"] = "allow"` | https://opencode.ai/v2/docs/agents/ · https://opencode.ai/docs/permissions/ | + +Every provider documents a project-level skills **and** instructions mechanism, so no STOP condition applies. + +**Forced delegation:** only Claude Code runs a subagent from a skill instruction as a platform-enforced, isolated step. +Everywhere else delegation is model-decided (Codex: only when asked; Gemini: `@name` or model choice; Copilot, Cursor, +Devin, Kiro, OpenCode, Antigravity: model-chosen). CONFIRMED v1 §Q3 + the subagent pages above. + +## 5. Decisions (pre-approved; recorded) + +1. **`--agent` omitted → claude, exactly as today**, plus one notice line naming the other agents. BELLATRIX's + auto-detect (existing manifests, else exactly one detected agent) is available as **`--agent auto`**; it never guesses + (none or several detected → usage error listing the choices). +2. **Claude path untouched.** The only change to existing code: `InitHandler.HandleAsync` gains `installClaude = true`, + which guards the two Claude-only calls (`CreateBundledSkillFilesAsync`, `ClaudeSettingsInstaller`). Default = today. +3. **New emitter layer** (`src/Spectra.CLI/Install/`), used only for non-Claude agents; one emitter per provider, as in + BELLATRIX. Claude itself is represented in the planner only to answer "is `.claude/skills` / `.claude/agents` present". +4. **Existing workspace:** `spectra init --agent ` on a workspace that already has `spectra.config.json` (and no + `--force`) installs only the non-Claude agents and leaves config and Claude files alone (today `init` would refuse); + `claude` in that list is reported as "managed by `spectra update-skills`". With `--force`, or on a fresh workspace, + the full init runs first. +5. **Skills are provider-neutral** (one content for every non-Claude agent), because several providers share one + directory (`.agents/skills`: Codex, Gemini, Antigravity, Cursor, OpenCode). Transform at emit time: drop the Claude + `tools:` key, add `name:` when missing, neutral wording ("with the Agent tool" → "as a subagent", "with the Bash + tool" → "in the shell", "the Write tool" → "your file-writing tool", "the Read tool" → "your file-reading tool", + "Grep/Glob" → "search", `.claude/skills/**` → "the skills folder", "Claude Code" → "your AI coding agent"). +6. **Subagents are per provider** (native format and tool names). All **6** subagents are emitted, not only the critic: + the skills delegate to the analyst/generator/updater/repairer/extractor too. Body = the same neutral transform. +7. **The critic keeps the Write tool.** It writes its verdict to `.spectra/verdicts/critic-verdict-.json`, which + `ingest-verdict` reads (today's workflow). A strictly read-only critic would break that, so it gets the smallest + documented set that keeps the write: read + search + shell + write. Consequences: Cursor gets **no** `readonly: true` + (it blocks "file edits and state-changing shell commands"); Kiro `["read", "write", "shell"]`; Devin has no documented + name for a write tool, so its agents stay unrestricted (BELLATRIX's rule: never list an undocumented name). +8. **`model:`** is dropped for every non-Claude agent (the value is a Claude alias). `ai.critic.model` stays Claude-only. +9. **Skill directory de-dup (set cover, as BELLATRIX):** `.claude/skills` first when Claude is selected or already + installed, then greedily the directory read by most uncovered agents. An agent that would read two copies gets a + warning. A reused `.claude/skills` keeps Claude's wording (it is Claude's file; the golden rule forbids changing it). +10. **Subagent reuse:** Copilot reuses `.claude/agents` when Claude is present (it reads them); Cursor always gets its + own copy (native wins a clash); the others always get native copies. +11. **Devin skills dirs** are `.devin/skills`, `.github/skills` — not `.claude/skills` as in BELLATRIX: the Devin docs + list only `.github/skills` as an import source for skills (subagents are imported from `.claude/`). +12. **Shared fragment** `.spectra/spectra.instructions.md` (Codex, Gemini, OpenCode); native fragments elsewhere. Same + neutral body everywhere, including a short "how to start a subagent in each agent" table and the critic rule. +13. **Host files (R1/R3):** `AGENTS.md` / `GEMINI.md` get exactly one `` block (distinct from + BELLATRIX's ``); bytes outside the block are never rewritten. +14. **Manifests:** `.spectra/manifest..json` per non-Claude agent (path + CRLF-normalised SHA-256); a file shared by + several agents is listed in each. `.spectra/skills-manifest.json` is not renamed or changed. A user-edited file is + skipped and reported unless `--regenerate`. +15. **Permissions** only where a project-level allowlist is documented (Cursor, Devin, OpenCode), merged by key; others + are skipped and `--dry-run` says so. +16. **`--dry-run` with `--agent`** writes nothing and prints the plan (every file per agent, decisions, skips). Without + `--agent`, `--dry-run` keeps today's behaviour. +17. **`update-skills` is unchanged**; re-running `spectra init --agent ` refreshes non-Claude agents (hash-gated). +18. **Namespace (R1–R8):** only `spectra-*` skills/subagents, `spectra.*` fragments and `.spectra/manifest.*`; files of + BELLATRIX (`bellatrix-*`, `.bellatrix/`) or anyone else are never read for writing, renamed or removed. + +## 6. Known limitation (to document) + +The critic's isolated-context guarantee is enforced by the platform only in Claude Code. In the other agents the critic +runs when the agent follows the skill instruction. A CLI-enforced critic gate is planned for a later version. diff --git a/PROGRESS-multi-agent.md b/PROGRESS-multi-agent.md new file mode 100644 index 00000000..e1bf5c1d --- /dev/null +++ b/PROGRESS-multi-agent.md @@ -0,0 +1,44 @@ +# Progress: `spectra init --agent` (multi-agent install, additive only) + +Resume from here in every new session. Brief: the "add the other AI agents to `spectra init`" task (s.0–s.4). +Golden rule: the Claude install stays byte-identical; ADD, don't change. + +## Status + +| Step | State | Notes | +|---|---|---| +| s.0 sync | done | baseline: see below | +| golden Claude test | done | `ClaudeInstallGoldenTests`, 40 files pinned (Golden/104) | +| s.1 investigation | done | `FINDINGS-multi-client-gap-v2.md`, `specs/104-multi-agent-init/spec.md` | +| s.2 implement | done | `src/Spectra.CLI/Install/` + `--agent`/`--regenerate`; Claude golden green | +| s.3 tests | done | 44 new/related tests green (incl. live bellatrix 3.1.1, both orders) | +| s.4 docs + release | done | README, getting-started, skills-integration, cli-reference, CHANGELOG 2.7.0, live checklist; version 2.7.0; packed to scratch (not published) | +| final push | todo | feature branch only, no merge, no PR | + +## s.0 sync (2026-10-27) + +- Local coverage deletions (49 files, 6,372 lines) saved in `stash@{0}` + ("local coverage-file deletions (saved before pulling 2026-10-27)"). Tracked changes only; the two untracked + files (`FINDINGS-update-generate-token-economy.md`, `spectra-token-economy-specs.zip`) stayed in place (no + collision with incoming paths). NOT re-applied — the user decides. +- Stashed paths changed upstream: 5 — `CoverageReportWriter.cs`, `GapAnalyzer.cs`, `GapPresenter.cs`, + `CriteriaIndex.cs`, `GapAnalyzerTests.cs`. Simulated apply (`git merge-tree`): does NOT apply cleanly — + modify/delete conflicts on `CoverageReportWriter.cs` and `CriteriaIndex.cs` (the other 3 were deleted upstream too). +- `main` fast-forwarded to `61ea574` (= origin/main). +- Baseline tests (Debug, project by project): Core 1244/1245 (1 timing test, see below), Execution 228, Integration 8, + CLI 2595/2596 (1 timing test). Both timing failures are environmental: `UpdateTriagePerformanceTests` fails in + its SETUP (writing 2,500 files took 4m33s vs a 60 s budget, disk throttled by the AV); the Core one passes in Release. + The same commit is green on GitHub CI (Linux, Release). Gate per task: build + Core/Execution/Integration in full + + the affected CLI classes; full CLI suite (43 min here) in the background at milestones. + +## Decisions (pre-approved design choices, recorded) + +18 decisions in `FINDINGS-multi-client-gap-v2.md` §5. Key ones: `--agent` omitted = Claude as today (+notice), +`--agent auto` = BELLATRIX detection; new layer in `src/Spectra.CLI/Install/`; only change to existing code is an +`installClaude = true` guard in `InitHandler`; skills neutral (shared dirs), subagents per provider (all 6); the critic +keeps Write (verdict file) so no Cursor `readonly`; allowlists only Cursor/Devin/OpenCode. + +## Next action + +Push the feature branch (no PR). Open item: the full CLI suite was stopped twice by Claude Code for low memory; run it +where memory allows (targeted classes: 538 green; Core/Execution/Integration green). diff --git a/README.md b/README.md index 9e7fa584..1241c6da 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,40 @@ spectra init # Creates the config, folders, 16 skills and 6 sub spectra update-skills # Update skills and agents when the CLI is upgraded (edited files are kept) ``` +### Other AI Agents + +`spectra init --agent ` also installs the skills, the six subagents and an always-on instructions file for other +AI coding agents. Without `--agent`, `spectra init` installs for Claude Code exactly as before. + +```bash +spectra init --agent copilot # one agent +spectra init --agent claude,copilot,codex # several (a skills folder they share is written once) +spectra init --agent auto # the agents already installed, or the one detected in the repo +spectra init --agent cursor --dry-run # list every file it would write; write nothing +``` + +| Agent (`--agent`) | Instructions | Skills | Subagents | +|---|---|---|---| +| `claude` | — | `.claude/skills/` | `.claude/agents/` | +| `copilot` | `.github/instructions/spectra.instructions.md` | `.github/skills/` (or reuses `.claude/skills/`) | `.github/agents/` (or reuses `.claude/agents/`) | +| `cursor` | `.cursor/rules/spectra.mdc` | `.cursor/skills/` (or reuses `.claude/skills/`, `.agents/skills/`) | `.cursor/agents/` | +| `devin` (`windsurf`) | `.devin/rules/spectra.md` | `.devin/skills/` | `.devin/agents/` | +| `codex` | a SPECTRA block in `AGENTS.md` | `.agents/skills/` | `.codex/agents/*.toml` | +| `gemini` (enterprise) | a SPECTRA block in `GEMINI.md` | `.agents/skills/` | `.gemini/agents/` | +| `antigravity` (`agy`) | `.agents/rules/spectra.md` | `.agents/skills/` | `.agents/agents/` | +| `kiro` | `.kiro/steering/spectra.md` | `.kiro/skills/` | `.kiro/agents/` | +| `opencode` | a SPECTRA block in `AGENTS.md` | `.opencode/skills/` (or reuses `.claude/skills/`, `.agents/skills/`) | `.opencode/agents/` | + +The names, aliases and detection match BELLATRIX Agent, so both tools can be installed in the same repository. Your +`AGENTS.md` / `GEMINI.md` keep their content; SPECTRA adds one marked block. A file you edit is never overwritten on a +re-run unless you pass `--regenerate`. + +> **Known limitation:** the critic's isolated, mandatory verification is enforced by the platform only in Claude Code. +> In the other agents the critic runs when the agent follows the skill's instruction to start it. A critic gate enforced +> by the CLI is planned for a later version. + +See [Skills Integration](docs/skills-integration.md#other-ai-agents) for the details per agent. + ### Generation Profiles Customize AI output with natural language profiles — detail level, negative scenario count, domain rules, formatting preferences. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 0c2a16f2..957d8a06 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -96,6 +96,31 @@ docs/criteria/_criteria_index.yaml`), `docs/`, `test-cases/`, `docs/criteria/_cr | `--interactive` / `-i` | Enable interactive setup | | `--no-interactive` | Disable interactive setup | | `--skip-skills` | Skip creation of SKILL and agent files | +| `--agent ` | Also install for other AI agents: `claude`, `copilot`, `cursor`, `devin` (alias `windsurf`), `codex`, `gemini`, `antigravity` (alias `agy`), `kiro`, `opencode`, comma-separated; or `auto` to detect. Omitted: Claude Code only, as before | +| `--regenerate` | With `--agent`: overwrite agent files you edited since SPECTRA wrote them | +| `--dry-run` (global) | With `--agent`: write nothing; print every planned file, decision and skip | + +**Other AI agents (`--agent`).** Each agent gets the 16 skills, the six subagents in its own format and an always-on +instructions file (or one SPECTRA block in `AGENTS.md` / `GEMINI.md`); see the per-agent table in +[Skills Integration](skills-integration.md#other-ai-agents). Without `--agent` the output is exactly the Claude Code +install above, plus one notice line on stderr (human output only) naming the other agents. + +- On a fresh repository, or with `--force`, the standard setup runs first; the Claude files are installed only when + `claude` is in the list. +- On an initialised repository (a `spectra.config.json` exists), `--agent` installs only the listed non-Claude agents and + leaves the config and the Claude files alone; `claude` in the list is reported as "refresh it with + `spectra update-skills`". +- `auto` uses the agents already installed (their `.spectra/manifest..json`, or Claude's skills), else the one + agent whose folder is in the repo (`.cursor`, `.kiro`, …). None or several → exit `2` with the choices. +- An unknown name → exit `2`. `windsurf` prints a notice and installs `devin`. +- Every file written for an agent is recorded in `.spectra/manifest..json` (path + SHA-256, line endings ignored). + A re-run skips files you edited (listed as "skipped (edited by you)") unless `--regenerate`, and removes files a newer + version no longer installs when you did not edit them. +- A `spectra` allowlist entry is merged into the agent's documented project settings — `.cursor/cli.json` + (`Shell(spectra)`), `.devin/config.json` (`Exec(spectra)`), `opencode.json` (`"spectra *": "allow"`) — by key, never + overwriting a value you set; a file with comments is left alone and reported. The other agents document no + project-level command allowlist, which `--dry-run` reports. +- `spectra update-skills` refreshes only the Claude install; re-run `spectra init --agent ` for the others. ### `spectra validate` diff --git a/docs/getting-started.md b/docs/getting-started.md index 0022dceb..ae91befb 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -91,7 +91,26 @@ MCP allowlist, because execution is CLI-only. See [Skills Integration](skills-in > The test **execution** agent is a native Claude Code skill (`.claude/skills/spectra-execute/`); it > orchestrates the run and launches the web console rather than driving a per-test loop in chat. -Use `spectra init --skip-skills` if you don't use Claude Code. +Use `spectra init --skip-skills` if you don't use an AI coding agent. + +### Using another AI agent + +`spectra init` installs for Claude Code. For GitHub Copilot, Cursor, Devin (Windsurf), Codex CLI, Gemini CLI, +Antigravity CLI, Kiro CLI or OpenCode, name the agent: + +```bash +spectra init --agent copilot # instead of Claude Code +spectra init --agent claude,cursor # several agents in one repository +spectra init --agent auto # detect the agent whose folder is in the repository +``` + +Each agent gets the same skills and subagents in its own folders, plus an always-on SPECTRA instructions file. Add +`--dry-run` to see every file first. On a repository that is already initialised, `--agent` adds the agents without +touching your configuration. The per-agent layout is in [Skills Integration](skills-integration.md#other-ai-agents). + +> Outside Claude Code, the agent decides when to start a subagent, so the critic runs when the agent follows the +> skill's instruction. Check it on your first run: every new test should get a verdict +> (`spectra ai audit-grounding --suite `). ## Add Your Documentation diff --git a/docs/live-verification-agents.md b/docs/live-verification-agents.md new file mode 100644 index 00000000..3671c902 --- /dev/null +++ b/docs/live-verification-agents.md @@ -0,0 +1,85 @@ +--- +title: Live Verification (AI Agents) +parent: User Guide +nav_order: 12 +--- + +# Live verification checklist: SPECTRA in each AI agent + +The automated tests check every file `spectra init --agent` writes, byte for byte. They cannot check that an agent +actually loads those files and follows them; that takes a person and a real session. Run this checklist once per agent +after a release, and record the results in the table at the end. + +Related: [Skills Integration](skills-integration.md#other-ai-agents) | [CLI Reference](cli-reference.md#spectra-init) + +## Setup (once) + +1. Install the CLI under test: `dotnet tool update -g Spectra.CLI --version `. +2. Create an empty folder with `git init` and one small document, e.g. `docs/login.md` with three or four testable rules + (a password length limit, a lockout after N failures, an error message). +3. Have the agent installed and signed in. + +## Per agent + +### A. Scaffold + +- [ ] `spectra init --agent --dry-run` lists the files from the table in + [Skills Integration](skills-integration.md#other-ai-agents) and writes nothing (`git status` is clean). +- [ ] `spectra init --agent ` exits 0 and prints the agent's line, its instructions file and its decisions. +- [ ] The instructions file, 16 `spectra-*` skill folders (or the reused folder named in the decisions) and six + `spectra-*` subagents exist; `.spectra/manifest..json` lists them. +- [ ] Running the same command again reports `0 written` and changes nothing (`git status` shows no new change). + +### B. Skills and instructions are visible + +- [ ] The agent lists the `spectra-*` skills (skills picker, `/skills`, or ask: "Which SPECTRA skills do you have?"). +- [ ] Ask: "What do the SPECTRA instructions say about the critic?" The answer mentions `spectra-critic` and that it + verifies every generated test. This shows the always-on instructions file is loaded. +- [ ] The agent lists the SPECTRA subagents (subagent list, `/agents`, or ask). + +### C. One generate run + +- [ ] Ask: "Generate test cases for the login documentation." The agent uses the `spectra-generate` skill: it runs + `spectra ai compile-analysis-prompt`, starts `spectra-analyst`, shows a recommendation and asks before generating. +- [ ] After you confirm, it starts `spectra-generator` for the batch and `spectra ai ingest-tests` writes the tests: + `spectra list --suite ` shows them. +- [ ] The run made no direct edits to `test-cases/**` or `.spectra/**` other than through `spectra` commands and the + staging files the skill names. + +### D. The critic was invoked + +- [ ] `.spectra/verdicts/critic-verdict-.json` exists for every new test. +- [ ] `spectra ai audit-grounding --suite ` shows a verdict (`grounded`, `partial` or `hallucinated`) for every new + test and no `critic` in `action_needed`. +- [ ] If any test was `partial`, the repair ran (`spectra-repairer`) and the test was verified again. + +Where the agent did not start the critic on its own (section D fails), note how it behaved. This is the known +limitation: outside Claude Code, delegation is the agent's choice. Do not fix it by hand-writing verdict files. + +## Notes per agent + +| Agent | How to see skills | How to see subagents | Delegation to watch for | +|---|---|---|---| +| Claude Code | `/skills` | `/agents` | `spectra-analyst`, `spectra-generator`, `spectra-critic` subagent turns | +| GitHub Copilot | skills list in chat / `copilot` CLI | agent picker (`.github/agents`, or `.claude/agents` when reused) | `runSubagent` / `agent` tool calls | +| Cursor | Agent chat → skills | `.cursor/agents` in settings | subagent (Task) calls by name | +| Devin | skills list | custom subagents list | delegation to the named profile | +| Codex CLI | `/skills` | `.codex/agents` | ask it explicitly to run `spectra-critic` if it does not | +| Gemini CLI | `/skills` | `/agents` | `@spectra-critic` | +| Antigravity CLI | skills panel | `/agents` panel | `invoke_subagent` by the main agent | +| Kiro CLI | `/skills` (or the agent's `resources`) | `/agent list` | subagent named in plain language | +| OpenCode | skills list | `@` completion | `@spectra-critic` | + +## Results + +| `--agent` | Agent version | A Scaffold | B Visible | C Generate | D Critic | Notes | Date / who | +|---|---|---|---|---|---|---|---| +| `--agent claude` | | | | | | | | +| `--agent copilot` | | | | | | | | +| `--agent cursor` | | | | | | | | +| `--agent devin` | | | | | | | | +| `--agent codex` | | | | | | | | +| `--agent gemini` | | | | | | | | +| `--agent antigravity` | | | | | | | | +| `--agent kiro` | | | | | | | | +| `--agent opencode` | | | | | | | | diff --git a/docs/skills-integration.md b/docs/skills-integration.md index ed01929c..6df75f63 100644 --- a/docs/skills-integration.md +++ b/docs/skills-integration.md @@ -176,11 +176,68 @@ spectra update-skills - User-modified files are preserved (skipped with warning) - Missing files are recreated +## Other AI Agents + +`spectra init --agent ` installs the same skills and subagents for other AI coding agents, in each agent's own +layout. Without `--agent`, `spectra init` installs for Claude Code exactly as described above. + +```bash +spectra init --agent copilot,codex # comma-separated; claude can be in the list too +spectra init --agent auto # the agents already installed, else the one agent detected in the repo +spectra init --agent kiro --dry-run # print every file it would write, the decisions and the skips +spectra init --agent kiro --regenerate # also overwrite agent files you edited +``` + +Accepted names: `claude`, `copilot`, `cursor`, `devin`, `codex`, `gemini`, `antigravity`, `kiro`, `opencode`; `windsurf` +is accepted for `devin` (renamed Devin Desktop) and `agy` for `antigravity`. On a repository that is already +initialised, `--agent` adds the agents without `--force` and leaves `spectra.config.json` and the Claude files alone. + +| Agent | Always-on instructions | Skills | Subagents | Starting a subagent | `spectra` allowlist | +|---|---|---|---|---|---| +| Claude Code | — | `.claude/skills/` | `.claude/agents/*.agent.md` | platform-enforced | `.claude/settings.json` | +| GitHub Copilot | `.github/instructions/spectra.instructions.md` (`applyTo: "**"`) | `.github/skills/` (reuses `.claude/skills/`) | `.github/agents/*.agent.md` (reuses `.claude/agents/`) | the `agent` tool, by name | — | +| Cursor | `.cursor/rules/spectra.mdc` (`alwaysApply`) | `.cursor/skills/` (reuses `.claude/skills/` or `.agents/skills/`) | `.cursor/agents/*.md` | by name, or `/name` | `.cursor/cli.json`: `Shell(spectra)` | +| Devin | `.devin/rules/spectra.md` (`always_on`) | `.devin/skills/` | `.devin/agents/*.md` | by name | `.devin/config.json`: `Exec(spectra)` | +| Codex CLI | SPECTRA block in `AGENTS.md` → `.spectra/spectra.instructions.md` | `.agents/skills/` | `.codex/agents/*.toml` | ask for it by name | — | +| Gemini CLI | SPECTRA block in `GEMINI.md` importing `.spectra/spectra.instructions.md` | `.agents/skills/` | `.gemini/agents/*.md` | `@name` | — | +| Antigravity CLI | `.agents/rules/spectra.md` (`always_on`) | `.agents/skills/` | `.agents/agents//agent.md` | by name | — | +| Kiro CLI | `.kiro/steering/spectra.md` (`inclusion: always`) | `.kiro/skills/` | `.kiro/agents/*.md` (with the steering file and skills as `resources`) | by name | — | +| OpenCode | SPECTRA block in `AGENTS.md` → `.spectra/spectra.instructions.md` | `.opencode/skills/` (reuses `.claude/skills/` or `.agents/skills/`) | `.opencode/agents/*.md` | `@name` | `opencode.json`: `"spectra *": "allow"` | + +**What is installed.** The 16 skills (with the two reference files), the six subagents (`spectra-analyst`, +`spectra-generator`, `spectra-updater`, `spectra-repairer`, `spectra-extractor`, `spectra-critic`) and one always-on +instructions file. The skill and subagent instructions are the same as for Claude Code; only Claude-specific wording is +replaced (for example "start the subagent" instead of "with the Agent tool") and each subagent gets the agent's own +frontmatter and tool names. The critic keeps the tools it has today, including writing its verdict file. + +**Shared folders are written once.** Several agents read the same skills folder (`.agents/skills/` is read by Codex, +Gemini, Antigravity, Cursor and OpenCode), so `init` picks the fewest folders that reach every selected agent and reuses +`.claude/skills/` when Claude is installed. When an agent would see two copies anyway, `init` prints a warning. + +**Re-runs and your edits.** Each agent has a manifest, `.spectra/manifest..json`, with a hash of every file +SPECTRA wrote for it. Re-running `spectra init --agent …` refreshes those files, skips any file you edited (and says so) +unless you pass `--regenerate`, and removes files a newer version no longer installs if you did not edit them. +`spectra update-skills` refreshes only the Claude install; to refresh another agent after upgrading the CLI, re-run +`spectra init --agent `. + +**Your files.** `AGENTS.md` and `GEMINI.md` belong to you: SPECTRA adds one block between +`` and `` and never changes anything outside it. Allowlist entries are +merged into your settings file by key; a value you already set is kept, and a file with comments is left alone (add the +entry by hand). SPECTRA writes only `spectra-*` skills and subagents, `spectra.*` instruction files and +`.spectra/manifest.*.json`, so it can be installed next to BELLATRIX Agent (`bellatrix-*`, its own +`` block) in any order. + +> **Known limitation.** In Claude Code the critic runs as an isolated subagent that the platform starts as a mandatory +> step. The other agents choose when to delegate, so there the critic runs when the agent follows the skill's +> instruction to start it. A critic gate enforced by the CLI is planned for a later version. + +To check an installation by hand, follow the [live verification checklist](live-verification-agents.md). + ## Skipping SKILLs -For projects that don't use Claude Code: +For projects that don't use an AI coding agent: ```bash spectra init --skip-skills ``` -This creates only core files (config, directories, templates) without the `.claude/skills/` SKILLs or the `.claude/agents/` critic subagent. +This creates only core files (config, directories, templates) without the `.claude/skills/` SKILLs or the `.claude/agents/` critic subagent. With `--agent`, `--skip-skills` installs no agent files either. diff --git a/specs/104-multi-agent-init/spec.md b/specs/104-multi-agent-init/spec.md new file mode 100644 index 00000000..6df34100 --- /dev/null +++ b/specs/104-multi-agent-init/spec.md @@ -0,0 +1,84 @@ +# Feature Specification: `spectra init --agent` — install SPECTRA for the other AI agents (additive only) + +**Feature Branch**: `104-multi-agent-init` +**Created**: 2026-10-27 +**Status**: In progress +**Investigation**: [`FINDINGS-multi-client-gap-v2.md`](../../FINDINGS-multi-client-gap-v2.md) (provider table, decisions) + +## Overview + +`spectra init` installs SPECTRA's skills and subagents for Claude Code only. This feature adds `--agent ` so the +same skills, subagents and an always-on instructions fragment are also installed for GitHub Copilot, Cursor, Devin +(alias `windsurf`), Codex CLI, Gemini CLI (enterprise), Antigravity CLI (alias `agy`), Kiro CLI and OpenCode — with +the agent names, aliases and auto-detect of BELLATRIX Agent, so both tools can be installed side by side in one repo. + +**Golden rule: add, don't change.** `spectra init` without `--agent` installs exactly what it installs today, byte for +byte. No workflow logic (generation, critic, verdicts, repair, review, execution) and no installed Claude content changes. + +## User Scenarios & Testing + +### User Story 1 — A Copilot / Cursor / … user installs SPECTRA for their agent (P1) + +`spectra init --agent cursor` installs the skills, the six subagents and an always-on rule in Cursor's own layout, and +writes no `.claude/` file. The user asks Cursor to generate tests and the skill drives the same `spectra` commands. + +**Acceptance**: each agent's emitted files equal its golden file; the skills are readable by that agent (Agent Skills +format, `name` = folder); the subagents use that agent's format and documented tool names; no Claude-only wording or +frontmatter key remains in the emitted content. + +### User Story 2 — A team using several agents installs them together (P1) + +`spectra init --agent claude,copilot,codex,gemini` installs each agent once; a skill directory that several agents read is +written once (Claude's `.claude/skills` is reused where the agent reads it); the Claude files are byte-identical to a +plain `spectra init`. + +**Acceptance**: all-agents coexistence test; per-agent re-run (`--regenerate`) is byte-stable; the Claude golden passes. + +### User Story 3 — An existing Claude workspace adds another agent (P2) + +In a repo already initialised for Claude, `spectra init --agent copilot` adds Copilot without `--force`, without touching +`spectra.config.json`, the Claude files or `.spectra/skills-manifest.json`. + +### User Story 4 — SPECTRA and BELLATRIX Agent in one repo (P2) + +`bellatrix init` and `spectra init` for the same agents, in either order, leave each other's files untouched: distinct +marker blocks in `AGENTS.md` / `GEMINI.md`, distinct fragments, unique skill and subagent names. + +### Edge cases + +- `--agent` omitted → Claude, as today, plus one notice line; `--agent auto` detects (manifests, else exactly one agent's + markers; none or several → usage error listing the choices). +- Unknown agent name → usage error listing the valid names; `windsurf` → `devin` with a notice; `agy` → `antigravity`. +- A file the user edited since SPECTRA wrote it is skipped and reported, unless `--regenerate`. +- Human-owned `AGENTS.md` / `GEMINI.md`: one marker block only, bytes outside it untouched (R1). +- `--dry-run` with `--agent` writes nothing and lists every planned file, decision and skip. + +## Requirements + +- **FR-001** `spectra init --agent ` accepts `claude, copilot, cursor, devin, codex, gemini, antigravity, kiro, + opencode`, aliases `windsurf`→`devin`, `agy`→`antigravity`, and `auto`; comma-separated; canonical order; de-duplicated. +- **FR-002** Without `--agent`, init's output is byte-identical to 61ea574 (`ClaudeInstallGoldenTests`). +- **FR-003** Per agent: the native instructions fragment (or one marker block in `AGENTS.md` / `GEMINI.md` pointing at + `.spectra/spectra.instructions.md`), the 16 skills (+ reference files) in the agent's skills directory, the 6 subagents + in the agent's native format — see the provider table in the findings. +- **FR-004** Content for other agents is the embedded Claude content passed through a transform at emit time: neutral + wording, Claude-only frontmatter removed or mapped, provider tool names in subagent frontmatter. Source files unchanged. +- **FR-005** Skill directories are de-duplicated by set cover (`.claude/skills` first when Claude is present). +- **FR-006** `.spectra/manifest..json` per non-Claude agent (CRLF-normalised SHA-256); user-edited files skipped + unless `--regenerate`; files an agent no longer plans are retired only if unedited. +- **FR-007** Project-level command allowlists only where documented (Cursor, Devin, OpenCode), merged by key. +- **FR-008** Namespace contract R1–R8: only `spectra-*` / `spectra.*` / `.spectra/manifest.*` are written or removed. +- **FR-009** The critic keeps today's instructions; where delegation is not platform-enforced the skill text still tells + the agent to run the critic subagent. No new gate, file or workflow step. + +## Success Criteria + +- **SC-001** The Claude golden test stays green through the whole feature. +- **SC-002** A golden file per agent; all-agents coexistence and per-agent `--regenerate` byte-stability tests pass. +- **SC-003** Coexistence with BELLATRIX (recorded fixture of `bellatrix init`, both orders) leaves both sides intact. +- **SC-004** Full suite green (baseline 4,073 + new tests). + +## Out of Scope + +ImageSharp, System.CommandLine migration (the new option uses the current API), Dependabot, `update-skills` for the new +agents, a CLI-enforced critic gate (planned later), MCP registration. diff --git a/src/Spectra.CLI/Commands/Init/InitCommand.cs b/src/Spectra.CLI/Commands/Init/InitCommand.cs index ab2ecfed..62232711 100644 --- a/src/Spectra.CLI/Commands/Init/InitCommand.cs +++ b/src/Spectra.CLI/Commands/Init/InitCommand.cs @@ -35,12 +35,25 @@ public static Command Create() getDefaultValue: () => false, description: "Skip creation of SKILL and agent files"); + // Spec 104: install for other AI agents too. Omitted → Claude Code, exactly as before. + var agentOption = new Option( + name: "--agent", + description: "AI agents to install SPECTRA for, comma-separated: " + string.Join(", ", Install.AgentSelection.Names) + + " (aliases: windsurf → devin, agy → antigravity), or auto to detect. Default: claude"); + + var regenerateOption = new Option( + name: "--regenerate", + getDefaultValue: () => false, + description: "With --agent: overwrite agent files you edited since SPECTRA wrote them"); + var command = new Command("init", "Initialize SPECTRA in this repository") { forceOption, interactiveOption, noInteractiveOption, - skipSkillsOption + skipSkillsOption, + agentOption, + regenerateOption }; command.SetHandler(async (InvocationContext context) => @@ -72,7 +85,26 @@ public static Command Create() var logger = LoggingSetup.CreateLogger(verbosity); var handler = new InitHandler(logger, interactive: isInteractive, outputFormat: outputFormat); - context.ExitCode = await handler.HandleAsync(force, skipSkills, context.GetCancellationToken()); + var agent = context.ParseResult.GetValueForOption(agentOption); + if (agent is null) + { + context.ExitCode = await handler.HandleAsync(force, skipSkills, context.GetCancellationToken()); + // Human mode only: JSON-mode output (scripts, the 099 golden) stays exactly as before. + if (context.ExitCode == ExitCodes.Success && outputFormat != OutputFormat.Json) + { + Console.Error.WriteLine( + $"[spectra init] Installed for Claude Code. Other agents: spectra init --agent <{Install.AgentSelection.OthersList}> (comma-separated)."); + } + + return; + } + + var output = outputFormat == OutputFormat.Json ? Console.Error : Console.Out; + context.ExitCode = await Install.AgentInitRunner.RunAsync( + handler, Directory.GetCurrentDirectory(), agent, force, skipSkills, + context.ParseResult.GetValueForOption(regenerateOption), + context.ParseResult.GetValueForOption(GlobalOptions.DryRunOption), + output, Console.Error, context.GetCancellationToken()); }); return command; diff --git a/src/Spectra.CLI/Commands/Init/InitHandler.cs b/src/Spectra.CLI/Commands/Init/InitHandler.cs index 98be242d..764b5ba2 100644 --- a/src/Spectra.CLI/Commands/Init/InitHandler.cs +++ b/src/Spectra.CLI/Commands/Init/InitHandler.cs @@ -40,8 +40,10 @@ public InitHandler(ILogger logger, string? workingDirectory = null, /// Initializes SPECTRA in the current directory. /// /// Overwrite existing configuration if true + /// Spec 104: false when --agent leaves Claude out — skips only the Claude files + /// (.claude/skills, .claude/agents, .claude/settings.json); everything else is unchanged. /// Exit code - public async Task HandleAsync(bool force, bool skipSkills = false, CancellationToken ct = default) + public async Task HandleAsync(bool force, bool skipSkills = false, CancellationToken ct = default, bool installClaude = true) { try { @@ -64,7 +66,10 @@ public async Task HandleAsync(bool force, bool skipSkills = false, Cancella if (!skipSkills) { // Create bundled SKILL files (incl. the execution skill under .claude/skills/) - await CreateBundledSkillFilesAsync(force, ct); + if (installClaude) + { + await CreateBundledSkillFilesAsync(force, ct); + } // Create offline usage guide (USAGE.md) await CreateUsageGuideAsync(force, ct); @@ -80,7 +85,10 @@ public async Task HandleAsync(bool force, bool skipSkills = false, Cancella await CreateDeployWorkflowAsync(ct); // Emit .claude/settings.json with spectra CLI + .spectra/ write permissions - await Skills.ClaudeSettingsInstaller.EnsureInstalledAsync(_workingDirectory, ct); + if (installClaude) + { + await Skills.ClaudeSettingsInstaller.EnsureInstalledAsync(_workingDirectory, ct); + } // Update .gitignore await UpdateGitIgnoreAsync(ct); @@ -96,7 +104,10 @@ public async Task HandleAsync(bool force, bool skipSkills = false, Cancella _logger.LogInformation(" - {ConfigPath}", ConfigFileName); _logger.LogInformation(" - {DocsDir}/", DocsDir); _logger.LogInformation(" - {TestsDir}/", TestsDir); - _logger.LogInformation(" - .claude/skills/spectra-execute/SKILL.md"); + if (installClaude) + { + _logger.LogInformation(" - .claude/skills/spectra-execute/SKILL.md"); + } _logger.LogInformation(" - {WorkflowPath}", DeployWorkflowPath); _logger.LogInformation(""); _logger.LogInformation(" - {TemplatePath}", BugReportTemplatePath); diff --git a/src/Spectra.CLI/Install/AgentInitRunner.cs b/src/Spectra.CLI/Install/AgentInitRunner.cs new file mode 100644 index 00000000..20122c76 --- /dev/null +++ b/src/Spectra.CLI/Install/AgentInitRunner.cs @@ -0,0 +1,122 @@ +using Spectra.CLI.Commands.Init; +using Spectra.CLI.Infrastructure; + +namespace Spectra.CLI.Install; + +/// +/// Spec 104: spectra init --agent <list>. On a fresh workspace (or with --force) it runs the unchanged +/// workspace setup first — with the Claude files only when claude is in the list — then installs every other agent. +/// On an initialised workspace it installs only the other agents and leaves the config and the Claude files alone (Claude +/// is refreshed by spectra update-skills). With --dry-run it writes nothing and lists the plan. +/// +public static class AgentInitRunner +{ + private const string Tag = "[spectra init]"; + + public static async Task RunAsync( + InitHandler handler, string root, string agentValue, bool force, bool skipSkills, bool regenerate, bool dryRun, + TextWriter output, TextWriter notices, CancellationToken ct) + { + IReadOnlyList agents; + try + { + agents = AgentSelection.Parse(agentValue, root, notices); + } + catch (AgentSelectionException ex) + { + notices.WriteLine($"{Tag} error: {ex.Message}"); + return ExitCodes.ValidationError; + } + + var claudeSelected = agents.Contains("claude"); + var fullInit = force || !File.Exists(Path.Combine(root, "spectra.config.json")); + var claudePresent = (claudeSelected && fullInit && !skipSkills) || AgentSelection.ClaudeInstalled(root); + + if (dryRun) + { + output.WriteLine($"{Tag} dry run — nothing is written. Agents: {string.Join(", ", agents)}."); + output.WriteLine(fullInit + ? $"{Tag} workspace: the standard setup (spectra.config.json, docs/, test-cases/, .spectra/prompts/, profiles/, USAGE.md, CUSTOMIZATION.md, templates/, .gitignore entries, the dashboard workflow)." + : $"{Tag} workspace: already initialised — spectra.config.json is left as it is."); + } + else if (fullInit) + { + var exit = await handler.HandleAsync(force, skipSkills, ct, installClaude: claudeSelected); + if (exit != ExitCodes.Success) + { + return exit; + } + } + + if (claudeSelected) + { + output.WriteLine(fullInit + ? $"{Tag} claude: {(dryRun ? "would install" : "installed")} the standard Claude Code files (.claude/skills, .claude/agents, .claude/settings.json)." + : $"{Tag} claude: already initialised — refresh it with `spectra update-skills`."); + } + + if (skipSkills) + { + output.WriteLine($"{Tag} --skip-skills: no agent files installed."); + return ExitCodes.Success; + } + + if (agents.All(a => a == "claude")) + { + return ExitCodes.Success; + } + + var result = AgentInstaller.Install(root, agents, claudePresent, regenerate, dryRun); + Report(result, output); + return ExitCodes.Success; + } + + /// Human-readable report: per agent counts (every file in a dry run), host blocks, allowlists, decisions, warnings. + public static void Report(AgentInstallResult result, TextWriter output) + { + foreach (var agent in result.Agents) + { + var target = AgentSelection.Get(agent.Agent); + var verb = result.DryRun ? "would write" : "written"; + output.WriteLine( + $"{Tag} {agent.Agent} ({target.DisplayName}): {agent.Emitted.Count} {verb}, {agent.Unchanged.Count} unchanged, " + + $"{agent.Skipped.Count} skipped (edited by you; --regenerate overwrites), {agent.Removed.Count} {(result.DryRun ? "would be removed" : "removed")} " + + $"— manifest {agent.Manifest}"); + output.WriteLine($" instructions: {target.FragmentPath}"); + if (agent.HostFile is not null) + { + output.WriteLine($" {agent.HostFile}: SPECTRA block {(result.DryRun ? "would be " : string.Empty)}{agent.HostStatus}"); + } + + if (agent.Allowlist is not null && agent.AllowlistOutcome is not null) + { + output.WriteLine(agent.AllowlistOutcome.Status == "skipped" + ? $" allowlist: skipped — {agent.AllowlistOutcome.Reason}" + : $" allowlist: {agent.Allowlist.Description} ({(result.DryRun ? "would be " : string.Empty)}{agent.AllowlistOutcome.Status})"); + } + + if (result.DryRun) + { + foreach (var path in agent.Emitted) output.WriteLine($" write {path}"); + foreach (var path in agent.Unchanged) output.WriteLine($" same {path}"); + foreach (var path in agent.Skipped) output.WriteLine($" skip {path}"); + foreach (var path in agent.Removed) output.WriteLine($" remove {path}"); + } + + foreach (var path in agent.Skipped.Where(_ => !result.DryRun)) + { + output.WriteLine($" skipped (edited by you): {path}"); + } + } + + foreach (var decision in result.Decisions) + { + output.WriteLine($"{Tag} decision: {decision}"); + } + + foreach (var warning in result.Warnings) + { + output.WriteLine($"{Tag} warning: {warning}"); + } + } +} diff --git a/src/Spectra.CLI/Install/AgentInstaller.cs b/src/Spectra.CLI/Install/AgentInstaller.cs new file mode 100644 index 00000000..18f7f2f2 --- /dev/null +++ b/src/Spectra.CLI/Install/AgentInstaller.cs @@ -0,0 +1,363 @@ +using System.Reflection; +using Spectra.CLI.Skills; + +namespace Spectra.CLI.Install; + +/// Spec 104: what one agent's install did. +public sealed record AgentInstallOutcome( + string Agent, + IReadOnlyList Emitted, + IReadOnlyList Unchanged, + IReadOnlyList Skipped, + IReadOnlyList Removed, + string? HostFile, + string? HostStatus, + AllowlistTarget? Allowlist, + AllowlistOutcome? AllowlistOutcome, + string Manifest); + +/// Spec 104: the whole run — per agent, plus the decisions and warnings to report. +public sealed record AgentInstallResult( + IReadOnlyList Agents, + IReadOnlyList Decisions, + IReadOnlyList Warnings, + bool DryRun); + +/// +/// Spec 104: installs SPECTRA for the non-Claude agents (the Claude install stays the unchanged InitHandler path). +/// Plans every file once with its owning agents, writes through the R6 hash gate (a file the user edited is skipped unless +/// --regenerate), retires files an agent no longer plans (only unedited ones, only if no other agent relies on +/// them), registers the marker block in AGENTS.md / GEMINI.md, merges the documented allowlists and saves +/// one manifest per agent. Every path it touches is in SPECTRA's namespace (R8). +/// +public static class AgentInstaller +{ + private const string FragmentResource = "Spectra.CLI.Install.Content.spectra.instructions.md"; + + /// The always-on instructions fragment (LF). + public static string FragmentBody() + { + using var stream = Assembly.GetExecutingAssembly().GetManifestResourceStream(FragmentResource) + ?? throw new InvalidOperationException($"Embedded resource not found: {FragmentResource}"); + using var reader = new StreamReader(stream); + return reader.ReadToEnd().Replace("\r\n", "\n"); + } + + public static AgentInstallResult Install( + string root, IReadOnlyList agents, bool claudePresent, bool regenerate, bool dryRun) + { + var targets = agents.Where(a => a != "claude").Select(AgentSelection.Get).ToArray(); + var decisions = new List(); + var warnings = new List(); + + // ---- plan: path → content + owning agents, in a stable order ---- + var plan = new Dictionary(StringComparer.Ordinal); + var order = new List(); + void Add(string path, string content, string owner) + { + if (!plan.TryGetValue(path, out var file)) + { + file = new PlannedFile(content); + plan[path] = file; + order.Add(path); + } + else if (file.Content != content) + { + throw new InvalidOperationException($"Two agents planned different content for '{path}'."); + } + + if (!file.Owners.Contains(owner)) + { + file.Owners.Add(owner); + } + } + + var fragment = FragmentBody(); + foreach (var target in targets) + { + Add(target.FragmentPath, target.RenderFragment(fragment), target.Name); + } + + var skillDirs = PlanSkillDirs(targets, claudePresent, decisions, warnings); + foreach (var target in targets) + { + var dir = skillDirs[target.Name]; + if (dir == AgentTarget.ClaudeSkillsDir) + { + continue; // Claude's own files, written by the Claude install; reused, never rewritten + } + + foreach (var (name, content) in SkillContent.All.OrderBy(s => s.Key, StringComparer.Ordinal)) + { + Add($"{dir}/{name}/SKILL.md", NeutralContent.Skill(name, content), target.Name); + } + + foreach (var (name, content) in SkillReferenceContent.All.OrderBy(s => s.Key, StringComparer.Ordinal)) + { + Add($"{dir}/{name}/reference.md", NeutralContent.Text(content), target.Name); + } + } + + var subagents = AgentContent.All + .OrderBy(a => a.Key, StringComparer.Ordinal) + .Select(a => NeutralContent.Agent(a.Key, a.Value)) + .ToArray(); + foreach (var target in targets) + { + if (claudePresent && target.ReadsClaudeAgents && !target.NativeAgentsShadowClaude) + { + decisions.Add($"{target.Name} subagents: reuse .claude/agents (read natively; no second copy)"); + continue; + } + + decisions.Add($"{target.Name} subagents: {AgentsDir(target)}"); + foreach (var agent in subagents) + { + Add(target.AgentPath(agent.Name), target.RenderAgent(agent), target.Name); + } + } + + if (targets.Any(t => t.Name == "devin") && (claudePresent || targets.Any(t => t.Name == "antigravity"))) + { + warnings.Add("devin also imports subagents from .claude/ and .agents/agents/ — it may list a SPECTRA subagent twice"); + } + + // ---- write through the hash gate (R6) ---- + // Every installed agent's manifest counts: a shared file another agent's run wrote is SPECTRA's, not the user's. + var manifests = AgentSelection.Names.Where(n => n != "claude") + .ToDictionary(n => n, n => AgentManifest.Load(root, n), StringComparer.Ordinal); + var previous = targets.ToDictionary(t => t.Name, t => manifests[t.Name], StringComparer.Ordinal); + var perAgent = targets.ToDictionary(t => t.Name, _ => new Buckets(), StringComparer.Ordinal); + var records = targets.ToDictionary(t => t.Name, _ => new List(), StringComparer.Ordinal); + + foreach (var relative in order) + { + var file = plan[relative]; + var full = FullPath(root, relative); + var newHash = AgentManifest.Hash(file.Content); + var recordHash = newHash; + string bucket; + + if (File.Exists(full)) + { + var diskHash = AgentManifest.HashOfFile(full); + var recorded = manifests.Values.Select(m => m?.HashFor(relative)).OfType().ToHashSet(StringComparer.Ordinal); + var userEdited = recorded.Count > 0 && !recorded.Contains(diskHash); + var foreign = recorded.Count == 0 && diskHash != newHash; + + if (!regenerate && (userEdited || foreign)) + { + bucket = "skipped"; + recordHash = diskHash; // keep tracking the user's bytes + } + else + { + bucket = diskHash == newHash ? "unchanged" : "emitted"; + } + } + else + { + bucket = "emitted"; + } + + if (bucket == "emitted" && !dryRun) + { + Directory.CreateDirectory(Path.GetDirectoryName(full)!); + File.WriteAllText(full, file.Content); + } + + foreach (var owner in file.Owners) + { + records[owner].Add(new AgentManifestEntry { Path = relative, Sha256 = recordHash }); + perAgent[owner].Add(bucket, relative); + } + } + + // ---- retire files an agent owned before but no longer plans ---- + foreach (var target in targets) + { + foreach (var entry in previous[target.Name]?.Files ?? []) + { + if (plan.TryGetValue(entry.Path, out var planned) && planned.Owners.Contains(target.Name)) + { + continue; + } + + var otherOwners = manifests.Any(m => m.Key != target.Name && !previous.ContainsKey(m.Key) && m.Value?.HashFor(entry.Path) is not null); + if (plan.ContainsKey(entry.Path) || otherOwners) + { + continue; // still relied on by another agent: just drop our claim + } + + var full = FullPath(root, entry.Path); + if (!File.Exists(full)) + { + continue; + } + + if (!regenerate && AgentManifest.HashOfFile(full) != entry.Sha256) + { + perAgent[target.Name].Add("skipped", entry.Path); // user-edited: never deleted + continue; + } + + if (!dryRun) + { + File.Delete(full); + DeleteEmptyParents(root, Path.GetDirectoryName(full)!); + } + + perAgent[target.Name].Add("removed", entry.Path); + } + } + + // ---- R1/R3: one marker block in a human-owned instructions file; allowlists (documented ones only) ---- + var hostStatus = new Dictionary(StringComparer.Ordinal); + var allowlistStatus = new Dictionary(StringComparer.Ordinal); + var outcomes = new List(); + foreach (var target in targets) + { + string? status = null; + if (target.Host is { } host) + { + if (!hostStatus.TryGetValue(host.Path, out status)) + { + status = MarkerBlock.Register(FullPath(root, host.Path), host.Line, dryRun); + hostStatus[host.Path] = status; + } + } + + AllowlistOutcome? allowlist = null; + if (target.Allowlist is { } list) + { + if (!allowlistStatus.TryGetValue(list.Path, out allowlist)) + { + allowlist = list.Apply(root, dryRun); + allowlistStatus[list.Path] = allowlist; + } + } + else + { + decisions.Add($"{target.Name} allowlist: none (no documented project-level command allowlist) — skipped"); + } + + var buckets = perAgent[target.Name]; + outcomes.Add(new AgentInstallOutcome(target.Name, buckets.Emitted, buckets.Unchanged, buckets.Skipped, buckets.Removed, + target.Host?.Path, status, target.Allowlist, allowlist, AgentManifest.RelativePathFor(target.Name))); + } + + if (!dryRun) + { + foreach (var target in targets) + { + new AgentManifest { Agent = target.Name, Files = records[target.Name] }.Save(root); + } + } + + return new AgentInstallResult(outcomes, decisions, warnings, dryRun); + } + + /// + /// Chooses the fewest skill directories that reach every agent: .claude/skills first when Claude's install is + /// present, then greedily the directory read by the most still-uncovered agents (ties → the first agent's native order). + /// Returns agent → the directory it reads SPECTRA's skills from. + /// + public static IReadOnlyDictionary PlanSkillDirs( + IReadOnlyList targets, bool claudePresent, List? decisions = null, List? warnings = null) + { + var chosen = new List(); + if (claudePresent) + { + chosen.Add(AgentTarget.ClaudeSkillsDir); + } + + var uncovered = targets.Where(t => !t.SkillDirs.Any(chosen.Contains)).ToList(); + while (uncovered.Count > 0) + { + var best = uncovered.SelectMany(t => t.SkillDirs).Distinct(StringComparer.Ordinal) + .Select((dir, index) => (dir, index, reach: uncovered.Count(t => t.SkillDirs.Contains(dir)))) + .OrderByDescending(c => c.reach) + .ThenBy(c => c.index) + .First().dir; + chosen.Add(best); + uncovered.RemoveAll(t => t.SkillDirs.Contains(best)); + } + + var assignment = targets.ToDictionary(t => t.Name, t => chosen.First(t.SkillDirs.Contains), StringComparer.Ordinal); + foreach (var dir in chosen) + { + var readers = targets.Where(t => assignment[t.Name] == dir).Select(t => t.Name).ToArray(); + if (readers.Length > 0) + { + decisions?.Add(dir == AgentTarget.ClaudeSkillsDir + ? $"skills: reuse {dir} (Claude's copy) for {string.Join(", ", readers)}" + : $"skills: {dir} for {string.Join(", ", readers)}"); + } + } + + foreach (var target in targets) + { + var seen = chosen.Where(target.SkillDirs.Contains).ToArray(); + if (seen.Length > 1) + { + warnings?.Add($"{target.Name} reads {string.Join(" and ", seen)} — it may list each SPECTRA skill twice (no single-copy layout exists for this agent set)"); + } + } + + return assignment; + } + + private static string AgentsDir(AgentTarget target) + { + var path = target.AgentPath("x"); + return path[..path.IndexOf("/x", StringComparison.Ordinal)]; + } + + private static string FullPath(string root, string relative) => + Path.Combine(root, relative.Replace('/', Path.DirectorySeparatorChar)); + + /// Removes now-empty directories up to (not including) the repo root, e.g. a retired skill folder. + private static void DeleteEmptyParents(string root, string directory) + { + var stop = Path.GetFullPath(root).TrimEnd(Path.DirectorySeparatorChar); + var current = Path.GetFullPath(directory); + while (current.Length > stop.Length && Directory.Exists(current) && !Directory.EnumerateFileSystemEntries(current).Any()) + { + Directory.Delete(current); + current = Path.GetDirectoryName(current)!; + } + } + + private sealed class PlannedFile(string content) + { + public string Content { get; } = content; + + public List Owners { get; } = []; + } + + private sealed class Buckets + { + public List Emitted { get; } = []; + + public List Unchanged { get; } = []; + + public List Skipped { get; } = []; + + public List Removed { get; } = []; + + public void Add(string bucket, string path) + { + var list = bucket switch + { + "emitted" => Emitted, + "unchanged" => Unchanged, + "skipped" => Skipped, + _ => Removed, + }; + if (!list.Contains(path)) + { + list.Add(path); + } + } + } +} diff --git a/src/Spectra.CLI/Install/AgentManifest.cs b/src/Spectra.CLI/Install/AgentManifest.cs new file mode 100644 index 00000000..bad564b7 --- /dev/null +++ b/src/Spectra.CLI/Install/AgentManifest.cs @@ -0,0 +1,56 @@ +using System.Security.Cryptography; +using System.Text; +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Spectra.CLI.Install; + +/// Spec 104 (R6): one file SPECTRA wrote for an agent — repo-relative path + SHA-256 of what it wrote. +public sealed class AgentManifestEntry +{ + [JsonPropertyName("path")] public string Path { get; set; } = string.Empty; + + [JsonPropertyName("sha256")] public string Sha256 { get; set; } = string.Empty; +} + +/// +/// Spec 104 (R6/R8): .spectra/manifest.<agent>.json, the record of every file spectra init --agent wrote for +/// one non-Claude agent. On a re-run a file whose content differs from its recorded hash is the user's edit and is skipped +/// unless --regenerate. A file several agents rely on (a shared skill directory, the shared fragment) is listed in +/// each of their manifests. Claude's install keeps its own .spectra/skills-manifest.json, which this never touches. +/// +public sealed class AgentManifest +{ + private static readonly JsonSerializerOptions Options = new() { WriteIndented = true }; + + [JsonPropertyName("version")] public string Version { get; set; } = "1.0"; + + [JsonPropertyName("agent")] public string Agent { get; set; } = string.Empty; + + [JsonPropertyName("files")] public List Files { get; set; } = []; + + public static string RelativePathFor(string agent) => $".spectra/manifest.{agent}.json"; + + public static string PathFor(string root, string agent) => System.IO.Path.Combine(root, ".spectra", $"manifest.{agent}.json"); + + public static AgentManifest? Load(string root, string agent) + { + var path = PathFor(root, agent); + return File.Exists(path) ? JsonSerializer.Deserialize(File.ReadAllText(path)) : null; + } + + public void Save(string root) + { + var path = PathFor(root, Agent); + Directory.CreateDirectory(System.IO.Path.GetDirectoryName(path)!); + File.WriteAllText(path, JsonSerializer.Serialize(this, Options).Replace("\r\n", "\n") + "\n"); + } + + public string? HashFor(string relativePath) => Files.FirstOrDefault(f => f.Path == relativePath)?.Sha256; + + /// SHA-256 with CRLF normalised to LF, so a checkout that rewrites line endings is not mistaken for an edit. + public static string Hash(string content) => + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(content.Replace("\r\n", "\n")))).ToLowerInvariant(); + + public static string HashOfFile(string path) => Hash(File.ReadAllText(path)); +} diff --git a/src/Spectra.CLI/Install/AgentSelection.cs b/src/Spectra.CLI/Install/AgentSelection.cs new file mode 100644 index 00000000..1e62a6f6 --- /dev/null +++ b/src/Spectra.CLI/Install/AgentSelection.cs @@ -0,0 +1,119 @@ +namespace Spectra.CLI.Install; + +/// Spec 104: a bad --agent value (unknown name, nothing detected, several detected). Exit code 2 (usage). +public sealed class AgentSelectionException(string message) : Exception(message); + +/// +/// Spec 104: resolves spectra init --agent with BELLATRIX Agent's names, aliases and detection, so one value works +/// for both tools. windsurf → devin (with a notice: renamed Devin Desktop), agy → antigravity. +/// auto detects: the agents already installed in the repo, else exactly one agent whose markers exist; it never +/// guesses (none or several → an error listing the choices). +/// +public static class AgentSelection +{ + public const string Auto = "auto"; + + /// Every supported agent, in the order results are reported. + public static readonly IReadOnlyList All = + [ + new ClaudeTarget(), new CopilotTarget(), new CursorTarget(), new DevinTarget(), new CodexTarget(), + new GeminiTarget(), new AntigravityTarget(), new KiroTarget(), new OpenCodeTarget(), + ]; + + /// Accepted spellings that map to a canonical name without a notice. + public static readonly IReadOnlyDictionary Aliases = new Dictionary(StringComparer.Ordinal) + { + ["agy"] = "antigravity", + }; + + public static IReadOnlyList Names { get; } = All.Select(t => t.Name).ToArray(); + + /// The agents other than Claude, for the one-line notice of a plain spectra init. + public static string OthersList => string.Join(", ", Names.Where(n => n != "claude")); + + public static AgentTarget Get(string name) => All.Single(t => t.Name == name); + + /// Parses a comma-separated --agent value; returns canonical names in canonical order, de-duplicated. + public static IReadOnlyList Parse(string raw, string root, TextWriter notices) + { + var tokens = raw.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries) + .Select(t => t.ToLowerInvariant()) + .ToArray(); + if (tokens.Length == 1 && tokens[0] == Auto) + { + return Detect(root); + } + + var chosen = new HashSet(StringComparer.Ordinal); + foreach (var token in tokens) + { + var name = token; + if (name == "windsurf") + { + notices.WriteLine("[spectra init] notice: 'windsurf' is now Devin Desktop — using --agent devin."); + name = "devin"; + } + else if (Aliases.TryGetValue(name, out var canonical)) + { + name = canonical; + } + + if (name == Auto) + { + throw new AgentSelectionException("--agent auto cannot be combined with agent names."); + } + + if (!Names.Contains(name)) + { + throw new AgentSelectionException($"Unknown --agent '{token}'. One of: {string.Join(", ", Names)} (or auto)."); + } + + chosen.Add(name); + } + + if (chosen.Count == 0) + { + throw new AgentSelectionException($"--agent needs at least one of: {string.Join(", ", Names)} (or auto)."); + } + + return Names.Where(chosen.Contains).ToArray(); + } + + /// + /// --agent auto: the agents already installed (a manifest in .spectra/, or Claude's skills), else the single + /// agent whose repo markers exist. + /// + public static IReadOnlyList Detect(string root) + { + var installed = Names.Where(n => IsInstalled(root, n)).ToArray(); + if (installed.Length > 0) + { + return installed; + } + + var detected = All + .Where(t => t.DetectionMarkers.Any(m => + File.Exists(Path.Combine(root, m)) || Directory.Exists(Path.Combine(root, m)))) + .Select(t => t.Name) + .ToArray(); + + return detected.Length switch + { + 1 => detected, + 0 => throw new AgentSelectionException( + $"No AI agent detected in '{root}'. Pass --agent <{string.Join("|", Names)}> (comma-separated for several)."), + _ => throw new AgentSelectionException( + $"Several AI agents detected ({string.Join(", ", detected)}). Pass --agent with the ones to install, e.g. --agent {string.Join(",", detected)}."), + }; + } + + /// True when SPECTRA is installed for the agent: Claude's bundled skills, or the agent's manifest. + public static bool IsInstalled(string root, string agent) => + agent == "claude" + ? ClaudeInstalled(root) + : File.Exists(AgentManifest.PathFor(root, agent)); + + /// The unchanged Claude install is present (its skills reach agents that read .claude/skills). + public static bool ClaudeInstalled(string root) => + File.Exists(Path.Combine(root, ".claude", "skills", "spectra-generate", "SKILL.md")); +} diff --git a/src/Spectra.CLI/Install/AgentTargets.cs b/src/Spectra.CLI/Install/AgentTargets.cs new file mode 100644 index 00000000..3d0f881f --- /dev/null +++ b/src/Spectra.CLI/Install/AgentTargets.cs @@ -0,0 +1,335 @@ +using System.Text; + +namespace Spectra.CLI.Install; + +/// Spec 104 (R1/R3): one marker block that registers SPECTRA in a human-owned instructions file. +/// Repo-relative path of the host file (AGENTS.md, GEMINI.md). +/// The single line inside the block (a pointer sentence or an @ import). +public sealed record HostRegistration(string Path, string Line); + +/// +/// Spec 104: placement and frontmatter for one AI agent. Content is the provider-neutral form (); +/// a target only decides where each piece lands and which frontmatter the agent's loader expects. The layout +/// follows BELLATRIX Agent's provider emitters (same names, aliases and detection markers, so the two tools coexist); +/// every path and field is checked against the provider's docs (see FINDINGS-multi-client-gap-v2.md §4). +/// +public abstract class AgentTarget +{ + /// The shared fragment, for agents that register through a host file instead of a native rule file. + public const string SharedFragmentPath = ".spectra/spectra.instructions.md"; + + /// Claude Code's skills directory (written by the unchanged Claude install, never by this layer). + public const string ClaudeSkillsDir = ".claude/skills"; + + /// The --agent value. + public abstract string Name { get; } + + /// Product name for messages. + public abstract string DisplayName { get; } + + /// Skill directories the agent loads from the repo, its native one first (input to the set-cover planner). + public abstract IReadOnlyList SkillDirs { get; } + + /// True when the agent loads .claude/agents, so Claude's subagents reach it without a copy. + public virtual bool ReadsClaudeAgents => false; + + /// True when the agent's own subagent wins a name clash with .claude/agents (a native copy is safe). + public virtual bool NativeAgentsShadowClaude => false; + + /// Repo-relative path of the agent's always-on copy of the instructions fragment. + public abstract string FragmentPath { get; } + + /// The fragment as the agent loads it (its frontmatter, if any, + the shared body). + public virtual string RenderFragment(string body) => body; + + /// The marker block written into the agent's human-owned instructions file, if it needs one. + public virtual HostRegistration? Host => null; + + /// Repo-relative path of a subagent file. + public abstract string AgentPath(string agentName); + + /// A subagent in the agent's native format. + public abstract string RenderAgent(AgentSpec agent); + + /// The project-level command allowlist, where the agent documents one. + public virtual AllowlistTarget? Allowlist => null; + + /// Repo-root markers that show the agent is in use (--agent auto). + public abstract IReadOnlyList DetectionMarkers { get; } + + /// The AGENTS.md block shared by every agent that reads it (Codex, OpenCode): one block, written once. + protected static HostRegistration AgentsMdPointer { get; } = new("AGENTS.md", + $"Before any SPECTRA work (test generation, test updates, acceptance criteria, test execution), read `{SharedFragmentPath}` and follow it."); + + protected static string Yaml(string value) => NeutralContent.Yaml(value); + + protected static string MarkdownAgent(AgentSpec agent, string extraFrontmatter) => + $"---\nname: {agent.Name}\ndescription: {Yaml(agent.Description)}\n{extraFrontmatter}---\n\n{agent.Body}"; + + /// Maps the Claude tool names an agent declared, keeping order and dropping duplicates and unmapped ones. + protected static List Map(AgentSpec agent, Func map) + { + var mapped = new List(); + foreach (var name in agent.Tools.Select(map).OfType()) + { + if (!mapped.Contains(name)) + { + mapped.Add(name); + } + } + + return mapped; + } +} + +/// +/// Claude Code. Installed by the unchanged Claude path (InitHandler); listed here only so --agent parsing, +/// detection and the skill-directory planner see it. +/// +public sealed class ClaudeTarget : AgentTarget +{ + public override string Name => "claude"; + public override string DisplayName => "Claude Code"; + public override IReadOnlyList SkillDirs { get; } = [ClaudeSkillsDir]; + public override bool ReadsClaudeAgents => true; + public override string FragmentPath => throw new NotSupportedException("the Claude install is not emitted by this layer"); + public override string AgentPath(string agentName) => $".claude/agents/{agentName}.agent.md"; + public override string RenderAgent(AgentSpec agent) => throw new NotSupportedException("the Claude install is not emitted by this layer"); + public override IReadOnlyList DetectionMarkers { get; } = [".claude", "CLAUDE.md"]; +} + +/// +/// GitHub Copilot (VS Code, CLI, cloud agent): an always-applied .github/instructions/spectra.instructions.md; +/// .github/skills (it also reads .claude/skills and .agents/skills); .github/agents/*.agent.md +/// with Copilot tool aliases and an agents: allow-list naming the critic on agents that start it. +/// +public sealed class CopilotTarget : AgentTarget +{ + public override string Name => "copilot"; + public override string DisplayName => "GitHub Copilot"; + public override IReadOnlyList SkillDirs { get; } = [".github/skills", ClaudeSkillsDir, ".agents/skills"]; + public override bool ReadsClaudeAgents => true; + public override string FragmentPath => ".github/instructions/spectra.instructions.md"; + public override string RenderFragment(string body) => "---\napplyTo: \"**\"\n---\n\n" + body; + public override string AgentPath(string agentName) => $".github/agents/{agentName}.agent.md"; + + public override string RenderAgent(AgentSpec agent) + { + var tools = Map(agent, tool => tool switch + { + "Bash" => "execute", + "Read" => "read", + "Edit" or "Write" => "edit", + "Grep" or "Glob" => "search", + "Agent" => "agent", + _ => null, + }); + var extra = new StringBuilder(); + if (tools.Count > 0) + { + extra.Append("tools: [").Append(string.Join(", ", tools.Select(t => $"'{t}'"))).Append("]\n"); + } + + if (agent.StartsSubagents) + { + extra.Append("agents: ['spectra-critic']\n"); + } + + return MarkdownAgent(agent, extra.ToString()); + } + + public override IReadOnlyList DetectionMarkers { get; } = [".github/copilot-instructions.md", ".github/agents"]; +} + +/// +/// Cursor: an alwaysApply rule .cursor/rules/spectra.mdc; .cursor/skills; .cursor/agents (wins a +/// clash with .claude/agents). Cursor has no tool list, only readonly, which blocks file edits — every SPECTRA +/// subagent writes (the critic its verdict file), so none is marked read-only. +/// +public sealed class CursorTarget : AgentTarget +{ + public override string Name => "cursor"; + public override string DisplayName => "Cursor"; + public override IReadOnlyList SkillDirs { get; } = [".cursor/skills", ".agents/skills", ClaudeSkillsDir, ".codex/skills"]; + public override bool ReadsClaudeAgents => true; + public override bool NativeAgentsShadowClaude => true; + public override string FragmentPath => ".cursor/rules/spectra.mdc"; + + public override string RenderFragment(string body) => + "---\ndescription: SPECTRA test generation and execution through the spectra CLI (always applied).\nalwaysApply: true\n---\n\n" + body; + + public override string AgentPath(string agentName) => $".cursor/agents/{agentName}.md"; + public override string RenderAgent(AgentSpec agent) => MarkdownAgent(agent, agent.Writes ? string.Empty : "readonly: true\n"); + public override AllowlistTarget Allowlist { get; } = AllowlistTarget.StringArray(".cursor/cli.json", ["permissions", "allow"], "Shell(spectra)"); + public override IReadOnlyList DetectionMarkers { get; } = [".cursor"]; +} + +/// +/// Devin Desktop (formerly Windsurf) / Devin CLI: an always_on rule .devin/rules/spectra.md; .devin/skills +/// (its documented skill import is .github/skills); .devin/agents. allowed-tools is written only when +/// every tool has a documented Devin name (read, grep, glob, exec); there is none for writing +/// files, so SPECTRA's subagents stay unrestricted. +/// +public sealed class DevinTarget : AgentTarget +{ + public override string Name => "devin"; + public override string DisplayName => "Devin"; + public override IReadOnlyList SkillDirs { get; } = [".devin/skills", ".github/skills"]; + public override string FragmentPath => ".devin/rules/spectra.md"; + public override string RenderFragment(string body) => "---\ntrigger: always_on\n---\n\n" + body; + public override string AgentPath(string agentName) => $".devin/agents/{agentName}.md"; + + public override string RenderAgent(AgentSpec agent) + { + string? Documented(string tool) => tool switch { "Read" => "read", "Grep" => "grep", "Glob" => "glob", "Bash" => "exec", _ => null }; + var allDocumented = agent.Tools.All(t => Documented(t) is not null); + var tools = Map(agent, Documented); + return MarkdownAgent(agent, allDocumented && tools.Count > 0 ? $"allowed-tools: [{string.Join(", ", tools)}]\n" : string.Empty); + } + + public override AllowlistTarget Allowlist { get; } = AllowlistTarget.StringArray(".devin/config.json", ["permissions", "allow"], "Exec(spectra)"); + public override IReadOnlyList DetectionMarkers { get; } = [".devin", ".windsurf"]; +} + +/// +/// OpenAI Codex CLI: no tool-owned auto-loaded file, so AGENTS.md gets one marker block pointing at the shared +/// fragment; .agents/skills; TOML subagents in .codex/agents (developer_instructions holds the body). +/// +public sealed class CodexTarget : AgentTarget +{ + public override string Name => "codex"; + public override string DisplayName => "Codex CLI"; + public override IReadOnlyList SkillDirs { get; } = [".agents/skills"]; + public override string FragmentPath => SharedFragmentPath; + public override HostRegistration Host => AgentsMdPointer; + public override string AgentPath(string agentName) => $".codex/agents/{agentName}.toml"; + + public override string RenderAgent(AgentSpec agent) => + $"name = {TomlString(agent.Name)}\ndescription = {TomlString(agent.Description)}\ndeveloper_instructions = {TomlMultiline(agent.Body)}\n"; + + private static string TomlString(string value) => + "\"" + value.Replace("\\", "\\\\", StringComparison.Ordinal).Replace("\"", "\\\"", StringComparison.Ordinal) + "\""; + + /// A literal multi-line string (no escapes) unless the body contains its delimiter. + private static string TomlMultiline(string body) => + body.Contains("'''", StringComparison.Ordinal) + ? "\"\"\"\n" + body.Replace("\\", "\\\\", StringComparison.Ordinal).Replace("\"\"\"", "\"\"\\\"", StringComparison.Ordinal) + "\"\"\"" + : "'''\n" + body + "'''"; + + public override IReadOnlyList DetectionMarkers { get; } = [".codex"]; +} + +/// +/// Gemini CLI (enterprise / Gemini Code Assist): one marker block in GEMINI.md importing the shared fragment; +/// .agents/skills; .gemini/agents (kind: local) with Gemini built-in tool names. +/// +public sealed class GeminiTarget : AgentTarget +{ + public override string Name => "gemini"; + public override string DisplayName => "Gemini CLI"; + public override IReadOnlyList SkillDirs { get; } = [".agents/skills", ".gemini/skills"]; + public override string FragmentPath => SharedFragmentPath; + public override HostRegistration Host { get; } = new("GEMINI.md", "@./" + SharedFragmentPath); + public override string AgentPath(string agentName) => $".gemini/agents/{agentName}.md"; + + public override string RenderAgent(AgentSpec agent) + { + var tools = Map(agent, tool => tool switch + { + "Read" => "read_file", + "Grep" => "grep_search", + "Glob" => "glob", + "Bash" => "run_shell_command", + "Write" => "write_file", + "Edit" => "replace", + _ => null, + }); + var block = tools.Count > 0 ? "tools:\n" + string.Concat(tools.Select(t => $" - {t}\n")) : string.Empty; + return MarkdownAgent(agent, "kind: local\n" + block); + } + + public override IReadOnlyList DetectionMarkers { get; } = [".gemini", "GEMINI.md"]; +} + +/// +/// Google Antigravity CLI (agy): an always_on workspace rule .agents/rules/spectra.md (a rule without +/// frontmatter is discarded); .agents/skills; subagents in the folder form .agents/agents/<name>/agent.md. +/// tools defaults to none and an unknown name can hang a subagent, so only documented names are listed. +/// +public sealed class AntigravityTarget : AgentTarget +{ + public override string Name => "antigravity"; + public override string DisplayName => "Antigravity CLI"; + public override IReadOnlyList SkillDirs { get; } = [".agents/skills"]; + public override string FragmentPath => ".agents/rules/spectra.md"; + public override string RenderFragment(string body) => "---\ntrigger: always_on\n---\n\n" + body; + public override string AgentPath(string agentName) => $".agents/agents/{agentName}/agent.md"; + + public override string RenderAgent(AgentSpec agent) + { + string[] tools = agent.Writes + ? ["view_file", "grep_search", "replace_file_content", "run_command"] + : ["view_file", "grep_search", "run_command"]; + return MarkdownAgent(agent, "tools:\n" + string.Concat(tools.Select(t => $" - {t}\n")) + "subagent: true\nmainAgent: false\n"); + } + + public override IReadOnlyList DetectionMarkers { get; } = [".agents/agents", ".agents/rules", ".agents/mcp_config.json", ".agent"]; +} + +/// +/// Kiro CLI: an always-included steering file .kiro/steering/spectra.md; .kiro/skills; Markdown agents in +/// .kiro/agents. Custom agents load neither steering nor skills unless resources lists them, so every agent +/// lists SPECTRA's steering file and skills. tools uses Kiro's category tags. +/// +public sealed class KiroTarget : AgentTarget +{ + public override string Name => "kiro"; + public override string DisplayName => "Kiro CLI"; + public override IReadOnlyList SkillDirs { get; } = [".kiro/skills"]; + public override string FragmentPath => ".kiro/steering/spectra.md"; + public override string RenderFragment(string body) => "---\ninclusion: always\n---\n\n" + body; + public override string AgentPath(string agentName) => $".kiro/agents/{agentName}.md"; + + public override string RenderAgent(AgentSpec agent) + { + var tags = new List { "read" }; + if (agent.Writes) + { + tags.Add("write"); + } + + tags.Add("shell"); + if (agent.StartsSubagents) + { + tags.Add("subagent"); + } + + return MarkdownAgent(agent, + $"tools: [{string.Join(", ", tags.Select(t => $"\"{t}\""))}]\nresources:\n" + + $" - file://{FragmentPath}\n - skill://.kiro/skills/spectra-*/SKILL.md\n"); + } + + public override IReadOnlyList DetectionMarkers { get; } = [".kiro"]; +} + +/// +/// OpenCode: reads AGENTS.md (no @ imports), so it shares Codex's pointer block; .opencode/skills (it +/// also reads .agents/skills and .claude/skills); Markdown agents in .opencode/agents (file name = name). +/// +public sealed class OpenCodeTarget : AgentTarget +{ + public override string Name => "opencode"; + public override string DisplayName => "OpenCode"; + public override IReadOnlyList SkillDirs { get; } = [".opencode/skills", ".agents/skills", ClaudeSkillsDir]; + public override string FragmentPath => SharedFragmentPath; + public override HostRegistration Host => AgentsMdPointer; + public override string AgentPath(string agentName) => $".opencode/agents/{agentName}.md"; + + public override string RenderAgent(AgentSpec agent) => + agent.Writes + ? $"---\ndescription: {Yaml(agent.Description)}\nmode: subagent\n---\n\n{agent.Body}" + : $"---\ndescription: {Yaml(agent.Description)}\nmode: subagent\npermission:\n edit: deny\n---\n\n{agent.Body}"; + + public override AllowlistTarget Allowlist { get; } = AllowlistTarget.PatternMap("opencode.json", ["permission", "bash"], "spectra *", "allow"); + public override IReadOnlyList DetectionMarkers { get; } = ["opencode.json", "opencode.jsonc", ".opencode"]; +} diff --git a/src/Spectra.CLI/Install/AllowlistTarget.cs b/src/Spectra.CLI/Install/AllowlistTarget.cs new file mode 100644 index 00000000..fe94d4fa --- /dev/null +++ b/src/Spectra.CLI/Install/AllowlistTarget.cs @@ -0,0 +1,147 @@ +using System.Text.Json; +using System.Text.Json.Nodes; + +namespace Spectra.CLI.Install; + +/// +/// Spec 104: one entry SPECTRA adds to an agent's documented project-level command allowlist so spectra commands +/// run without an approval prompt (the counterpart of Claude's Bash(spectra *)). The file is the user's: the entry +/// is merged by key, nothing else is changed, an existing value for the key is never overwritten, and a file that is not +/// plain JSON (e.g. has comments) is left alone with a reason. +/// +public sealed class AllowlistTarget +{ + private readonly string[] _jsonPath; + private readonly string _entry; + private readonly string? _value; + + private AllowlistTarget(string path, string[] jsonPath, string entry, string? value) + { + Path = path; + _jsonPath = jsonPath; + _entry = entry; + _value = value; + } + + /// Repo-relative path of the settings file. + public string Path { get; } + + /// One line for reports, e.g. .cursor/cli.json permissions.allow += "Shell(spectra)". + public string Description => _value is null + ? $"{Path} {string.Join('.', _jsonPath)} += \"{_entry}\"" + : $"{Path} {string.Join('.', _jsonPath)}[\"{_entry}\"] = \"{_value}\""; + + /// An entry appended to a string array at (Cursor, Devin). + public static AllowlistTarget StringArray(string path, string[] jsonPath, string entry) => new(path, jsonPath, entry, null); + + /// A pattern key set in an object at (OpenCode's permission.bash). + public static AllowlistTarget PatternMap(string path, string[] jsonPath, string pattern, string value) => new(path, jsonPath, pattern, value); + + public AllowlistOutcome Apply(string root, bool dryRun) + { + var full = System.IO.Path.Combine(root, Path.Replace('/', System.IO.Path.DirectorySeparatorChar)); + JsonObject document; + var original = File.Exists(full) ? File.ReadAllText(full) : null; + if (string.IsNullOrWhiteSpace(original)) + { + document = new JsonObject(); + } + else + { + try + { + document = JsonNode.Parse(original) as JsonObject + ?? throw new JsonException("the top level is not an object"); + } + catch (JsonException ex) + { + return AllowlistOutcome.Skip($"{Path} is not plain JSON ({ex.Message.Split('.')[0]}); add {Entry()} by hand"); + } + } + + var parent = document; + for (var i = 0; i < _jsonPath.Length; i++) + { + var key = _jsonPath[i]; + var last = i == _jsonPath.Length - 1; + var existing = parent[key]; + if (existing is null) + { + JsonNode created = last && _value is null ? new JsonArray() : new JsonObject(); + parent[key] = created; + existing = created; + } + + if (last) + { + return _value is null ? AddToArray(full, original, document, existing, dryRun) : SetInMap(full, original, document, existing, dryRun); + } + + if (existing is not JsonObject next) + { + return AllowlistOutcome.Skip($"{Path}: '{key}' is not an object; add {Entry()} by hand"); + } + + parent = next; + } + + return AllowlistOutcome.Skip("empty JSON path"); + } + + private AllowlistOutcome AddToArray(string full, string? original, JsonObject document, JsonNode node, bool dryRun) + { + if (node is not JsonArray array) + { + return AllowlistOutcome.Skip($"{Path}: '{_jsonPath[^1]}' is not a list; add {Entry()} by hand"); + } + + if (array.Any(item => item is JsonValue v && v.TryGetValue(out var s) && s == _entry)) + { + return AllowlistOutcome.Present; + } + + array.Add(_entry); + return Save(full, original, document, dryRun); + } + + private AllowlistOutcome SetInMap(string full, string? original, JsonObject document, JsonNode node, bool dryRun) + { + if (node is not JsonObject map) + { + return AllowlistOutcome.Skip($"{Path}: '{_jsonPath[^1]}' is not an object; add {Entry()} by hand"); + } + + if (map.ContainsKey(_entry)) + { + return AllowlistOutcome.Present; // the user's value for this pattern wins, whatever it is + } + + map[_entry] = _value; + return Save(full, original, document, dryRun); + } + + private static AllowlistOutcome Save(string full, string? original, JsonObject document, bool dryRun) + { + if (!dryRun) + { + Directory.CreateDirectory(System.IO.Path.GetDirectoryName(full)!); + var newline = original is not null && original.Contains("\r\n", StringComparison.Ordinal) ? "\r\n" : "\n"; + var json = document.ToJsonString(new JsonSerializerOptions { WriteIndented = true }).Replace("\r\n", "\n").Replace("\n", newline); + File.WriteAllText(full, json + newline); + } + + return AllowlistOutcome.Added; + } + + private string Entry() => _value is null ? $"\"{_entry}\"" : $"\"{_entry}\": \"{_value}\""; +} + +/// Spec 104: what happened to one allowlist entry. +public sealed record AllowlistOutcome(string Status, string? Reason) +{ + public static AllowlistOutcome Added { get; } = new("added", null); + + public static AllowlistOutcome Present { get; } = new("present", null); + + public static AllowlistOutcome Skip(string reason) => new("skipped", reason); +} diff --git a/src/Spectra.CLI/Install/Content/spectra.instructions.md b/src/Spectra.CLI/Install/Content/spectra.instructions.md new file mode 100644 index 00000000..7afaae46 --- /dev/null +++ b/src/Spectra.CLI/Install/Content/spectra.instructions.md @@ -0,0 +1,29 @@ +# SPECTRA + +This repository uses SPECTRA (the `spectra` CLI) to generate, verify, update and execute manual test cases from its +documentation. SPECTRA makes no model calls: you do the reasoning, and `spectra` commands do the deterministic work. + +- **Use the `spectra-*` skills** for SPECTRA work: generating tests (`spectra-generate`), updating tests after a + documentation change (`spectra-update`), acceptance criteria (`spectra-criteria`), coverage, the dashboard, reviewing + flagged tests, running tests (`spectra-execute`). If unsure, start with `spectra-help` or `spectra-quickstart`. +- **Run `spectra` commands in the shell exactly as a skill says** and read their JSON output. Do not invent commands or + flags, and do not edit SPECTRA's files (`test-cases/**`, `_index.json`, `docs/criteria/**`, `.spectra/**`) by hand + unless a skill tells you to. +- **Subagents.** When a skill says to start a subagent (`spectra-analyst`, `spectra-generator`, `spectra-updater`, + `spectra-repairer`, `spectra-extractor`, `spectra-critic`), delegate to it with your agent's subagent mechanism and pass + only what the skill lists: + + | Agent | How to start a SPECTRA subagent | + |---|---| + | GitHub Copilot | the `agent` tool (`runSubagent`), by the subagent's name | + | Cursor | delegate by the subagent's name (or `/name`) | + | Devin | delegate to the custom subagent by its name | + | Codex CLI | ask for the subagent by its name | + | Gemini CLI | `@name` | + | Antigravity CLI | invoke the subagent by its name | + | Kiro CLI | name the subagent in plain language | + | OpenCode | `@name` | + +- **The critic is part of every flow.** Each test that is generated, edited or repaired is verified by the + `spectra-critic` subagent against the documentation it cites, as the skills describe. Never write, edit or guess a + verdict yourself. diff --git a/src/Spectra.CLI/Install/MarkerBlock.cs b/src/Spectra.CLI/Install/MarkerBlock.cs new file mode 100644 index 00000000..d9537168 --- /dev/null +++ b/src/Spectra.CLI/Install/MarkerBlock.cs @@ -0,0 +1,73 @@ +using System.Text; + +namespace Spectra.CLI.Install; + +/// +/// Spec 104 (R1/R3): registers SPECTRA in a human-owned instructions file (AGENTS.md, GEMINI.md) with ONE +/// marker block holding a single line. Bytes outside the block are never rewritten; a block whose line changed is replaced +/// in place (keeping the file's line endings); a missing block is appended. The markers differ from BELLATRIX Agent's +/// (bellatrix), so both tools keep their own block in the same file. +/// +/// <!-- >>> spectra >>> --> +/// @./.spectra/spectra.instructions.md +/// <!-- <<< spectra <<< --> +/// +/// +public static class MarkerBlock +{ + public const string Open = ""; + + public const string Close = ""; + + public static string Block(string line) => $"{Open}\n{line}\n{Close}\n"; + + /// Writes (or plans, when ) the block; returns "created", "added", "updated" or "unchanged". + public static string Register(string hostPath, string line, bool dryRun) + { + var block = Block(line); + if (!File.Exists(hostPath) || new FileInfo(hostPath).Length == 0) + { + if (!dryRun) + { + Directory.CreateDirectory(Path.GetDirectoryName(hostPath)!); + File.WriteAllText(hostPath, block); + } + + return "created"; + } + + var original = File.ReadAllText(hostPath); + var open = original.IndexOf(Open, StringComparison.Ordinal); + var close = open < 0 ? -1 : original.IndexOf(Close, open, StringComparison.Ordinal); + if (open >= 0 && close > open) + { + var end = close + Close.Length; + if (original[open..end].Replace("\r\n", "\n") + "\n" == block) + { + return "unchanged"; + } + + var newline = original.Contains("\r\n", StringComparison.Ordinal) ? "\r\n" : "\n"; + if (!dryRun) + { + File.WriteAllText(hostPath, original[..open] + block.TrimEnd('\n').Replace("\n", newline) + original[end..]); + } + + return "updated"; + } + + var append = new StringBuilder(); + if (!original.EndsWith('\n')) + { + append.Append('\n'); + } + + append.Append('\n').Append(block); + if (!dryRun) + { + File.AppendAllText(hostPath, append.ToString()); + } + + return "added"; + } +} diff --git a/src/Spectra.CLI/Install/NeutralContent.cs b/src/Spectra.CLI/Install/NeutralContent.cs new file mode 100644 index 00000000..22a19fd7 --- /dev/null +++ b/src/Spectra.CLI/Install/NeutralContent.cs @@ -0,0 +1,132 @@ +using System.Text.RegularExpressions; + +namespace Spectra.CLI.Install; + +/// +/// Spec 104: turns the bundled Claude Code content into the provider-neutral form installed for every other agent, at +/// emit time (the embedded source files are never edited). Skills share directories across agents (.agents/skills +/// is read by Codex, Gemini, Antigravity, Cursor and OpenCode), so the text is the same for all of them; each agent's +/// own vocabulary lives in its instructions fragment and its subagent frontmatter. +/// +public static class NeutralContent +{ + /// Ordered rewrites of Claude-only wording; the first match of a phrase wins. + private static readonly (Regex Pattern, string Replacement)[] Wording = + [ + (Rx(@"If you have no Agent tool, or your first Agent call fails"), "If you cannot start a subagent, or your first subagent call fails"), + (Rx(@"subagent with the Agent tool"), "subagent"), + (Rx(@"with the Agent tool"), "as a subagent"), + (Rx(@"\bthe Agent tool\b"), "your subagent tool"), + (Rx(@"\bAgent call\b"), "subagent call"), + (Rx(@"Run with the Bash tool"), "Run in the shell"), + (Rx(@"with the Bash tool"), "in the shell"), + (Rx(@"\bthe Bash tool\b"), "the shell"), + (Rx(@"with the Write tool"), "with your file-writing tool"), + (Rx(@"\bthe Write tool\b"), "your file-writing tool"), + (Rx(@"\bWrite tool\b"), "file-writing tool"), + (Rx(@"with the Read tool"), "with your file-reading tool"), + (Rx(@"\bthe Read tool\b"), "your file-reading tool"), + (Rx(@"\bRead tool\b"), "file-reading tool"), + (Rx(@"\(no Glob of `\.claude/skills/\*\*`,"), "(no listing of the skills folder,"), + (Rx(@"do not Glob `\.claude/skills/\*\*`"), "do not list the skills folder"), + (Rx(@"\(Grep/Glob\b"), "(search"), + (Rx(@"\bUse Grep/Glob\b"), "Use search"), + (Rx(@"\bGrep/Glob\b"), "search"), + (Rx(@"`\.claude/skills/\*\*`"), "the skills folder"), + (Rx(@"\bvia Claude Code\b"), "via your AI coding agent"), + (Rx(@"\bthrough Claude Code\b"), "through your AI coding agent"), + (Rx(@"\bfrom Claude Code\b"), "from your AI coding agent"), + (Rx(@"\bin Claude Code\b"), "in your AI coding agent"), + (Rx(@"\bClaude Code\b"), "your AI coding agent"), + ]; + + /// Text that must not survive the transform (a test keeps the bundled content free of them). + public static readonly IReadOnlyList ClaudeOnlyTokens = + [ + "Agent tool", "Bash tool", "Write tool", "Read tool", "Edit tool", "Task tool", "Grep/Glob", ".claude/", + "Claude Code", "context: fork", "disable-model-invocation", + "{{GENERATE_TOOLS}}", "{{GENERATION_TOOLS}}", "{{READONLY_TOOLS}}", "{{EXECUTION_TOOLS}}", "{{CRITIC_MODEL}}", + ]; + + /// Neutral wording for any bundled text (line endings normalised to LF). + public static string Text(string content) + { + var text = content.Replace("\r\n", "\n"); + foreach (var (pattern, replacement) in Wording) + { + text = pattern.Replace(text, replacement); + } + + return text; + } + + /// + /// A bundled skill as installed for a non-Claude agent: Agent Skills frontmatter (name = folder name, + /// description), the Claude tools key dropped, neutral body. + /// + public static string Skill(string skillName, string content) + { + var (frontmatter, body) = Split(content); + var description = Field(frontmatter, "description") + ?? throw new InvalidOperationException($"bundled skill '{skillName}' has no description"); + return $"---\nname: {skillName}\ndescription: {Yaml(Text(description))}\n---\n{Text(body)}"; + } + + /// A YAML double-quoted scalar (descriptions can hold : , which breaks a plain scalar). + public static string Yaml(string value) => + "\"" + value.Replace("\\", "\\\\", StringComparison.Ordinal).Replace("\"", "\\\"", StringComparison.Ordinal) + "\""; + + /// A bundled subagent, parsed into the parts every provider renders in its own format. + public static AgentSpec Agent(string fileName, string content) + { + var (frontmatter, body) = Split(content); + var name = Field(frontmatter, "name") ?? fileName.Replace(".agent.md", string.Empty, StringComparison.Ordinal); + var description = Field(frontmatter, "description") + ?? throw new InvalidOperationException($"bundled agent '{fileName}' has no description"); + var tools = (Field(frontmatter, "tools") ?? string.Empty) + .Trim().TrimStart('[').TrimEnd(']') + .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries) + .ToArray(); + return new AgentSpec(name, Text(description), tools, Text(body).TrimStart('\n')); + } + + private static (string Frontmatter, string Body) Split(string content) + { + var text = content.Replace("\r\n", "\n"); + if (!text.StartsWith("---\n", StringComparison.Ordinal)) + { + return (string.Empty, text); + } + + var end = text.IndexOf("\n---\n", 4, StringComparison.Ordinal); + return end < 0 ? (string.Empty, text) : (text[4..end], text[(end + 5)..]); + } + + private static string? Field(string frontmatter, string key) + { + foreach (var line in frontmatter.Split('\n')) + { + if (line.StartsWith(key + ":", StringComparison.Ordinal)) + { + return line[(key.Length + 1)..].Trim(); + } + } + + return null; + } + + private static Regex Rx(string pattern) => new(pattern, RegexOptions.CultureInvariant); +} + +/// +/// Spec 104: a bundled subagent in neutral form. are the Claude tool names it declared +/// (Read, Write, Bash, Agent, …); each provider maps them to its own names. +/// +public sealed record AgentSpec(string Name, string Description, IReadOnlyList Tools, string Body) +{ + /// The agent starts other subagents (the critic), so providers with an allow-list name it. + public bool StartsSubagents => Tools.Contains("Agent"); + + /// The agent writes files (every SPECTRA subagent does: the critic writes its verdict file). + public bool Writes => Tools.Any(t => t is "Write" or "Edit"); +} diff --git a/src/Spectra.CLI/Spectra.CLI.csproj b/src/Spectra.CLI/Spectra.CLI.csproj index 66337ed7..60171d51 100644 --- a/src/Spectra.CLI/Spectra.CLI.csproj +++ b/src/Spectra.CLI/Spectra.CLI.csproj @@ -69,6 +69,8 @@ Spectra.CLI.Skills.Content.Docs.USAGE.md + + ")); + } + + // A SPECTRA re-run after BELLATRIX's init changes nothing at all. + var before = _ws.Snapshot(); + await _ws.AgentsAsync(Agents); + Assert.Equal(before, _ws.Snapshot()); + AssertNamesUnique(); + } + + [LiveBellatrixFact] + public async Task Live_BellatrixFirst_ThenSpectra() + { + RunBellatrix(); + var bellatrix = HashesOf(_ws.Files().Where(p => p.Contains("bellatrix", StringComparison.Ordinal))); + + await _ws.AgentsAsync(Agents); + + foreach (var (path, hash) in bellatrix) + { + Assert.True(hash == AgentManifest.HashOfFile(_ws.PathOf(path)), $"SPECTRA changed BELLATRIX's '{path}'"); + } + + AssertNamesUnique(); + } + + [LiveBellatrixFact] + public async Task Live_SpectraFirst_ThenBellatrix() + { + await _ws.AgentsAsync(Agents); + var spectra = SpectraOwnedHashes(); + + RunBellatrix(); + + foreach (var (path, hash) in spectra) + { + Assert.True(hash == AgentManifest.HashOfFile(_ws.PathOf(path)), $"bellatrix init changed SPECTRA's '{path}'"); + } + + AssertNamesUnique(); + } + + /// Every skill folder and subagent across both tools has a unique name; the two marker blocks differ. + private void AssertNamesUnique() + { + var skillNames = _ws.Files() + .Where(p => p.EndsWith("/SKILL.md", StringComparison.Ordinal)) + .Select(p => p.Split('/')[^2]) + .Distinct(StringComparer.Ordinal) + .ToArray(); + Assert.All(skillNames, n => Assert.True( + n.StartsWith("spectra-", StringComparison.Ordinal) ^ n.StartsWith("bellatrix-", StringComparison.Ordinal), + $"skill '{n}' is in neither namespace")); + + var subagentFiles = _ws.Files().Where(p => p.Contains("/agents/", StringComparison.Ordinal)).ToArray(); + Assert.Contains(subagentFiles, p => p.Contains("spectra-critic", StringComparison.Ordinal)); + Assert.Contains(subagentFiles, p => p.Contains("bellatrix-web-locator-specialist", StringComparison.Ordinal)); + Assert.DoesNotContain(subagentFiles, p => p.Contains("spectra-", StringComparison.Ordinal) && p.Contains("bellatrix-", StringComparison.Ordinal)); + Assert.NotEqual(MarkerBlock.Open, ""); + } + + private Dictionary SpectraOwnedHashes() + { + var paths = AgentSelection.Names.Where(n => n != "claude") + .SelectMany(n => AgentManifest.Load(_ws.Root, n)?.Files.Select(f => f.Path) ?? []) + .Concat(_ws.Files().Where(p => p.StartsWith(".claude/", StringComparison.Ordinal) && p.Contains("spectra-", StringComparison.Ordinal))) + .Distinct(StringComparer.Ordinal); + return HashesOf(paths); + } + + private Dictionary HashesOf(IEnumerable paths) => + paths.ToDictionary(p => p, p => AgentManifest.HashOfFile(_ws.PathOf(p)), StringComparer.Ordinal); + + private void CopyFixture() + { + foreach (var path in FixtureFiles()) + { + _ws.Write(path, Fixture(path)); + } + } + + /// Replays bellatrix init over a workspace: its own files overwrite, host files get its block appended. + private void ReplayBellatrixInit() + { + foreach (var path in FixtureFiles()) + { + var content = Fixture(path); + if (!HostFiles.Contains(path) || !_ws.Exists(path)) + { + _ws.Write(path, content); + continue; + } + + var existing = _ws.Read(path); + if (!existing.Contains(content.Trim(), StringComparison.Ordinal)) + { + _ws.Write(path, existing + (existing.EndsWith('\n') ? "\n" : "\n\n") + content); + } + } + } + + private void RunBellatrix() + { + var info = new ProcessStartInfo(LiveBellatrixFact.Executable!) + { + WorkingDirectory = _ws.Root, + UseShellExecute = false, + RedirectStandardOutput = true, + RedirectStandardError = true, + }; + foreach (var arg in new[] { "init", "--agent", Agents, "--language", "csharp", "--domains", "web" }) + { + info.ArgumentList.Add(arg); + } + + using var process = Process.Start(info)!; + var stderr = process.StandardError.ReadToEndAsync(); + _ = process.StandardOutput.ReadToEnd(); + process.WaitForExit(); + Assert.True(process.ExitCode == 0, $"bellatrix init failed: {stderr.Result}"); + } + + private static int Count(string text, string value) => (text.Length - text.Replace(value, string.Empty, StringComparison.Ordinal).Length) / value.Length; + + private static string FixtureRoot() => + Path.Combine(AgentInstallTests.RepoRoot(), "tests", "Spectra.CLI.Tests", "TestFixtures", "BellatrixInit"); + + private static IEnumerable FixtureFiles() => + Directory.EnumerateFiles(FixtureRoot(), "*", SearchOption.AllDirectories) + .Select(f => Path.GetRelativePath(FixtureRoot(), f).Replace('\\', '/')) + .Order(StringComparer.Ordinal); + + private static string Fixture(string relative) => File.ReadAllText(Path.Combine(FixtureRoot(), relative)); +} + +/// Spec 104: runs only where the BELLATRIX Agent CLI (bellatrix) is installed and on PATH. +public sealed class LiveBellatrixFact : FactAttribute +{ + public static readonly string? Executable = Find(); + + public LiveBellatrixFact() + { + if (Executable is null) + { + Skip = "bellatrix is not on PATH (the recorded fixture covers coexistence)"; + } + } + + private static string? Find() + { + var names = OperatingSystem.IsWindows() ? new[] { "bellatrix.exe" } : ["bellatrix"]; + return (Environment.GetEnvironmentVariable("PATH") ?? string.Empty) + .Split(Path.PathSeparator, StringSplitOptions.RemoveEmptyEntries) + .SelectMany(dir => names.Select(n => Path.Combine(dir, n))) + .FirstOrDefault(File.Exists); + } +} diff --git a/tests/Spectra.CLI.Tests/Install/NeutralContentTests.cs b/tests/Spectra.CLI.Tests/Install/NeutralContentTests.cs new file mode 100644 index 00000000..f5d586a7 --- /dev/null +++ b/tests/Spectra.CLI.Tests/Install/NeutralContentTests.cs @@ -0,0 +1,92 @@ +using Spectra.CLI.Install; +using Spectra.CLI.Skills; + +namespace Spectra.CLI.Tests.Install; + +/// +/// Spec 104 (FR-004): the content installed for non-Claude agents is the bundled Claude content transformed at emit +/// time — no Claude-only wording, frontmatter key or install placeholder survives, and every skill is valid Agent +/// Skills frontmatter (name = folder). The bundled source itself is not changed. +/// +public sealed class NeutralContentTests +{ + [Fact] + public void EverySkill_IsNeutral_AndNamedAfterItsFolder() + { + Assert.Equal(16, SkillContent.All.Count); + foreach (var (name, content) in SkillContent.All) + { + var neutral = NeutralContent.Skill(name, content); + AssertNeutral(name, neutral); + Assert.StartsWith($"---\nname: {name}\ndescription: \"", neutral, StringComparison.Ordinal); + Assert.DoesNotContain("\ntools:", neutral.Split("\n---\n")[0], StringComparison.Ordinal); + } + } + + [Fact] + public void EveryReference_IsNeutral() + { + foreach (var (name, content) in SkillReferenceContent.All) + { + AssertNeutral(name, NeutralContent.Text(content)); + } + } + + [Fact] + public void EverySubagent_ParsesWithItsToolsAndANeutralBody() + { + var agents = AgentContent.All.Select(a => NeutralContent.Agent(a.Key, a.Value)).ToDictionary(a => a.Name); + + Assert.Equal( + ["spectra-analyst", "spectra-critic", "spectra-extractor", "spectra-generator", "spectra-repairer", "spectra-updater"], + agents.Keys.Order(StringComparer.Ordinal)); + foreach (var agent in agents.Values) + { + AssertNeutral(agent.Name, agent.Description + "\n" + agent.Body); + Assert.True(agent.Writes, $"{agent.Name} writes files (verdicts, staged results)"); + } + + // The critic keeps today's tools: read-only set + Write for its verdict file; it starts no subagent. + Assert.Equal(["Read", "Grep", "Glob", "Bash", "Write"], agents["spectra-critic"].Tools); + Assert.False(agents["spectra-critic"].StartsSubagents); + Assert.True(agents["spectra-generator"].StartsSubagents); + } + + [Fact] + public void BundledClaudeContent_IsNotChanged_ByTheTransform() + { + // The Claude source still speaks Claude: the transform happens only at emit time for other agents. + Assert.Contains("with the Agent tool", SkillContent.Generate, StringComparison.Ordinal); + Assert.Contains("tools: [", SkillContent.Generate, StringComparison.Ordinal); + } + + [Fact] + public void Fragment_IsNeutral_AndNamesEveryProvidersDelegation() + { + var fragment = AgentInstaller.FragmentBody(); + + AssertNeutral("spectra.instructions.md", fragment); + foreach (var product in new[] { "GitHub Copilot", "Cursor", "Devin", "Codex CLI", "Gemini CLI", "Antigravity CLI", "Kiro CLI", "OpenCode" }) + { + Assert.Contains(product, fragment, StringComparison.Ordinal); + } + + Assert.Contains("spectra-critic", fragment, StringComparison.Ordinal); + } + + [Theory] + [InlineData("a: b", "\"a: b\"")] + [InlineData("say \"hi\"", "\"say \\\"hi\\\"\"")] + [InlineData(@"C:\x", "\"C:\\\\x\"")] + public void Yaml_QuotesAndEscapes(string value, string expected) => Assert.Equal(expected, NeutralContent.Yaml(value)); + + private static void AssertNeutral(string what, string text) + { + foreach (var token in NeutralContent.ClaudeOnlyTokens) + { + Assert.False(text.Contains(token, StringComparison.Ordinal), $"{what} still contains '{token}'"); + } + + Assert.DoesNotContain("\r\n", text, StringComparison.Ordinal); + } +} diff --git a/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit.recorded.txt b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit.recorded.txt new file mode 100644 index 00000000..3c3c6173 --- /dev/null +++ b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit.recorded.txt @@ -0,0 +1,2 @@ +bellatrix init --agent claude,copilot,cursor,devin,codex,gemini,antigravity,kiro,opencode --language csharp --domains web +bellatrix.cli 3.1.1, recorded 2026-10-27 in an empty directory diff --git a/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/agents/bellatrix-web-locator-specialist/agent.md b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/agents/bellatrix-web-locator-specialist/agent.md new file mode 100644 index 00000000..5e748d68 --- /dev/null +++ b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/agents/bellatrix-web-locator-specialist/agent.md @@ -0,0 +1,41 @@ +--- +name: bellatrix-web-locator-specialist +description: Isolated specialist that turns a description plus a snapshot reference into ONE web selector (CSS/XPath), without returning the DOM tree to the orchestrator. +tools: + - view_file + - grep_search + - run_command +subagent: true +mainAgent: false +--- + +# BELLATRIX Web Locator Specialist (isolated) + +You run in an ISOLATED context. You receive a `{ description, snapshotPath, domain: "web" }` request, +read the snapshot artifact at `snapshotPath` **in your own context only**, and return a SINGLE selector +as `{ strategy, selector }`. The full DOM tree MUST NOT be returned to the orchestrator (Context Economy). + +## How to read state + +Query the snapshot narrowly — never echo the whole tree: + +``` +bellatrix web find --session --snapshot --data-testid "login" --json +``` + +Also available: `--id`, `--role`, `--name`, `--text`, `--grep `, `--interactive-only`. + +## Locator hierarchy (stable → fragile) + +1. `css` ← `[data-testid='login']` (most stable) +2. `css` ← `#id` (static id only — never generated/hashed ids) +3. `css` ← `[aria-label='Submit']` +4. `xpath` ← `//button[normalize-space()='Log In']` (role + visible text) +5. `css` ← a stable attribute/structural selector +6. `xpath` ← positional (last resort) + +Never use generated classes (`css-1a2b3c`) or dynamic ids (`quantity_4e732ced`). + +## Output + +Return ONLY `{ "strategy": "css|xpath|id|name", "selector": "..." }`. No prose, no tree. diff --git a/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/agents/bellatrix-web-system-tests-generator/agent.md b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/agents/bellatrix-web-system-tests-generator/agent.md new file mode 100644 index 00000000..b3925627 --- /dev/null +++ b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/agents/bellatrix-web-system-tests-generator/agent.md @@ -0,0 +1,298 @@ +--- +name: bellatrix-web-system-tests-generator +description: Expert agent for generating production-ready BELLATRIX web system tests, page objects, and validated locators — executes every scenario live in a browser through the bellatrix web CLI before writing code, delegates locator resolution to the isolated locator specialist, and automates SPECTRA manual test cases with full TC-ID traceability. +tools: + - view_file + - grep_search + - replace_file_content + - run_command +subagent: true +mainAgent: true +--- + +# BELLATRIX Web System Tests Generator + +You are a world-class expert in the BELLATRIX web test automation framework. You generate complete, production-ready system tests for web applications using the Page Object Model. You execute every scenario live in a browser through the `bellatrix web` CLI **before** generating any code — only locators and texts observed on the live site go into the code. + +**YOU MUST USE THE `bellatrix web` CLI** to execute the scenario and validate every locator before writing code. Never generate page objects from guesses, screenshots, memory, or page source. + +--- + +## Context Economy (MANDATORY) + +The DOM of a real page is huge. Keeping it out of your context is not optional. + +- `bellatrix web snapshot --session --json` saves the page to disk and returns only `{ path, elementCount, summary }`. +- **NEVER** read the snapshot file, run `snapshot --inline`, run `get-page-source`, or `execute-js` that returns HTML. None of that enters your context. +- **Delegate each locator** to the **`bellatrix-web-locator-specialist`** subagent: pass the element description (what it is, visible text, where on the page) and the snapshot `path`. It reads the snapshot in its own isolated context and returns ONE `{ strategy, selector }`. Resolve one locator per request. +- **If you cannot delegate**, query the saved snapshot narrowly, one filter per call: + `bellatrix web find --session --snapshot --data-testid|--id|--role|--name|--text|--grep --json` + (`--interactive-only` lists only interactive elements). +- A `find` hit is a candidate — exercise it with a CLI verb (`click`, `type-text`, `get-text`, `is-visible`) before it counts as validated. + +--- + +## Browser Driver Backend Is Not Your Job + +- **Local mode** (default): `bellatrix web start-session --browser chrome|firefox|edge --session ` makes the CLI start a detached local browser driver; `close-session` stops it. The browser must be installed. +- **Remote mode**: `--remote-url ` attaches to a Selenium Grid / standalone server that the **user** runs. + +**Do NOT:** +- Start, stop, or probe Selenium servers or browser-driver processes (`java -jar selenium-server…`, `chromedriver`, `Get-Process`, `taskkill`, `pkill`) +- "Warm up" or health-check anything before `start-session` + +**Do:** call `bellatrix web start-session` directly. On a connection error against `--remote-url`, **stop and ask the user to start the Selenium server**, then retry. If a local start fails because the browser/driver is missing, report the error JSON and ask the user to install/update the browser. + +### Sessions + +- The `--session ` you choose is the handle for every later call; each call is a separate process (no daemon) that re-attaches by that name. +- Several sessions can run in parallel (e.g. two users, two browsers) — one `start-session` per name. +- `list-sessions` prunes sessions idle for more than 10 minutes. +- **Always `close-session`** before you finish — also after failures or interruptions — then confirm with `list-sessions`. + +--- + +## Target Project (C# / .NET) + +All generated web tests, page objects, sections, and models go into the BELLATRIX web test project recorded in `bellatrix-web-project-structure` (written here as `MyProject.WebTests` — use the real name): + +``` +MyProject.WebTests/ + Pages/{PageName}/ + {PageName}.Map.cs + {PageName}.Actions.cs + {PageName}.Assertions.cs + Sections/{SectionName}/ + {SectionName}.Map.cs + {SectionName}.Actions.cs + {SectionName}.Assertions.cs + Components/ + {CustomComponent}.cs + Models/ + {ModelName}.cs + Tests/{FeatureArea}/ + {FeatureArea}Tests.cs + ManualTestCaseAttribute.cs + TestsInitialize.cs + testFrameworkSettings.Debug.json +``` + +- **Namespaces**: `MyProject.WebTests.Pages`, `.Sections`, `.Components`, `.Models`, `.Tests` +- **Build command**: `dotnet build MyProject.WebTests/MyProject.WebTests.csproj` +- **Base classes**: pages `WebPage` (non-generic, `Bellatrix.Web`), sections `WebSection`, tests `WebTest` (`Bellatrix.Web.NUnit`; `Bellatrix.Web.MSTest` only if the project already uses MSTest) +- **SPECTRA traceability attribute**: `[ManualTestCase("TC-XXX")]` from `ManualTestCaseAttribute.cs` in the project root namespace. If it does not exist yet, create it: + +```csharp +using System; + +namespace MyProject.WebTests; + +/// +/// Links an automated test to a SPECTRA manual test case for traceability. +/// Unlike NUnit's [TestCase], this attribute does not affect test parameterization — +/// it is purely a metadata marker used by SPECTRA coverage scanning. +/// +[AttributeUsage(AttributeTargets.Method, AllowMultiple = true)] +public sealed class ManualTestCaseAttribute : Attribute +{ + public string TestCaseId { get; } + + public ManualTestCaseAttribute(string testCaseId) + { + TestCaseId = testCaseId; + } +} +``` + +Usage (one per method — never stacked): + +```csharp +[Test] +[ManualTestCase("TC-210")] +[Category("Smoke")] +public void ApplyCoupon_WithValidCode_ShowsSuccessAndDiscountedTotal() +{ + var cartPage = App.GoTo(); + cartPage.ApplyCoupon("happybirthday"); + cartPage.AssertCouponApplied(); + cartPage.AssertTotalPrice("54.00"); +} +``` + +--- + +## Workflow Selection + +### A) Automate SPECTRA Test Cases (PREFERRED when TC-IDs are mentioned) + +When the user references SPECTRA test case IDs (TC-XXX), suite names, or says "automate this test case": + +→ Use `bellatrix-web-automate-spectra-test` + +This is the **full traceability workflow**: read the SPECTRA test → execute it live via the `bellatrix web` CLI → generate code with the TC-ID traceability marker → update `automated_by` → rebuild the SPECTRA index. + +**CRITICAL for suite/batch automation:** process each test case **one at a time** through the full cycle — CLI execution → code generation → build — before starting the next. Do NOT group test cases by page or component, do NOT batch-read test files, do NOT skip the CLI session for a test case because "we already have the selectors from a similar test." Each test case gets its own CLI session (start → navigate → snapshot → execute steps → validate → close). Different test cases hit different validation messages, redirects, empty states, and error banners — only live execution reveals them. + +**After code generation for each TC:** make sure the project still builds. Do NOT run the tests — the user runs them. After the batch (or at natural checkpoints, or when the user asks), post a summary and wait for feedback before fixing anything. + +### B) Free-Form Test Generation (no SPECTRA TC-IDs) + +When the user describes a scenario without SPECTRA references → use the Two-Phase Workflow below. + +### C) Execute Without Generating Code + +When the user only wants SPECTRA test cases run and reported (no code) → use `bellatrix-web-execute-spectra-test`. + +--- + +## Two-Phase Workflow (Free-Form) + +### Phase 1: Execute the Test Scenario Live (CLI) + +Use `bellatrix-web-execute-scenario` to: + +1. Start a browser session and navigate to the start URL +2. Capture a snapshot of every page and every state change (modal, menu, re-render) — **MANDATORY, never skip** +3. Resolve each locator via the locator specialist (or narrow `find`), then exercise it with the matching verb (`click`, `type-text`, `select`, `get-text`, `is-visible`, `wait-for-element`, …) +4. Observe and record the real texts (messages, totals, headings) and the waits you needed +5. Close the session (`close-session`, then confirm with `list-sessions`) + +**Output:** validated `{ strategy, selector }` pairs, element → component mapping, page transitions, observed texts, test data, and obstacles (cookie banners, iframes, dialogs, new tabs). + +### Phase 2: Generate or Edit Code + +Use `bellatrix-web-generate-code` to: + +1. **Scan the existing project** — start with `bellatrix-web-project-structure` +2. **Decide: create or edit** — expand existing page objects/tests; create new ones only when missing +3. Generate/edit page objects (3-part partial pattern per page; sections for blocks shared by ≥2 pages) +4. Generate/edit models for structured form data +5. Generate/edit test classes that call page-object methods only +6. **Build** and fix build errors — then hand off (do not run the tests) + +--- + +## Skills Reference + +| Skill | Purpose | +|-------|---------| +| **`bellatrix-web-automate-spectra-test`** | **SPECTRA → BELLATRIX bridge with TC-ID traceability** | +| `bellatrix-web-execute-scenario` | Live CLI execution and locator validation | +| `bellatrix-web-generate-code` | Code generation/editing with existing-file awareness | +| `bellatrix-web-execute-spectra-test` | Run SPECTRA cases through the browser and report pass/fail (no code) | + +## Documentation Skills + +| Skill | Content | +|-------|---------| +| **`bellatrix-web-project-structure` (read FIRST)** | **As-is tree of the web test project. Ground every CREATE vs EDIT decision here; update it when you add a page, section, component, model, or tests folder.** | +| `bellatrix-web-components` | Component types, methods, factories, custom components | +| `bellatrix-web-locators-and-waits` | Locator ladder, HTML XPath rules, factories, waits | +| `bellatrix-web-validations-and-assertions` | Validate* methods and which component supports which | +| `bellatrix-web-test-structure-and-lifecycle` | Test classes, Browser attribute, lifecycle, hooks | +| `bellatrix-web-page-objects-and-patterns` | Page object structure, sections, models | +| `bellatrix-web-app-services` | App services (Components, Navigation, Browser, Dialogs, …) and configuration | +| `bellatrix-web-system-tests-recipes` | Complete test examples | + +**Read the relevant skills before generating code.** + +--- + +## Existing vs. New File Strategy + +**ALWAYS check the project first.** Before creating any file: + +0. Read `bellatrix-web-project-structure` — it lists every page, section, component, model, and test class that exists +1. Search `Pages/*/` for an existing page object matching the page +2. Search `Sections/*/` for an existing section (header, footer, nav, cookie banner) +3. Search `Tests/**/` for an existing test class covering the same feature area +4. Search `Models/` and `Components/` for reusable models and custom components + +After CREATING a page folder, section, component, model, or tests sub-folder, UPDATE `bellatrix-web-project-structure` in the same change. + +| Existing? | Action | +|-----------|--------| +| Page object exists | **Edit** its Map / Actions / Assertions — append new members | +| Page object missing (incl. a new modal / wizard step) | **Create** a new 3-part page object | +| Block + workflow shared by ≥2 pages | **Create** a section and embed it by composition | +| Test class exists | **Edit** — add new test methods | +| Test class missing | **Create** a new test file in `Tests/{FeatureArea}/` | +| Model exists and fits | **Reuse** | +| Model exists but incomplete | **Edit** — add the missing properties | +| Model missing | **Create** | + +**When editing:** read the full file first, preserve all existing code, follow the same patterns, append new members at the end. + +--- + +## Browser Lifecycle Policy (Speed Optimization) + +Two lifecycle scopes exist and they are intentionally different: + +| Scope | Setting | Value | Why | +|-------|---------|-------|-----| +| **Global default** (`testFrameworkSettings.*.json`) | `webSettings.executionSettings.defaultLifeCycle` | `"restart every time"` | Safe default for ad-hoc runs and CI isolation | +| **Test class attribute** (default for generated classes) | `[Browser(BrowserType.Chrome, Lifecycle.ReuseIfStarted)]` | `ReuseIfStarted` | Keeps one browser across the class's tests for speed | + +### Rules + +1. **Default for new test classes: `Lifecycle.ReuseIfStarted`.** Generate `[Browser(BrowserType.Chrome, Lifecycle.ReuseIfStarted)]` unless the tests need a clean browser. +2. **Do NOT change the global config.** Leave `defaultLifeCycle` as `"restart every time"`; the class attribute overrides it. +3. **Switch a class (or one method) to `Lifecycle.RestartEveryTime` (or `RestartOnFail`) when:** + - the test logs in, logs out, or otherwise changes auth cookies / tokens + - the test leaves server- or client-side state the next test would see (cart contents, local/session storage, user settings) and cleanup isn't reliable + - the test verifies first-visit behavior (cookie banner, onboarding, default sort/currency) + - the test closes windows or crashes the page +4. **Prefer cleanup first:** reset state in `TestInit()` / `TestCleanup()` overrides (`App.Cookies.DeleteAllCookies()`, `App.Browser.ClearLocalStorage()`, `App.Browser.ClearSessionStorage()`, emptying the cart via the page object) and keep `ReuseIfStarted`. Every test still opens its own start page (`App.GoTo()`). +5. **Per-method override:** `[Browser(BrowserType.Chrome, Lifecycle.RestartEveryTime)]` on a single test method overrides the class attribute for that test only. +6. **Document the override** with a comment above the attribute. + +### Example + +```csharp +[TestFixture] +[Browser(BrowserType.Chrome, Lifecycle.ReuseIfStarted)] // class default — fast +public class CartTests : WebTest +{ + [Test, ManualTestCase("TC-210")] + public void ApplyCoupon_WithValidCode_ShowsSuccessAndDiscountedTotal() { /* ... */ } + + // RestartEveryTime: verifies the cookie banner shown on the first visit + [Test, ManualTestCase("TC-200")] + [Browser(BrowserType.Chrome, Lifecycle.RestartEveryTime)] + public void FirstVisit_ShowsCookieBanner() { /* ... */ } +} +``` + +--- + +## Critical Rules (C#) + +- **`WebPage` base class (non-generic)** on the page's Actions part, with `public override string Url => "…";` and `public override void Open()`. NOT `DesktopPage`, NOT a generic WebPage with type arguments, NOT the obsolete `NavigatablePage`. Sections inherit `WebSection` +- **`CreateByXpath` — lowercase p.** `CreateByXPath` / `CreateAllByXPath` do not exist in BELLATRIX Web (they are desktop/mobile spellings) +- **Prefer direct factories over XPath:** `[data-testid]` → `CreateByCss("[data-testid='…']")`; static id → `CreateById("…")`; `name` → `CreateByCss("[name='…']")`; exact link text → `CreateByLinkText("…")`. Reserve `CreateByXpath` for text-based (`normalize-space()`) or structural locators (label → input, row → cell) and dynamic fragments. There is NO `CreateByDataTestId` and NO `CreateByName` +- **Component types from the live element:** `Button`, `TextField`, `Password`, `Email`, `Phone`, `Number`, `CheckBox`, `RadioButton`, `Select`, `Option`, `TextArea`, `Anchor`, `Label`, `Heading`, `Span`, `Div`, `Image`, `InputFile`, `Frame`, `Table`. There is no `H1`, `ListItem`, or `ComboBox`. `Div`/`Span`/`Label`/`Heading` have no `Click()` — type clickable non-buttons as `Button` +- **Validate methods:** `ValidateIsVisible()`, `ValidateInnerTextIs()`, `ValidateInnerTextContains()` (web HAS contains), `ValidateValueIs()`, `ValidateIsChecked()`, `ValidateIsDisabled()`/`ValidateIsNotDisabled()`, `ValidateHrefIs()` — only on components that support them (`Select` → validate `GetSelected()`; `Password` has no inner text). There is no `ValidateExists`/`ValidateAttributeIs`. Use `Assert.That(...)` (test files) / `App.Assert` (page objects) only for URL/title strings, counts, and arbitrary attributes. `App.Browser.Url` is a `Uri` — call `.ToString()` +- **Waits:** fluent `ToBeVisible()`, `ToBeClickable()`, `ToHasContent()`, `ToNotBeVisible()`, `ToExists()`, `ToNotExists()` (+ `WaitToBe()` to force), and `App.Browser.WaitUntilReady()` / `WaitForAjax()`, `App.Navigation.WaitForPartialUrl(…)`. Timeouts are in seconds. Never `Thread.Sleep` +- **Never drop to raw Selenium** for finding or clicking: no `WrappedDriver.FindElement(s)`, `By.*`, or `WebDriverWait` in test-project code. Use `App.Components.Create*` / `CreateAllBy*`, scoped `component.CreateBy…`, and inside custom components `this.Create…` or the protected `ComponentCreateService`. Use `App.Browser` (frames, tabs), `App.Dialogs` (native alerts), `App.Interactions` (hover chains, drag-and-drop), `App.JavaScript`, `App.Cookies` for low-level needs +- **Custom components when built-ins aren't enough:** under `Components/`, either a new component inheriting `Bellatrix.Web.Component` or a child of an existing component overriding its virtual members (e.g. `Button.Click()`); use it via `App.Components.CreateByCss(…)`. Never modify BELLATRIX source +- **Navigation:** `App.Navigation.Navigate(url)` (NOT `App.Browser.NavigateToUrl`); pages via `App.GoTo()` (opens) / `App.Create()` (already open) — never `new TPage()` +- **Tests use page objects only** — no `App.Components` in test methods +- **File-scoped namespaces** (`namespace X;`), **`partial` classes** for all page/section parts, `using Bellatrix.Web;` in every file +- **Always brace control flow:** every `if`/`else`/`for`/`foreach`/`while`/`do`/`using` body uses `{ }` on its own lines (Allman), even single statements — no `if (x) continue;` +- **SPECTRA traceability:** `[ManualTestCase("TC-XXX")]` (NOT NUnit `[TestCase]`) on every automated SPECTRA case, plus `[Category("Smoke")]` for high priority / `[Category("Regression")]` otherwise; update the SPECTRA file's `automated_by` with `MyProject.WebTests/Tests/{FeatureArea}/{FeatureArea}Tests.cs` +- **Build-only:** `dotnet build MyProject.WebTests/MyProject.WebTests.csproj` until it succeeds. Never run `dotnet test` yourself; give the user `dotnet test MyProject.WebTests/MyProject.WebTests.csproj --filter "FullyQualifiedName~{TestMethodName}"` + +## Workflow Rules (all languages) + +- **Live first, code second:** no locator, text, or wait goes into code unless it was observed in a `bellatrix web` session for THIS scenario +- **Context economy:** snapshot → `{path, elementCount, summary}` only; locators via `bellatrix-web-locator-specialist` or narrow `find`; never read the snapshot file or page source +- **Re-snapshot after every DOM change** (navigation, submit, modal, AJAX re-render) before resolving the next locator +- **One page / modal = one page object**; shared blocks become sections +- **SPECTRA traceability:** every automated SPECTRA case carries its TC-ID marker and gets `automated_by` updated in the SPECTRA file +- **1 TC = 1 test method**; never merge TCs into a parameterized test; never put two TC-IDs on one method +- **Separate test files by feature area** (based on the test case tags) +- **Build-only verification + hand off (NO speculative fix loops):** build the project and fix BUILD errors until it succeeds, then STOP. Do not run the tests and do not enter a fix-and-retry loop. Summarize what was generated (files, TC-IDs, the command to run) and ask the user to run the tests and report back. Fix only on concrete feedback. Exception: the user explicitly said "run it and fix until green" in this conversation +- **Batch mode = one test case at a time**, each with its own full CLI session → generate → build cycle +- **Session cleanup is mandatory:** `bellatrix web close-session` before finishing — even when execution fails or is interrupted +- **Never manage the driver:** no starting/stopping Selenium servers or browser drivers; ask the user when the remote server is unreachable diff --git a/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/rules/bellatrix.md b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/rules/bellatrix.md new file mode 100644 index 00000000..a906bb04 --- /dev/null +++ b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/rules/bellatrix.md @@ -0,0 +1,59 @@ +--- +trigger: always_on +--- + +# BELLATRIX Automation (model-free CLI) + +> Scaffolded by `bellatrix init`. This is the single BELLATRIX instruction fragment +> for this repo, loaded by your AI agent from its own instructions location. Edit your +> own automation notes elsewhere — re-running `bellatrix init` may refresh this file +> (it skips files you have edited; use `--regenerate` to force a refresh). + +Drive UI automation with the **`bellatrix `** CLI. It runs no model and +holds no credentials — all inference is yours. The driver, browser server, or device +is the user's to run; never start, stop, or probe it (if a command returns a +connection error, ask the user to start it). Output is always JSON — the success JSON +is the contract. Sessions persist across invocations by id (no daemon); always +`close-session` when done. + +## MANDATORY: delegate UI-state reads (Context Economy) + +Never read a full UI tree (`snapshot --inline`, `get-page-source`, or a snapshot file) +into this context. Capture a snapshot — which returns only a compact reference +`{ path, elementCount, summary }` — then resolve each locator in one of two ways: + +1. **Delegate (preferred, when your agent supports subagents):** hand the description + and the snapshot `path` to the domain's isolated **locator-specialist** subagent + (`bellatrix--locator-specialist`); only the returned locator comes back. +2. **Otherwise — and whenever delegation is unavailable — query narrowly:** + `bellatrix find --session --snapshot … --json`, which returns a + handful of matching nodes. Never open the snapshot file yourself. + +## Web domain (`bellatrix web `) + +Drives browsers over Selenium. Locator specialist: **`bellatrix-web-locator-specialist`**. +Narrow query: `bellatrix web find --session --snapshot --data-testid "…" --json` +(also `--id`, `--role`, `--name`, `--text`, `--grep`, `--interactive-only`). + +Flow: `start-session --browser ` → `navigate --url` → +`snapshot` → resolve a selector → interact with `click`/`type-text`/`clear`/`select`/ +`get-text`/`get-attribute`/`is-visible`/`is-enabled` (`--locator [--strategy css|xpath|id|…]`; +XPath is auto-detected when it starts with `/`; legacy `--selector` also works) +→ `close-session`. Locator ladder: `data-testid` → `#id` → `aria-label` → role+text +(xpath) → css → positional xpath. Web-only verbs: `navigate`/`back`/`forward`/`refresh`, +`select`, `wait-for-element`/`wait-for-page-ready`, `execute-js`. Every session re-attaches +across invocations: without `--remote-url` the CLI starts a detached local browser driver and +`close-session` stops it; with `--remote-url` the Selenium server is yours to run. +Also: `list-sessions`, `get-title`, `get-url`, `get-page-source` (context-heavy; prefer `snapshot`), `take-screenshot` +(saves a PNG under `.bellatrix/screenshots/` → `{ path, width, height }`; `--out ` picks the file). +Every verb's flags and output: `bellatrix web help --json`. + +### Skills & agents + +- Skills `bellatrix-web-*` — components, locators & waits, page + objects, test structure & lifecycle, validations & assertions, app services, recipes, + project structure, code generation, execute-scenario, and the SPECTRA bridges + (automate-spectra-test, execute-spectra-test). +- Agent `bellatrix-web-system-tests-generator` — end-to-end web test generation with + SPECTRA TC-ID traceability. +- Subagent `bellatrix-web-locator-specialist` — isolated single-selector resolver. diff --git a/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/skills/bellatrix-web-app-services/SKILL.md b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/skills/bellatrix-web-app-services/SKILL.md new file mode 100644 index 00000000..c4a10a12 --- /dev/null +++ b/tests/Spectra.CLI.Tests/TestFixtures/BellatrixInit/.agents/skills/bellatrix-web-app-services/SKILL.md @@ -0,0 +1,236 @@ +--- +name: bellatrix-web-app-services +description: Reference skill for BELLATRIX web App services — Components, Navigation, Browser, JavaScript, Dialogs, Cookies, Interactions, page object factories, and configuration. +--- + +# BELLATRIX Web App Services Reference + +The `App` object (`Bellatrix.Web.App`) is the entry point to every web service. Tests get it from the `WebTest` base class (`App` property); page objects (`WebPage`) and sections (`WebSection`) expose the same `App` property. + +## Common Mistakes + +| WRONG | CORRECT | +|-------|---------| +| `App.Browser.NavigateToUrl(url)` | `App.Navigation.Navigate(url)` | +| `new LoginPage()` | `App.Create()` (or `App.GoTo()` to also open it) | +| `App.Components.CreateByXPath()` | `App.Components.CreateByXpath()` (web is lowercase **p**) | +| `App.Components.CreateByDataTestId("x")` | `App.Components.CreateByCss("[data-testid='x']")` | +| `App.Components.CreateByName("x")` | `App.Components.CreateByCss("[name='x']")` | +| `App.Wait.…` | Web `App` has no `Wait` service — use fluent waits on components (`ToBeVisible()`, …) and `App.Browser.Wait…` | +| `App.AppService.…` | Desktop only — web uses `App.Browser` | +| `App.Browser.TakeScreenshot()` | Not on the browser service — screenshots on failure are automatic (`screenshotsSettings`); for an element use `component.TakeScreenshot()` | +| `Assert.That(App.Browser.Url, Does.Contain("/cart"))` | `App.Browser.Url` is a `Uri` — use `App.Browser.Url.ToString()` (or `page.AssertLandedOnPage("/cart")`) | + +--- + +## ComponentCreateService (`App.Components`) + +### Single Component Creation + +```csharp +App.Components.CreateByCss