Spectre Rewrite Subagent

Spectre Subagent Rewrite

Rewrite one or more Spectre subagent definitions from broad persona prompts into focused worker contracts. Produce a reviewable proposal by default; apply changes to the live plugin only when the user explicitly asks.

Inputs

• Target agent names from $ARGUMENTS (finder, analyst, patterns, reviewer, tester, dev, web-research) or explicit file paths.
• Source path: plugins/spectre/agents/<agent>.md.
• Generated Codex path: plugins/spectre-codex/agents/<agent>.toml.
• Mode:
  • proposal by default: write review artifacts only.
  • apply only if the user explicitly asks to update live definitions.

Assume cwd is the Spectre repo root. If no target is provided, ask which subagent to rewrite.

Grounding

Read these before drafting:

1. docs/tasks/main/research/subagent_definition_best_practices_053126.md - subagent best practices and practitioner findings.
2. The source agent file(s) in full.
3. scripts/translators/agents.cjs only when applying or checking Codex TOML generation.
4. docs/spectre-design-research.md only if deciding whether a block is load-bearing or generic bloat.

Source of truth is plugins/spectre/agents/*.md; generated TOML is derived output.

Procedure

1. Inventory The Agent

Record:

• name, description, tools, codex_sandbox_mode, model, and body line/token size.
• Whether the role is read-only, write-capable, or ambiguous.
• Current generated Codex name, description, sandbox_mode, and developer_instructions if present.
• Known risks from the research doc: chatty description, write access on read-only role, generic capability catalog, mandatory artifact writes, missing return contract, or context-sharing assumptions.

2. Classify The Role

Choose one primary role and make the rewrite fit it:

• locator: finds files/areas; returns grouped paths only.
• analyst: explains how code works; returns cited implementation facts.
• pattern-miner: finds reusable examples; returns 2-5 examples and recommendation.
• reviewer: identifies risks/findings; returns severity-ranked findings first.
• tester: writes or verifies tests; decide whether it is write-capable or read-only.
• implementer: writes code; may edit files and run commands.
• web-briefer: verifies current/third-party facts; returns sourced findings.

If a source agent mixes roles, flag the split decision instead of silently broadening it.

3. Block Triage

Walk the source top to bottom. For each block, assign one verdict:

• KEEP: changes behavior measurably.
• CUT: persona filler, generic expertise, tutorials, marketing, jokes, or capability catalogs the model already knows.
• CONTRACT: restate as mission, inputs, boundaries, method, or return contract.
• PERMISSION: move to tools/sandbox/model decision.
• REFERENCE: preserve only by linking to an existing reference doc.

Keep specifics that define behavior: routing triggers, scope boundaries, least-privilege tools, citations, exact output schema, empty-result behavior, verification commands, artifact paths, and "do not write" constraints.

4. Draft The Agent Contract

Use this shape unless the existing agent has a stronger local convention:

---
name: <agent>
description: <one or two sentences: trigger, boundary, return type>
tools: <least-privilege tool list>
codex_sandbox_mode: <read-only|workspace-write>
model: <model if intentionally set>
---

You are a focused <role>. <One sentence mission.>

## Mission
<What this agent produces, not a broad capability list.>

## Inputs Expected
- <files/diff/range/task/error/source constraints expected from parent>

## Boundaries
- <what to do>
- <what not to do, especially write/no-write and no nested delegation>

## Method
- <only role-specific heuristics and failure-mode guards>

## Return Contract
<compact schema; include citations, uncertainty, empty-result behavior, and max summary size if useful>

Description rules:

• Put all trigger and "do not use when" information in the frontmatter description.
• Be specific, not long.
• Remove jokes, sales language, and second-person coaching.

Tool rules:

• Read-only roles default to Read, Grep, Glob, LS and codex_sandbox_mode: read-only.
• Web research adds web tools only.
• Implementers/test authors may use write/edit/bash and workspace-write.
• If a role sometimes writes and sometimes verifies, flag whether to split it.

Return rules:

• Require compact, structured output.
• Require file:line for code claims.
• Require links/version/date notes for web claims.
• State what to return when no findings or no matches are found.