trellis-brainstorm
Skill301 starsChanged 6 months agoMITView on GitHub
Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, uses grill-me style interviews in two generic tracks (backend behavior, then frontend/user-facing interface), records the PRD after every answer, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task.
21 other projects use a version of this, 3 of them edited.
Adopted by
Most recently taken up by
- vibex-ai/vibextheir own version, first seen Nov 12, 2026
- phoben/agent-skillstheir own version, first seen Nov 8, 2026
- mipawn/cc-usetheir own version, first seen Nov 1, 2026
- deequoique/stashseektheir own version, first seen Oct 20, 2026
- tmdy/CodeDecktheir own version, first seen Oct 18, 2026
- zhexin233-ui/easytoagentstheir own version, first seen Oct 11, 2026
Used with
Projects with it also use trellis-channel, trellis-session-insight and 1 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
wayfarer35Skilltrellis-channel
Use Trellis channel for live multi-agent collaboration, spawned workers, cross-agent review, progress inspection, forum channels, and channel log debugging.
Also in 18 projects that use this
wayfarer35Skilltrellis-session-insight
Reach into past AI conversation history through the `trellis mem` CLI. Use whenever the user asks 'how did we solve X last time', 'have we discussed this before', 'what was the decision on X', 'remind me what we did in this task', '上次怎么解的', '之前讨论过吗', '想起一段对话', or when starting a brainstorm that overlaps prior work, debugging a familiar bug, continuing a task across sessions, or doing a finish-work review. Returns raw past dialogue; decide for the moment whether to update spec, append to task notes, quote inline in the answer, or just internalize.
Also in 18 projects that use this
- +1 more from wayfarer35
Other versions21 projects use a version of this.
Word for word · 0
None found.
Edited · 3
- mumu-0922/GankAIGC★ 39614% same
- linyimin0812/folyn★ 4194% same
- ofoxai/skills★ 294% same
Wrote their own version · 18
- mindfold-ai/Trellis★ 15ksame name
- EcoPasteHub/EcoPaste★ 7.5ksame name
- QiaoKes/fntv-electron★ 1.3ksame name
- CharTyr/STS2-Agent★ 357same name
- hsingjui/ContextWeaver★ 295same name
- vibex-ai/vibex★ 245same name
- fy-agent/fyagent★ 218same name
- deequoique/stashseek★ 58same name
- mipawn/cc-use★ 9same name
- xhl592576605/agent-skills-mesh★ 8same name
8 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- trellis-before-devSkill
- trellis-break-loopSkill
- trellis-checkSkill
- trellis-continueSkill
- trellis-finish-workSkill
- trellis-metaSkill
- trellis-spec-bootstarpSkill
- trellis-startSkill
- trellis-update-specSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
42 rules. 1 is common, 29 are distinctive, and 12 are very specific to this project.
1
Common
Most of the 21 edited versions we read keep these.
29
Distinctive
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
CoreRule: Use the grill-me interview style during brainstorm.
- Distinctive: line 10
Ask the questions one at a time.
- Common: line 12
If a question can be answered by exploring the codebase, explore the codebase instead.
- Very specific: line 14
PRD Recording Rule: Update prd.md after every user answer.
- Distinctive: line 41
Always ensure a task exists at the start so the user's ideas are recorded immediately.
- Distinctive: line 44
If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
- Distinctive: line 47
Never overwhelm the user with a list of questions.
- Distinctive: line 53
If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
- Distinctive: line 56
After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP …
- Distinctive: line 59
Do not ask "should I search?" or "can you paste the code so I can continue?" If you need information: search/inspect.
- Distinctive: line 60
If you need information: search/inspect.
- Distinctive: line 63
Run requirement discovery in two independent tracks, in this order:
- Very specific: line 68
Keep one prd.md for the task.
- Distinctive: line 74
Before any Q&A, ensure a task exists.
- Distinctive: line 76
Use a temporary working title derived from the user's message.
- Very specific: line 83
Use a slug without a date prefix.
- Very specific: line 86
Create/seed prd.md immediately with what you know:
- Distinctive: line 149
Before asking questions like "what does the code look like?", gather context yourself:
- Distinctive: line 155
Check configs, scripts, existing command definitions
- Very specific: line 160
Look for existing PRDs/specs/templates
- Distinctive: line 161
Look for command usage examples, README, ADRs if any
- Distinctive: line 163
Write findings into PRD:
- Very specific: line 166
Add constraints/links to Technical Notes
- Distinctive: line 185
Before asking ANY question, run the following gate:
- Distinctive: line 189
If answer is available via:
- Distinctive: line 211
Derivable: should be answered by inspection/research
- Distinctive: line 219
Run brainstorm as two separate interview tracks.
- Distinctive: line 232
Ask one backend question at a time.
- Very specific: line 236
After the user answers, update prd.md immediately.
- Distinctive: line 239
Do not move to the frontend/user-facing track until backend behavior is coherent enough to summarize.
- Distinctive: line 243
After backend behavior is summarized, run a separate frontend/user-facing grill-me pass.
- Distinctive: line 253
Ask one frontend/user-facing question at a time.
- Very specific: line 313
Write findings to {TASK_DIR}/research/<topic>.md
- Distinctive: line 367
After you can summarize the goal, proactively broaden thinking before converging.
- Distinctive: line 417
Prefer multiple-choice when possible
- Distinctive: line 418
After each user answer:
- Very specific: line 421
Add or update one ## Decision Log entry
- Very specific: line 423
Update Backend Behavior (evolving) or Frontend/User-Facing Interface (evolving) depending on the active track
- Very specific: line 424
Update Acceptance Criteria with testable checkboxes
- Distinctive: line 449
After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
- Distinctive: line 483
When open questions are resolved, confirm complete requirements with a structured summary:
- Distinctive: line 603
After brainstorm completes (Step 9 confirmation approved), the flow continues to the Task Workflow's Phase 2: Prepare for Implementation:
“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Brainstorm - Requirements Discovery (AI Coding Enhanced)
CoreRule: Use the grill-me interview style during brainstorm. Interview the user relentlessly about every aspect of the plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
Ask the questions one at a time.
If a question can be answered by exploring the codebase, explore the codebase instead.
PRD Recording Rule: Update prd.md after every user answer. Do not wait until the interview ends. Each answered question must leave a durable record in the PRD by updating requirements, assumptions, open questions, acceptance criteria, technical notes, or the decision log.
Guide AI through collaborative requirements discovery before implementation, optimized for AI coding workflows:
- Task-first (capture ideas immediately)
- Action-before-asking (reduce low-value questions)
- Research-first for technical choices (avoid asking users to invent options)
- Diverge → Converge (expand thinking, then lock MVP)
When to Use
Triggered from start (Trellis command) when the user describes a development task, especially when:
- requirements are unclear or evolving
- there are multiple valid implementation paths
- trade-offs matter (UX, reliability, maintainability, cost, performance)
- the user might not know the best options up front
Core Principles (Non-negotiable)
- Task-first (capture early) Always ensure a task exists at the start so the user's ideas are recorded immediately.
- Action before asking If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
- One question per message Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
- Prefer concrete options For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
- Research-first for technical choices If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
- Diverge → Converge After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
- No meta questions Do not ask "should I search?" or "can you paste the code so I can continue?" If you need information: search/inspect. If blocked: ask the minimal blocking question.
- Two-track grill-me
Run requirement discovery in two independent tracks, in this order:
- Backend behavior: domain rules, state changes, commands/APIs/events, persistence, migration, execution flow, validation, errors, compatibility, tests.
- Frontend/user-facing interface: where users encounter the feature, what they see, what they can do, which fields are exposed, wording/i18n, controls, feedback states, and layout ergonomics.
- One PRD, one record per answer
Keep one
prd.mdfor the task. After each answer, append or update a concrete record so the next turn can resume from the file, not from chat memory.
Step 0: Ensure Task Exists (ALWAYS)
Before any Q&A, ensure a task exists. If none exists, create one immediately.
- Use a temporary working title derived from the user's message.
- It's OK if the title is imperfect — refine later in PRD.
TASK_DIR=$(python ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)Use a slug without a date prefix. task.py create adds the MM-DD-
directory prefix automatically.
Create/seed prd.md immediately with what you know:
# brainstorm: <short goal>
## Goal
<one paragraph: what + why>
## What I already know
* <facts from user message>
* <facts discovered from repo/docs>
## Assumptions (temporary)
* <assumptions to validate>
## Open Questions
* <ONLY Blocking / Preference questions; keep list short>
## Backend Behavior (evolving)
* <backend behavior, constraints, decisions, and acceptance criteria>
## Frontend/User-Facing Interface (evolving)
* <user-facing requirements, exposed information, interaction flows, i18n, states, and acceptance criteria>
## Decision Log
* <question> → <answer / decision> → <PRD impact>
## Requirements (evolving)
* <start with what is known>
## Acceptance Criteria (evolving)
* [ ] <testable criterion>
## Definition of Done (team quality bar)
* Tests added/updated (unit/integration where appropriate)
* Lint / typecheck / CI green
* Docs/notes updated if behavior changes
* Rollout/rollback considered if risky
## Out of Scope (explicit)
* <what we will not do in this task>
## Technical Notes
* <files inspected, constraints, links, references>
* <research notes summary if applicable>Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)
Before asking questions like "what does the code look like?", gather context yourself:
Repo inspection checklist
- Identify likely modules/files impacted
- Locate existing patterns (similar features, conventions, error handling style)
- Check configs, scripts, existing command definitions
- Note any constraints (runtime, dependency policy, build tooling)
Documentation checklist
- Look for existing PRDs/specs/templates
- Look for command usage examples, README, ADRs if any
Write findings into PRD:
- Add to
What I already know - Add constraints/links to
Technical Notes
Step 2: Classify Complexity (still useful, not gating task creation)
| Complexity | Criteria | Action |
| Trivial | Single-line fix, typo, obvious change | Skip brainstorm, implement directly |
| Simple | Clear goal, 1–2 files, scope well-defined | Ask 1 confirm question, then implement |
| Moderate | Multiple files, some ambiguity | Light brainstorm (2–3 high-value questions) |
| Complex | Vague goal, architectural choices, multiple approaches | Full brainstorm |
Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
Step 3: Question Gate (Ask ONLY high-value questions)
Before asking ANY question, run the following gate:
Gate A — Can I derive this without the user?
If answer is available via:
- repo inspection (code/config)
- docs/specs/conventions
- quick market/OSS research
→ Do not ask. Fetch it, summarize, update PRD.
Gate B — Is this a meta/lazy question?
Examples:
- "Should I search?"
- "Can you paste the code so I can proceed?"
- "What does the code look like?" (when repo is available)
→ Do not ask. Take action.
Gate C — What type of question is it?
- Blocking: cannot proceed without user input
- Preference: multiple valid choices, depends on product/UX/risk preference
- Derivable: should be answered by inspection/research
→ Only ask Blocking or Preference.
Step 4: Two-Track Grill-Me Interview (MANDATORY)
Run brainstorm as two separate interview tracks. Do not blend backend and frontend decisions into one vague discussion.
Track 1: Backend Behavior
Finish backend behavior first. Cover only the behavior and system contract:
- domain concepts and ownership boundaries
- commands, APIs, events, or protocol shape
- persistence, migration, compatibility, and rollback
- execution flow, lifecycle, cancellation, retry, and error handling
- validation rules and default behavior
- tests and traceability
Ask one backend question at a time. For each question:
- Inspect code/specs first when possible.
- Present 2–3 concrete options with a recommended answer.
- After the user answers, update
prd.mdimmediately. - Record the answer in
## Decision Logand update## Backend Behavior (evolving).
Do not move to the frontend/user-facing track until backend behavior is coherent enough to summarize.
Track 2: Frontend/User-Facing Interface
After backend behavior is summarized, run a separate frontend/user-facing grill-me pass. Cover only the surface users interact with:
- where the feature appears in the product and how users enter/leave it
- primary user journeys and secondary actions, such as create/edit/delete/toggle/run when applicable
- what information users should see versus what remains internal
- which control type fits each user-editable value, such as text input, picker, switch, calendar/time selector, or modal/full-screen selector
- Chinese-first copy, i18n keys, validation text, and user-facing terminology
- empty states, loading states, errors, success feedback, save/cancel behavior, and dirty-state handling
- information density, navigation, mobile/desktop layout, and accessibility constraints
Ask one frontend/user-facing question at a time. For each question:
- Inspect the old/current user-facing implementation first when possible.
- Present 2–3 concrete UX options with a recommended answer.
- After the user answers, update
prd.mdimmediately. - Record the answer in
## Decision Logand update## Frontend/User-Facing Interface (evolving).
The frontend/user-facing track is required for any user-visible change. If the task is truly backend-only, still record that conclusion in prd.md with the reason and the checked surfaces before skipping detailed UI questions.
Step 5: Research-first Mode (Mandatory for technical choices)
Trigger conditions (any → research-first)
- The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
- The user asks for "best practice", "how others do it", "recommendation"
- The user can't reasonably enumerate options
Delegate to trellis-research sub-agent (don't research inline)
For each research topic, spawn a trellis-research sub-agent via the Task tool — don't do WebFetch / WebSearch / gh api inline in the main conversation.
Why:
- The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
- It persists findings to
{TASK_DIR}/research/<topic>.md(the contract — seeworkflow.mdPhase 1.2) - It returns only
{file path, one-line summary}to the main agent - Independent topics can be parallelized — spawn multiple sub-agents in one tool call
Codex exception: on Codex CLI, do NOT dispatch
trellis-researchfor research-first mode — do the research inline (WebFetch / WebSearch in the main session) and write findings to{TASK_DIR}/research/<topic>.mdyourself. Reason: Codexspawn_agentruns sub-agents withfork_turns="none"(isolated context, no parent session inheritance), so the research sub-agent cannot resolve the active task path viatask.py currentand silently aborts without producing files. Inline research on Codex avoids this failure mode. The 3+ inline research calls limit (B rule inworkflow.md) is relaxed for Codex specifically.
Agent type: trellis-research
Task description template: "Research <specific question>; persist findings to {TASK_DIR}/research/<topic-slug>.md."
❌ Bad (what you must NOT do):
Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
→ WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
→ Write(research/topic.md)→ Pollutes main context with raw HTML/JSON, burns tokens.
✅ Good:
Main agent: Task(subagent_type="trellis-research",
prompt="Research topic A; persist to research/topic-a.md")
+ Task(subagent_type="trellis-research",
prompt="Research topic B; persist to research/topic-b.md")
+ Task(subagent_type="trellis-research",
prompt="Research topic C; persist to research/topic-c.md")
→ Reads research/topic-{a,b,c}.md after they finish.Research steps (to pass into each sub-agent prompt)
Each trellis-research sub-agent should:
- Identify 2–4 comparable tools/patterns for its topic
- Summarize common conventions and why they exist
- Map conventions onto our repo constraints
- Write findings to
{TASK_DIR}/research/<topic>.md
Main agent then reads the persisted files and produces 2–3 feasible approaches in PRD.
Research output format (PRD)
The PRD itself should only reference the persisted research files, not duplicate their content. Add a ## Research References section pointing at research/*.md.
Optionally, add a convergence section with feasible approaches derived from the research:
## Research References
* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
## Research Notes
### What similar tools do
* ...
* ...
### Constraints from our repo/project
* ...
### Feasible approaches here
**Approach A: <name>** (Recommended)
* How it works:
* Pros:
* Cons:
**Approach B: <name>**
* How it works:
* Pros:
* Cons:
**Approach C: <name>** (optional)
* ...Then ask one preference question:
- "Which approach do you prefer: A / B / C (or other)?"
Step 6: Expansion Sweep (DIVERGE) — Required after initial understanding
After you can summarize the goal, proactively broaden thinking before converging.
Expansion categories (keep to 1–2 bullets each)
Future evolution
- What might this feature become in 1–3 months?
- What extension points are worth preserving now?
Related scenarios
- What adjacent commands/flows should remain consistent with this?
- Are there parity expectations (create vs update, import vs export, etc.)?
Failure & edge cases
- Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
- Input validation, security boundaries, permission checks
Expansion message template (to user)
I understand you want to implement: <current goal>.
Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
1. Future evolution: <1–2 bullets>
2. Related scenarios: <1–2 bullets>
3. Failure/edge cases: <1–2 bullets>
For this MVP, which would you like to include (or none)?
1. Current requirement only (minimal viable)
2. Add <X> (reserve for future extension)
3. Add <Y> (improve robustness/consistency)
4. Other: describe your preferenceThen update PRD:
- What's in MVP →
Requirements - What's excluded →
Out of Scope
Step 7: Q&A Loop (CONVERGE)
Rules
- One question per message
- Prefer multiple-choice when possible
After each user answer:
- Update PRD immediately
- Add or update one
## Decision Logentry - Move answered items from
Open Questions→Requirements - Update
Backend Behavior (evolving)orFrontend/User-Facing Interface (evolving)depending on the active track - Update
Acceptance Criteriawith testable checkboxes - Clarify
Out of Scope
Question priority (recommended)
- MVP scope boundary (what is included/excluded)
- Preference decisions (after presenting concrete options)
- Failure/edge behavior (only for MVP-critical paths)
- Success metrics & Acceptance Criteria (what proves it works)
Preferred question format (multiple choice)
For <topic>, which approach do you prefer?
1. **Option A** — <what it means + trade-off>
2. **Option B** — <what it means + trade-off>
3. **Option C** — <what it means + trade-off>
4. **Other** — describe your preferenceStep 8: Propose Approaches + Record Decisions (Complex tasks)
After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
Based on current information, here are 2–3 feasible approaches:
**Approach A: <name>** (Recommended)
* How:
* Pros:
* Cons:
**Approach B: <name>**
* How:
* Pros:
* Cons:
Which direction do you prefer?Record the outcome in PRD as an ADR-lite section:
## Decision (ADR-lite)
**Context**: Why this decision was needed
**Decision**: Which approach was chosen
**Consequences**: Trade-offs, risks, potential future improvementsStep 9: Final Confirmation + Implementation Plan
When open questions are resolved, confirm complete requirements with a structured summary:
Final confirmation format
Here's my understanding of the complete requirements:
**Goal**: <one sentence>
**Requirements**:
* ...
* ...
**Acceptance Criteria**:
* [ ] ...
* [ ] ...
**Definition of Done**:
* ...
**Out of Scope**:
* ...
**Technical Approach**:
<brief summary + key decisions>
**Implementation Plan (small PRs)**:
* PR1: <scaffolding + tests + minimal plumbing>
* PR2: <core behavior>
* PR3: <edge cases + docs + cleanup>
Does this look correct? If yes, I'll proceed with implementation.Subtask Decomposition (Complex Tasks)
For complex tasks with multiple independent work items, create subtasks:
# Create child tasks
CHILD1=$(python ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
CHILD2=$(python ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
# Or link existing tasks
python ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"PRD Target Structure (final)
prd.md should converge to:
# <Task Title>
## Goal
<why + what>
## Requirements
* ...
## Backend Behavior
* ...
## Frontend/User-Facing Interface
* ...
## Acceptance Criteria
* [ ] ...
## Definition of Done
* ...
## Technical Approach
<key design + decisions>
## Decision (ADR-lite)
Context / Decision / Consequences
## Decision Log
* <question> → <answer / decision> → <PRD impact>
## Out of Scope
* ...
## Technical Notes
<constraints, references, files, research notes>Anti-Patterns (Hard Avoid)
- Asking user for code/context that can be derived from repo
- Asking user to choose an approach before presenting concrete options
- Meta questions about whether to research
- Staying narrowly on the initial request without considering evolution/edges
- Letting brainstorming drift without updating PRD
Integration with Start Workflow
After brainstorm completes (Step 9 confirmation approved), the flow continues to the Task Workflow's Phase 2: Prepare for Implementation:
Brainstorm
Step 0: Create task directory + seed PRD
Step 1-8: Discover requirements, grill-me backend behavior, grill-me frontend/user-facing interface, research, converge
Step 9: Final confirmation → user approves
↓
Task Workflow Phase 2 (Prepare for Implementation)
Code-Spec Depth Check (if applicable)
→ Research codebase (based on confirmed PRD)
→ Configure code-spec context (jsonl files)
→ Activate task
↓
Task Workflow Phase 3 (Execute)
Implement → Check → CompleteThe task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
Related Commands
| Command | When to Use |
``start (Trellis command) | Entry point that triggers brainstorm |
``finish-work (Trellis command) | After implementation is complete |
``update-spec (Trellis command) | If new patterns emerge during work |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

