Skip to content

core.md

Latest commit

 

History

History
223 lines (152 loc) · 11.4 KB

core.md

File metadata and controls

223 lines (152 loc) · 11.4 KB
Raw

NOTE: This is the canonical provider-independent contract. Both provider wrappers must load it in full.

Provider-neutral host abstractions

  • Resolve supporting assets and relative script paths against .claude/skills/user-brainstorm/; the canonical prose lives here while implementation assets remain with the compatibility launcher.
  • A named skill call means the host's skill-dispatch primitive. An Agent, Explore agent, workflow, or sub-agent means an isolated task/action invocation with fresh context and the requested capability tier. Provider wrappers map these roles to their native APIs.
  • Model tier names in inherited procedures describe capability roles. Resolve them through config/model-tier-map.json; an unavailable required capability returns required_tool_missing rather than weakening a gate.
  • Never expose hidden chain-of-thought. Preserve only decisions, evidence, commands, structured artifacts, and operator-facing rationale required by this contract.

user-brainstorm

Help the user explore and document an arbitrary topic — engineering pattern, architectural concern, product question, design space — by producing a tiered reference set.

The activity has two phases: interactive ideation (seed → gap-fill → tier, with the user in the loop) and parallel investigation (one background sub-agent per topic writes a templated reference file). The output is a self-contained, navigable doc set the user can grep later.

When to use

  • User wants to ideate comprehensively on a topic.
  • User asks "what are the considerations for X" or similar open-ended exploration.
  • User wants a reference doc set produced from a back-and-forth, not a one-shot answer.
  • After running, the user has a folder of cross-referenced investigations they can refer back to.

When NOT to use

  • Single specific question with a single specific answer — just answer it.
  • Topic is already covered by an existing doc set — point at that instead.
  • Topic is too narrow (one concern, not a space of concerns).

Steps

1. Get the topic

Required argument. If not provided, ask: "What topic do you want to brainstorm?" Derive a kebab-case slug from the topic. Confirm the output path with the user (default: docs/investigations/<slug>/ relative to CWD).

2. Seed 10 topics

Generate exactly 10 topics related to the subject. Each is a short noun phrase (3-8 words) describing a concern, pattern, failure mode, or design decision. Output as a numbered list. No commentary — let the user react.

3. Gap-fill loop

Ask the user: "Are there any topics not mentioned that are really important?" Take any user additions verbatim, then add 5-10 more topics that the user's additions imply or that round out coverage. Re-present the running list (or just the additions) and repeat the question.

Stop when:

  • User says no new topics surface, or
  • The next round produces only low-value / redundant additions.

Typical: 3-4 rounds total (1 seed + 2-3 gap-fills). Do not loop indefinitely. If after round 3 the user is still adding meaningful topics, the topic was probably wider than expected — say so and ask whether to keep going or split into sub-topics.

4. Aggregate + tier

Combine all surfaced topics into one list. De-duplicate. Then organize into four tiers:

  • Tier 1 — Load-bearing. Foundational; the system / approach breaks without these. Often includes a meta-principle that several other Tier 1 topics are special cases of.
  • Tier 2 — High-leverage. Shape outcomes significantly. Calibration, integration, scope decisions.
  • Tier 3 — Optimization. Matter at scale or in edge cases. Cost discipline, specialized lenses, performance refinements.
  • Tier 4 — Hygiene. Worth doing but rarely the bottleneck. Long-term system health, polish.

Present the tiered list to the user and ask: "Tiering look right? Any topics to move, merge, or cut?" Adjust based on response.

5. Confirm structure

Before writing anything, show the user:

  • The output path (e.g., docs/investigations/<slug>/).
  • The file structure that will be created (see "Output layout" below).
  • The total number of investigation files (one per surfaced topic).
  • Approximate per-file size (350-600 words).

Ask: "Proceed?" Wait for explicit confirmation before any file write.

6. Write meta files

Write two meta files into the output directory before dispatching agents:

  • topics.md — flat list of all topics, tier-organized, each line a markdown link to the eventual investigation file (NN-<slug>.md). Brief provenance note at top (how many rounds, how the set was assembled).
  • plan.md — investigation methodology. Goal, scope, common template (verbatim), execution model (sub-agent-per-file dispatch), output structure, done criteria.

7. Dispatch sub-agents

One background sub-agent per investigation file, each dispatched with explicit model: sonnet (authorship fan-out arms run Sonnet by default — tier policy, CLAUDE.md model paragraph). Each agent is briefed with:

  • File path to write (docs/investigations/<slug>/NN-<topic-slug>.md).
  • Topic title and tier.
  • Workspace context files to read for grounding (see "Per-agent grounding" below).
  • Topic-specific bullets (the angle, related workspace incidents, key references the agent should weave in — gathered during the ideation phase).
  • Likely cross-references (slugs of related sibling investigations).
  • The investigation file template (verbatim — see below).
  • Constraints (length, tone, no invented references).

Dispatch in waves of ~10-12 background agents per message. A single mega-message dispatching all agents has been observed to trigger 529 Overloaded cascades; waves keep concurrent load manageable. Use run_in_background: true so completions arrive as task-notifications.

If any agent fails (529, timeout, refusal), retry that single file in a fresh sub-agent dispatch.

8. Write README

After all agents have completed, glob the output directory to confirm every NN-<slug>.md exists. Then write README.md:

  • Intro paragraph stating the topic and scope.
  • Tier-organized list of links to each investigation file with a one-line hook per topic.
  • Provenance section (how many rounds, how many topics, dispatch pattern).
  • "See also" pointers to any workspace rules, memories, or skills the agents commonly referenced.

End the activity with a summary message to the user: total files written, location, any agents that needed retry, and what to do next (browse the README, grep for keywords).

Output layout

docs/investigations/<topic-slug>/
├── README.md           # tier-organized index, links to every file
├── topics.md           # flat list with tier headers
├── plan.md             # methodology that produced this set
└── NN-<slug>.md        # one per topic, numbered 01..NN

Investigation file template

Every investigation file uses this exact structure:

# <Topic Title>

**Tier:** <1 | 2 | 3 | 4>
**Status:** Investigated
**Related:** [[other-slug]], [[other-slug]]

## What it is
<1–2 paragraphs. State the concept directly.>

## Why it matters
<Failure modes. Workspace incidents if applicable. What goes wrong without this.>

## When to apply
<Trigger conditions — bullet list when natural.>

## How to apply
<Concrete patterns, decisions, snippets, checklists.>

## References
<Pointers to actual files in the workspace. Only cite ones the agent verified by reading. Common shapes:
- Rule: `<file>.md § <section>` (relative path)
- Memory: `<memory-file>.md`
- Skill: `<skill-name>`
- Incident: <project> <phase or step>>

## Open questions
<What's not settled. What to investigate further.>

Per-agent grounding

Each sub-agent's prompt instructs it to read (whatever exists in the workspace):

  • Project root CLAUDE.md if present.
  • Rule files under .claude/rules/*.md if the project has them.
  • Workspace memory index (typically at <workspace-memory>/MEMORY.md) and any feedback_*.md / project_*.md files it points to that look topic-relevant.
  • SKILL.md files under .claude/skills/<name>/ for skills clearly relevant to the topic.
  • The topics.md file in the output directory (for the canonical cross-reference slug list).

Agents must only cite files they actually verified by reading. Inventing references defeats the point.

Sub-agent prompt template

The orchestrator constructs each agent's prompt by filling this template:

Write ONE markdown file at <ABSOLUTE-PATH>/<NN>-<SLUG>.md.

Topic: "<TITLE>" (Tier <N>). One of <TOTAL> reference files about <SUBJECT>.

READ for grounding (don't invent references):
- <list of workspace files relevant to the topic, per "Per-agent grounding">

TOPIC CONTEXT (build on these — don't regurgitate):
- <3-5 bullets surfaced during the ideation phase: the angle, workspace incidents that anchor the topic, key memories/rules to weave in>

LIKELY CROSS-REFERENCES: [[other-slug]], [[other-slug]], ...

TEMPLATE (exact structure):
<verbatim template from above>

CONSTRAINTS:
- 350-600 words.
- No emojis.
- Reference tone — terse, factual.
- Markdown links use relative paths from the file's location.
- Cross-references via [[slug]].
- No padding. Honest-line is fine ("No prior incident in this workspace; pattern recommended on first-principles grounds").
- No invented references.

Write the file with the Write tool. Reply: "Wrote <NN>-<SLUG>.md" plus any notes.

Topic-specific bullets come from the ideation phase: as the user surfaces topics and reacts, note any workspace incidents, related rules, or angles they mention. These become the per-topic grounding for the relevant agent.

Constraints

  • 350-600 words per investigation. Concrete beats comprehensive.
  • No emojis.
  • Reference tone — terse, factual, written to be grepped later.
  • Cross-references via [[slug]] — slug = the file's <slug> part (without the NN- prefix or .md extension).
  • No padding. A section with nothing real says one honest line, not a paragraph of filler.
  • No invented references. Agents only cite files they verified by reading.
  • No naming specific other skills or projects unless the topic is explicitly about them. The skill itself is topic-agnostic; the investigation set produced should be.

Limitations

  • Dispatching all agents in one mega-message. Hit a 529 cascade once. Wave them in batches of ~10-12.
  • Skipping the tier confirmation. Tiering decisions shape the README's organization and the user's mental model. Always confirm before writing.
  • Letting gap-fill loop forever. Cap at 4 rounds. If the user keeps adding meaningful topics past that, the subject is too broad — surface this and ask to split.
  • Writing meta files before tier confirmation. Cheap to revise verbally, expensive to revise after files exist.
  • Producing generic content because the agents weren't grounded. Per-agent bullets and workspace context reads are what make the output useful. Skipping them produces hand-wavy reference docs that read like generic blog posts.

End-of-activity report

Final message to the user includes:

  • Output directory path.
  • File count produced (and any that needed retry).
  • Total topics by tier (e.g., "9 Tier 1, 12 Tier 2, 11 Tier 3, 3 Tier 4").
  • Any notes the agents flagged in their completion replies (e.g., "agent 14 noted an existing inconsistency in ; worth a follow-up").
  • One suggested next action — usually "browse the README" or "grep for ".

Keep it short. Two or three sentences plus the file count.