🤖 Guidance pass B: fix stale and contradicting Spire text
This commit is contained in:
@@ -14,7 +14,6 @@ the Spire plugin's own home — work here is work ON Spire.
|
||||
- **Adepts**: Listed by `spire:adepts` at boot. Domain knowledge agents with persistent folders at `docs/workpad/adepts/<domain-slug>/`.
|
||||
- **Pinned agents** (prefer these over generic tiers):
|
||||
<!-- None pinned in .claude/agents/ yet -->
|
||||
- **Verification commands**: `just --list` (minimal Justfile — `claude-rc` recipe only)
|
||||
- **Domain skills to route to subagents when relevant**:
|
||||
- `gitea:*` — Gitea issue and PR management
|
||||
- **Conventions**:
|
||||
@@ -24,12 +23,21 @@ the Spire plugin's own home — work here is work ON Spire.
|
||||
- Marketplace repo — each plugin under `plugins/` is self-contained
|
||||
- Working documents live in `docs/workpad/`
|
||||
|
||||
## Build
|
||||
|
||||
Read by `spire:implementation`. Unset means the skill's default; `none` means deliberately absent.
|
||||
|
||||
Reliquary is a markdown plugin marketplace. Most work is skill and agent text, so there is no compile step.
|
||||
|
||||
- **Gate** (cheap, between blocks): none
|
||||
- **Tests** (once per phase): `uv run --no-project --python 3.12 python -m unittest discover -s tests`, run from `plugins/spire/skills/gremlins`. It covers gremlins only. Other plugins have no test suite.
|
||||
|
||||
## Spire structure
|
||||
|
||||
This is the home repo. The plugin itself lives at `plugins/spire/`.
|
||||
|
||||
- **Agents**: `plugins/spire/agents/` — igor, athanor, adept, researcher, scout, search, zathras
|
||||
- **Skills**: `plugins/spire/skills/` — adepts, curator, igor, implementation, init, knowledge, project, research, research-tree, svg, workpad, zathras
|
||||
- **Agents**: `plugins/spire/agents/` — adept, athanor, attacker, igor, planner, researcher, reviewer, scout, search, zathras
|
||||
- **Skills**: `plugins/spire/skills/` — adepts, curator, gremlins, igor, implementation, init, knowledge, project, research, research-tree, svg, workpad, zathras
|
||||
- **Plugin config**: `plugins/spire/.claude-plugin/plugin.json`
|
||||
- **Design spec**: `docs/workpad/designs/2026-09-14-plugin-design-spec.md`
|
||||
- **Legacy**: `plugins/g4b_ai/` still exists (predecessor, being phased out)
|
||||
|
||||
@@ -62,7 +62,7 @@ When Igor resumes you with review findings: one fix pass over all of them, commi
|
||||
|
||||
## Tools, not the loop
|
||||
|
||||
Use what the harness and the project give you: a fail-first test inside a block, a look one layer up before fixing a stubborn failure, evidence before you claim a gate or test result, parallel agents only for genuinely independent blocks. Superpowers is not part of the loop; if a brief asks for it, `spire:implementation` `references/superpowers.md` says which of its rules the lean rules override.
|
||||
Use what the harness and the project give you: a fail-first test inside a block, a look one layer up before fixing a stubborn failure, evidence before you claim a gate or test result, parallel agents only for genuinely independent blocks.
|
||||
|
||||
## Non-build briefs
|
||||
|
||||
|
||||
@@ -20,14 +20,14 @@ You are a deep research agent. Your job is to investigate a topic thoroughly, sy
|
||||
## What you must NOT do
|
||||
|
||||
- **Never spawn sub-agents.** You do not have the Agent tool. You do not delegate. You do the research yourself, end to end.
|
||||
- **Never crawl websites.** Fetch specific pages — at most 3–5 per assignment. If you need more breadth, say so in your report and let the orchestrator decide.
|
||||
- **Never crawl websites.** Fetch specific pages — at most 5 per assignment (see Web content budget). If you need more breadth, say so in your report and let the orchestrator decide.
|
||||
- **Never follow every link on a page.** Read the page you fetched, extract what you need, move on.
|
||||
|
||||
## How to research
|
||||
|
||||
1. **Understand the brief.** Read your assignment carefully. Identify what you need to find out and what form the output should take.
|
||||
2. **Search before you fetch.** Check local code, docs, and git history first. Use WebSearch to find the right URLs before fetching blindly.
|
||||
3. **Fetch targeted pages.** Download 1–3 key sources as markdown. Read them. Extract findings.
|
||||
3. **Fetch targeted pages.** Download the key sources as markdown, within the cap below. Read them. Extract findings.
|
||||
4. **Synthesize, don't summarize.** Your value is in connecting information across sources and drawing conclusions — not in restating what each source said.
|
||||
5. **Write the report.** If given an output path, write your findings there as markdown. Structure it for a reader who will skim headings first.
|
||||
|
||||
|
||||
@@ -4,11 +4,6 @@ description: Lists the adept domains in the workpad — what each covers, when i
|
||||
allowed-tools: Bash(bash:*)
|
||||
---
|
||||
|
||||
<!-- Note: This skill uses Bash(bash:*) in allowed-tools — a novel pattern.
|
||||
All other Spire skills use Bash(cat:*). The bash permission is needed
|
||||
because the injection runs a script, not a simple cat. Per harness
|
||||
design this should pre-approve the command at load time. -->
|
||||
|
||||
!`bash "${CLAUDE_SKILL_DIR}/roster.sh"`
|
||||
|
||||
<!-- Empty roster: no adepts/ folder yet, or /spire:init has not been run. -->
|
||||
|
||||
@@ -40,7 +40,7 @@ The shape, not a menu:
|
||||
- "An adept for that already lives in the workpad. I'll wake it."
|
||||
- "Into the journal with that, before it escapes."
|
||||
|
||||
Project-specific knowledge (pinned agents, build commands, workpad location, conventions) is loaded by the `spire:project` skill at agent startup. If it loaded the blank template (the hint says "run /spire:init"), try reading `.claude/spire/project.md` directly before orienting from scratch. Deeper detail comes from the project's knowledge navigation skill if available, otherwise orient via direct file reads.
|
||||
Project-specific knowledge (pinned agents, build commands, workpad location, conventions) is loaded by the `spire:project` skill at agent startup. If it printed "No project config found. Run /spire:init …" instead, try reading `.claude/spire/project.md` directly before orienting from scratch. Deeper detail comes from the project's knowledge navigation skill if available, otherwise orient via direct file reads.
|
||||
|
||||
## Session start
|
||||
|
||||
@@ -95,7 +95,7 @@ The `athanor` is the forge — your heavy lifter. A build furnace pinned to Opus
|
||||
|
||||
Igor routes work through the stages below. Not every task enters the cycle — one-off fixes, ad-hoc questions, and maintenance stay outside it. The line: if writing the plan would take longer than doing the work, it is not in the cycle.
|
||||
|
||||
**Stages:** (1) Brainstorm — Igor with user or Pinky; skip when direction is clear. If a grilling skill is installed (e.g. `grill-me`, `grill-with-docs`), Igor may use it for a light brainstorm: facts are Igor's to find, decisions are the user's (trial since 0.2.2). (2) Research — researcher/adept answers open questions. (3) Design — independent Opus agent produces one buildable approach. (4) Plan — the `planner` (never the designer) produces steps with completion criteria, at the plan altitude in `spire:implementation`. (4b) Attack the plan — Igor dispatches the `attacker`, fresh (never the planner), that tests the plan adversarially against the code (blockers, design errors, missed consumers of changed semantics), then reshapes it into a build plan: phases that end testable, blocks one owner can finish. One step. It is what pays for dropping per-task review. Show the user the build plan and its open decisions before the door closes. (5) Build — the Athanor builds one phase per turn: blocks, a cheap gate between them, tests once, a run log. (6) Phase review — Igor dispatches a fresh `reviewer` per phase, without the attack's risk list as its scope; it answers every handoff flag, hunts weakened checks and tests that cannot fail, and stamps its model id. Details in `spire:implementation`.
|
||||
**Stages:** (1) Brainstorm — Igor with the user; skip when direction is clear. If a grilling skill is installed (e.g. `grill-me`, `grill-with-docs`), Igor may use it for a light brainstorm: facts are Igor's to find, decisions are the user's. (2) Research — researcher/adept answers open questions. (3) Design — independent Opus agent produces one buildable approach. (4) Plan — the `planner` (never the designer) produces steps with completion criteria, at the plan altitude in `spire:implementation`. (4b) Attack the plan — Igor dispatches the `attacker`, fresh (never the planner), that tests the plan adversarially against the code (blockers, design errors, missed consumers of changed semantics), then reshapes it into a build plan: phases that end testable, blocks one owner can finish. One step. It is what pays for dropping per-task review. Show the user the build plan and its open decisions before the door closes. (5) Build — the Athanor builds one phase per turn: blocks, a cheap gate between them, tests once, a run log. (6) Phase review — Igor dispatches a fresh `reviewer` per phase, without the attack's risk list as its scope; it answers every handoff flag, hunts weakened checks and tests that cannot fail, and stamps its model id. Details in `spire:implementation`.
|
||||
|
||||
**Separation rule:** Plans and designs are always written by independent agents. The author of a plan never implements it or attacks it; the author of a design never plans from it; the builder never reviews its own phase. Separation keeps review honest.
|
||||
|
||||
@@ -169,7 +169,7 @@ Roster matching uses the gravity-well rule: pick the slug that fits most strictl
|
||||
|
||||
## Rules
|
||||
|
||||
- **Agents write their own reports.** Give every dispatched agent an explicit output file path in the workpad (`reports/`, `research/`, etc.). Research briefs ask for findings and options, not verdicts; the user decides. Never collect raw findings and re-summarize them yourself — read the finished files and give the user a short synthesis with links. Read reports for synthesis, not for verification. If a report looks wrong, dispatch a follow-up; don't become the verifier.
|
||||
- **Agents write their own reports.** Give every dispatched agent that can write (not `scout` or `search`) an explicit output file path in the workpad (`reports/`, `research/`, etc.). Research briefs ask for findings and options, not verdicts; the user decides. Never collect raw findings and re-summarize them yourself — read the finished files and give the user a short synthesis with links. Read reports for synthesis, not for verification. If a report looks wrong, dispatch a follow-up; don't become the verifier.
|
||||
- **Journal.** Keep the session journal append-only and current: what was dispatched, what came back, decisions, course corrections. Take times from `date`, not from feel.
|
||||
- **A "no" is a lull, not a stop.** When you offer a follow-up and the user declines ("no," "nah," "I'm good"), that pause is the cheapest moment to bring the journal current — do it then. Then close the beat with one line: a short acknowledgment, or the next natural thread if one exists. Don't stop dead; silence reads as a crash.
|
||||
- **Talk to the user directly, keep details in files.** Questions and decisions go to the user conversationally and concisely; long-form material lives in the workpad.
|
||||
|
||||
@@ -84,5 +84,4 @@ Read these from `spire:project` (its `## Build` section; `project.local.md` wins
|
||||
## Composition
|
||||
|
||||
- **`workpad`** decides where documents go. **`research-tree`** comes first when how to build is itself an open question.
|
||||
- **Superpowers** is not part of this cycle. When to use it anyway (e.g. with older models) and which of its rules this skill overrides: `references/superpowers.md`.
|
||||
- This skill does not govern code style, test frameworks, CI or plan formats.
|
||||
|
||||
@@ -59,7 +59,7 @@ The harness changes. When a claim fails, fix it here with a new date.
|
||||
|---|---|
|
||||
| The Agent tool schema documents `subagent_type: "fork"`: a fork always inherits the caller's model; the `model` parameter is ignored. | verified 2026-10-05 (schema text) |
|
||||
| `fork` is actually offered as an agent type in a given session. | unverified: the schema mentions it, but on 2026-10-05 it was not in the list of agent types offered to the reviewer |
|
||||
| A fork copies the **caller**, not an arbitrary agent. Only the agent holding a context (e.g. the Athanor as trunk) can fork it. | assumed (no parameter names a fork source; Igor's skill calls it "forking yourself") |
|
||||
| A fork copies the **caller**, not an arbitrary agent. Only the agent holding a context (e.g. the Athanor as trunk) can fork it. | assumed (no parameter names a fork source) |
|
||||
| A fork starts with the caller's full transcript, so it starts at the caller's token count. | assumed, not measured |
|
||||
| Can a fork fork again? Does a foreground fork return its result to the caller? Does it see the caller's preloaded skills? | unknown; check in a throwaway preflight before relying on trunk and forks |
|
||||
|
||||
|
||||
@@ -223,7 +223,6 @@ covers:
|
||||
- <path/to/main/source/>
|
||||
- <path/to/tests/>
|
||||
related: []
|
||||
status: active
|
||||
---
|
||||
# <Domain Name>
|
||||
|
||||
|
||||
@@ -97,4 +97,3 @@ If the summary turned out hard to write, that's a signal — see the contradicti
|
||||
|
||||
- The internal structure of an individual research report — that's the agent's call, plus project conventions.
|
||||
- Whether the workpad itself exists / where it lives — defer to the `workpad` skill.
|
||||
- Picking which model to use for which agent — out of scope here.
|
||||
|
||||
@@ -56,10 +56,7 @@ When research requires information from the web:
|
||||
- `WebSearch` — searches the web and returns results with snippets. Use to find the right URL before fetching.
|
||||
|
||||
**MCP servers for richer web-to-markdown conversion (if configured):**
|
||||
- `@anthropic/fetch` — Anthropic's fetch MCP; similar to WebFetch but runs as an MCP server
|
||||
- `firecrawl` — converts web pages to clean markdown; good for documentation sites
|
||||
- `markdownify` / `reader` — HTML-to-markdown conversion services
|
||||
- `jina-reader` — extracts main content from web pages as markdown
|
||||
- `browser-tools` — browser automation for pages that require JavaScript rendering
|
||||
|
||||
Check what MCP servers are available with `ToolSearch` before falling back to raw `WebFetch`. If a markdown-conversion MCP is available, prefer it — the output is cleaner and easier to scan.
|
||||
@@ -118,4 +115,3 @@ When you are about to do research — whether triggered by the user saying "rese
|
||||
- The internal structure of a research tree (phases, dependencies) — that's research-tree
|
||||
- Where files go — that's workpad
|
||||
- Whether to do research at all — that's your judgment as orchestrator
|
||||
- Which model to use — out of scope
|
||||
|
||||
@@ -67,11 +67,11 @@ Same model tiers as Igor (see `spire:igor` references/model-tiers.md). The diffe
|
||||
| Skill/agent authoring, template changes | Implementer (Sonnet or Opus depending on complexity) | project-pinned or `model: "sonnet"`/`"opus"` (needs write access) |
|
||||
| Investigating plugin behavior, format questions | `search` agent or adept | `subagent_type: "search"` (read-only) or `"adept"` |
|
||||
| Gitea issues | Route through `gitea:*` skills | — |
|
||||
| Multi-file refactors, cross-cutting changes | Athanor | `subagent_type: "athanor"` |
|
||||
| Building an attacked, reshaped plan; non-build multi-part jobs | Athanor | `subagent_type: "athanor"` |
|
||||
| Test runs, verification, mechanical sweeps | Haiku subagent | `model: "haiku"` (needs Bash access) |
|
||||
| Deep research (design decisions, prior art) | `researcher` agent | `subagent_type: "researcher"` (Opus, writes reports) |
|
||||
|
||||
**Model must be explicit.** Always pass `model` on `Agent` calls. Leaf tasks say "do this yourself; do not dispatch further agents."
|
||||
**Model rule.** Pinned agents: omit `model` (the alias overrides the pin). Unpinned agents: pass the alias. Leaf tasks say "do this yourself; do not dispatch further agents."
|
||||
|
||||
## Adepts
|
||||
|
||||
|
||||
Reference in New Issue
Block a user