Skip to content

spectra init --agent: install for 8 more AI agents (additive, Claude unchanged) - #63

Merged
angelovstanton merged 6 commits into
mainfrom
104-multi-agent-init
Oct 27, 2026
Merged

angelovstanton merged 6 commits into
mainfrom
104-multi-agent-init

Conversation

@angelovstanton

Copy link
Copy Markdown
Member

spectra init --agent <list> installs SPECTRA's skills, subagents and always-on instructions for eight more AI agents: copilot, cursor, devin (alias windsurf), codex, gemini, antigravity (alias agy), kiro and opencode. --agent auto detects them the way BELLATRIX Agent does. --regenerate overwrites files you edited, and --dry-run writes nothing and prints the plan. Version 2.7.0.

The change is additive. The new layer lives in src/Spectra.CLI/Install/ and is used only for the non-Claude agents.

Golden rule: the Claude install is unchanged

  • spectra init without --agent behaves exactly as before. The only addition is a one-line stderr notice naming the other agents, and only in human output; JSON mode is unchanged.
  • The Claude install stays byte-identical: same paths, same file contents, same .claude/settings.json merge, same .spectra/skills-manifest.json. No skill, subagent or prompt content for Claude changed, and no workflow logic changed (generation, critic, verdict, repair, review-flagged, execution).
  • The only edit to existing code is an installClaude = true parameter on InitHandler.HandleAsync, which guards the two Claude-only calls. Its default is today's behaviour.
  • Test: tests/Spectra.CLI.Tests/Golden/ClaudeInstallGoldenTests.cs pins all 40 files a fresh spectra init writes, plus the merge into an existing .claude/settings.json. It compares each file's path and SHA-256 (line endings normalised). The golden files in Golden/104/ were recorded on main before any other change in this branch and pass unchanged on every commit.

Provider table

Placement was checked against each provider's official docs on 2026-10-27. S = the shared fragment .spectra/spectra.instructions.md.

--agent Instructions (always on) Skills Subagents Project allowlist Docs
copilot .github/instructions/spectra.instructions.md .github/skills (reuses .claude/skills) .github/agents/*.agent.md (reuses .claude/agents) none documented, skipped skills · custom agents
cursor .cursor/rules/spectra.mdc .cursor/skills (reuses .claude/skills / .agents/skills) .cursor/agents/*.md .cursor/cli.json Shell(spectra) subagents · permissions
devin / windsurf .devin/rules/spectra.md .devin/skills .devin/agents/*.md .devin/config.json Exec(spectra) extensibility · rules · subagents · permissions
codex AGENTS.md marker block → S .agents/skills .codex/agents/*.toml none (sandbox policy only), skipped skills · subagents · AGENTS.md
gemini GEMINI.md marker block @./S .agents/skills .gemini/agents/*.md workspace policies have no effect, skipped subagents · skills · policy engine
antigravity / agy .agents/rules/spectra.md .agents/skills .agents/agents/<name>/agent.md none documented, skipped rules · skills · subagents
kiro .kiro/steering/spectra.md .kiro/skills .kiro/agents/*.md per-agent only, skipped custom agents · skills · tools
opencode AGENTS.md marker block → S (shared with Codex) .opencode/skills (reuses .claude/skills / .agents/skills) .opencode/agents/*.md opencode.json permission.bash["spectra *"] agents · permissions

All 18 recorded decisions are in FINDINGS-multi-client-gap-v2.md.

Decisions that differ from the brief

  • No auto-detect by default. Without --agent, init stays Claude-only, as the golden rule requires. BELLATRIX's detection is available as --agent auto: it uses existing manifests, or exactly one detected agent, and never guesses.
  • The critic keeps the Write tool. It writes .spectra/verdicts/critic-verdict-<id>.json, which ingest-verdict reads. A strictly read-only critic would break that, so:
    • Cursor gets no readonly: true, which would block the write.
    • Kiro gets ["read", "write", "shell"].
    • Devin documents no name for a write tool, so its subagents stay unrestricted. Following BELLATRIX's rule, an undocumented tool name is never listed.
  • All six subagents are installed, not only the critic, because the skills delegate to the analyst, generator, updater, repairer and extractor too.
  • Permissions only where a project-level allowlist is documented (Cursor, Devin, OpenCode), merged by key. Gemini's workspace policies are documented as having no effect, so they are skipped.
  • update-skills is unchanged and refreshes only the Claude install. Re-running spectra init --agent <list> refreshes the others. That step is hash-gated, so files you edited are skipped unless you pass --regenerate.
  • An initialised workspace gets only the new agents. spectra init --agent x on a workspace that already has spectra.config.json installs only the non-Claude agents. It leaves the config and the Claude files alone; before this change, init refused there.
  • Devin reads skills from .devin/skills, not .claude/skills as in BELLATRIX, because Devin's docs list only .github/skills as an import source for skills.

Known limitation: the critic outside Claude Code

Only Claude Code runs a subagent from a skill instruction as an enforced, isolated step. In the other agents, delegation is the model's choice: Codex delegates only when asked, and Gemini on @name or by its own choice. The critic therefore runs when the agent follows the skill's instruction. Its isolated-context guarantee is not platform-enforced there. The README and the skills-integration page say so. A CLI-enforced critic gate is planned for a later version.

Live verification

The automated tests check every installed file byte for byte. Whether each agent actually loads the files and starts the critic needs a person and a real session. Checklist and results table: docs/live-verification-agents.md. It has not been run yet.

Tests

  • Per-agent goldens: one per agent plus one for all agents (Golden/104/agent-*.txt).
  • Coexistence:
    • agents sharing .agents/skills and AGENTS.md
    • with Claude installed before and after
    • re-runs (0 written) and --regenerate
    • aliases, auto, --dry-run (writes nothing)
    • user-edited files skipped
    • foreign files never touched
  • BELLATRIX coexistence, both orders:
    • against a recorded bellatrix init 3.1.1 output (all 9 agents)
    • against the installed bellatrix tool when it is on PATH; skipped otherwise
    • neither tool changes the other's files, and the marker blocks and all skill/subagent names stay distinct
  • Local runs:
    • Core 1,245, Execution 228 and Integration 8 pass.
    • In the CLI project, the 538 tests in the affected classes pass: init, skills, docs guards, both goldens and the 44 new tests.
    • The full CLI suite runs here in CI.

🤖 Generated with Claude Code

Every file spectra init writes without --agent, by path and line-ending-normalised
SHA-256 (fresh workspace, and over a user's existing .claude/settings.json).
The skills manifest's recorded hashes are verified against the files on disk and
masked, so the pin holds on Windows and Linux checkouts alike.
Re-verified FINDINGS-multi-client-gap.md against main after #47/#58: 16 skills,
6 subagents, no context:fork any more, Codex now reads .agents/skills, Antigravity
replaced consumer Gemini CLI, Kiro/OpenCode/Cursor/Devin added. Provider table with
doc URLs and the 18 recorded design decisions.
New emitter layer (src/Spectra.CLI/Install/) used only for non-Claude agents:
copilot, cursor, devin (windsurf), codex, gemini, antigravity (agy), kiro,
opencode, plus `auto` detection, with BELLATRIX Agent's names and markers.

- NeutralContent: the bundled skills/references/subagents transformed at emit
  time (neutral wording, Claude tools key dropped, name = folder, quoted YAML);
  the embedded source is untouched.
- One AgentTarget per provider: native always-on fragment (or one marker block in
  AGENTS.md / GEMINI.md), skills dir, the 6 subagents in native format and tool
  names, documented allowlists only (Cursor, Devin, OpenCode).
- AgentInstaller: set-cover skill dirs (.claude/skills reused when present),
  R6 hash gate with .spectra/manifest.<agent>.json, --regenerate, retiring
  unedited files, --dry-run.
- InitHandler: only an installClaude = true guard on the two Claude-only calls;
  init without --agent is byte-identical (golden) and prints one notice line.
…LATRIX

- Golden/104/agent-<name>.txt per agent and agent-all.txt; --agent claude is
  byte-identical to plain init; the Claude files are unchanged in an all-agents
  install.
- Re-runs (plain and per-agent --regenerate) are byte-stable; user edits are
  skipped unless --regenerate; retired files only when unedited.
- Aliases (windsurf, agy), usage errors, auto-detect, --dry-run writes nothing,
  --skip-skills, AGENTS.md/GEMINI.md human bytes kept (R1), allowlists merged by
  key, R8 namespace.
- BELLATRIX coexistence in both orders against a recorded fixture of
  bellatrix init 3.1.1 (all 9 agents, web), plus live variants when bellatrix
  is on PATH.
- README, getting-started, skills-integration, cli-reference: `spectra init
  --agent`, the per-agent table (instructions, skills, subagents, delegation,
  allowlist), re-runs/--regenerate, BELLATRIX coexistence, update-skills note,
  and the known limitation (critic isolation is platform-enforced only in
  Claude Code; a CLI-enforced critic gate is planned).
- New docs/live-verification-agents.md: per-agent checklist (scaffold, skills
  visible, one generate run, critic invoked) and a results table.
- CHANGELOG 2.7.0; Directory.Build.props 2.7.0; CLAUDE.md row 104.
- The plain-init notice is printed in human output only, so JSON-mode output
  (and the 099 golden) is unchanged.
- Docs/source guards: GitHub Copilot as an `--agent` install target is not the
  removed SDK (explicit allow-list lines; paragraphs naming the option or the
  other agents).
Copilot AI balanced review requested due to automatic review settings October 27, 2026 22:24

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

@angelovstanton
angelovstanton merged commit 7496d08 into main Oct 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants