trellis-brainstorm
Skill0 starsChanged 5 months agoMITView on GitHub
Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, 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.
20 other projects use a version of this, 13 of them edited; 12 of 13 edited versions we compared changed its rules; 1 new project in the last 4 weeks, against 0 the 4 before.
How people change it
12 of 13 edited versions changed its rules, and some changes recur.
Of the 13 edited versions we compared: 1 is an older text, 12 made changes of their own.
Not in older versions
- Before final review or
task.py start, run the PRD convergence pass below.missing from 1 of 1 - When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to fundamental truths before reasoning upward.missing from 1 of 1
- What if we removed this? If nothing breaks, it's unnecessary.missing from 1 of 1
- Who benefits from this complexity? If "nobody", simplify.missing from 1 of 1
- Start with the minimum viable mechanism satisfying all truthsmissing from 1 of 1
- Add complexity only when a specific truth demands itmissing from 1 of 1
- Before declaring planning ready or running
task.py start, rewriteprd.mdonce against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.missing from 1 of 1 - Remove resolved open questions instead of leaving empty or already-answered sections.missing from 1 of 1
Rules people drop
- Ask the questions one at a time.dropped by 12 of 12
- Ask the single highest-value remaining question.dropped by 12 of 12
- After each user answer, update
prd.mdbefore continuing.dropped by 12 of 12 - Before final review or
task.py start, run the PRD convergence pass below.dropped by 12 of 12 - Keep only genuinely blocking open questions.dropped by 12 of 12
- Do not start implementation until the user approves or asks for implementation.dropped by 12 of 12
- Use a concise title from the user's request. Use a slug without a date prefix.
task.py createadds theMM-DD-directory prefix automatically.dropped by 4 of 12
Rules people add
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
- A rule we can't quote: its licence doesn't allow itadded by 12 of 12
We split this file and each edited version into the rules they give an agent and match them by wording. A version that adds no rule of its own and has not changed since this file last did reads as an older text, so what it lacks is not counted as dropped. We keep no past texts of a file, so that is inferred, and an edited version that started from an older text still counts its gaps as drops.
Adopted by
Surging: 1 new project took it in the last 4 weeks, none the 4 weeks before.thin data
Most recently taken up by
- vibex-ai/vibexedited, first seen Nov 12, 2026
- mipawn/cc-useedited, first seen Nov 1, 2026
- deequoique/stashseekedited, first seen Oct 20, 2026
- tmdy/CodeDeckedited, first seen Oct 18, 2026
- zhexin233-ui/easytoagentsedited, first seen Oct 11, 2026
- wuwei-crg/LXB-Frameworktheir own version, first seen Oct 8, 2026
Other versions20 projects use a version of this.
Word for word · 4
- EcoPasteHub/EcoPaste★ 7.5k100% same
- xhl592576605/agent-skills-mesh★ 8100% same
- lifan-builds/context-harness★ 1100% same
- fantasticjoe/biozy★ 0100% same
Edited · 13
- mindfold-ai/Trellis★ 15k62% same
- QiaoKes/fntv-electron★ 1.3k65% same
- mumu-0922/GankAIGC★ 39695% same
- CharTyr/STS2-Agent★ 36264% same
- hsingjui/ContextWeaver★ 29562% same
- vibex-ai/vibex★ 24565% same
- fy-agent/fyagent★ 21862% same
- deequoique/stashseek★ 5865% same
- mipawn/cc-use★ 962% same
- tmdy/CodeDeck★ 264% same
3 more not listed
Wrote their own version · 3
- wuwei-crg/LXB-Framework★ 301same name
- linyimin0812/folyn★ 41same name
- ofoxai/skills★ 2same name
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
- CLAUDE.mdCLAUDE.md
- trellis-before-devSkill
- trellis-break-loopSkill
- trellis-channelSkill
- trellis-checkSkill
- trellis-metaSkill
- trellis-session-insightSkill
- trellis-spec-bootstrapSkill
- trellis-update-specSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
25 rules. 15 are common, 4 are distinctive, and 6 are very specific to this project.
15
Common
Most of the 16 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Ask the questions one at a time.
- Common: line 16
If a question can be answered by exploring the codebase, explore the codebase instead.
- Common: line 20
Do not ask the user to confirm facts that the repository can answer.
- Common: line 24
Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
- Common: line 28
Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
- Common: line 30
If no task exists yet, create one:
- Very specific: line 36
Use a concise title from the user's request.
- Distinctive: line 52
Ask the single highest-value remaining question.
- Very specific: line 54
After each user answer, update prd.md before continuing.
- Very specific: line 56
Before final review or task.py start, run the PRD convergence pass below.
- Common: line 58
Do not invent a project-specific product/spec hierarchy.
- Common: line 62
Ask only one question per message.
- Common: line 71
Do not ask process questions such as whether to search, inspect files, or continue brainstorming.
- Common: line 75
When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to …
- Common: line 100
What if we removed this?: If nothing breaks, it's unnecessary.
- Common: line 102
Who benefits from this complexity?: If "nobody", simplify.
- Common: line 106
Start with the minimum viable mechanism satisfying all truths
- Common: line 107
Add complexity only when a specific truth demands it
- Very specific: line 140
follow-up checks before task.py start
- Very specific: line 148
Before declaring planning ready or running task.py start, rewrite prd.md once against the final structure described in the artifact rules …
- Common: line 154
Remove resolved open questions instead of leaving empty or already-answered sections.
- Distinctive: line 157
Keep only genuinely blocking open questions.
- Very specific: line 159
After the pass, read prd.md top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
- Common: line 163
Before declaring planning ready:
- Distinctive: line 173
Do not start implementation until the user approves or asks for implementation.
“Common” is measured: kept by at least 6 in 10 of the 16 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
Trellis Brainstorm
Non-Negotiable Interview Contract
Interview me relentlessly about every aspect of this 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.
Non-Negotiable Evidence Rule
If a question can be answered by exploring the codebase, explore the codebase instead.
This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
Preconditions
Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
If no task exists yet, create one:
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --slug <slug>)Use a concise title from the user's request. Use a slug without a date prefix. task.py create adds the MM-DD- directory prefix automatically.
task.py create creates the default prd.md. Update that file with the current understanding before asking follow-up questions.
Planning Flow
- Capture the user's request and initial known facts in
prd.md. - Inspect available evidence before asking questions:
- code, tests, fixtures, and configs
- README files, docs, existing specs, and domain notes
- related Trellis tasks, research files, and session history when present
- Separate what you found into:
- confirmed facts
- product intent still needed from the user
- scope or risk decisions still needed from the user
- likely out-of-scope items
- Ask the single highest-value remaining question.
- Include your recommended answer with the question.
- After each user answer, update
prd.mdbefore continuing. - For complex tasks, create or update
design.mdandimplement.mdbefore implementation starts. - Before final review or
task.py start, run the PRD convergence pass below.
Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
Question Rules
Ask only one question per message.
Each question must include:
- the decision needed
- why the answer matters
- your recommended answer
- the trade-off if the user chooses differently
Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
Thinking Framework: First Principles Analysis
When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to fundamental truths before reasoning upward.
Step 1: Restate the Problem
Strip away implementation details to one sentence.
Bad: "We need to add Redis caching to the user profile endpoint" Good: "User profile data takes too long to load"
Step 2: List Fundamental Truths
What is absolutely true (not opinion or convention)?
| Category | Examples |
| Physical constraints | Network latency ≥ 0, disk I/O has limits |
| Business rules | "Users must see their own data" |
| Technical invariants | "Data must be consistent" |
| User needs | "The user wants X within Y seconds" |
Step 3: Challenge Assumptions
For each component of the current plan:
- Fact or convention? "We always use REST" — why?
- What if we removed this? If nothing breaks, it's unnecessary.
- Solving the actual problem or a symptom? Trace the causal chain.
- Who benefits from this complexity? If "nobody", simplify.
Step 4: Build Up from Truths
- Start with the minimum viable mechanism satisfying all truths
- Add complexity only when a specific truth demands it
- Each addition must answer: "Which truth requires this?"
Step 5: Validate
- Does the solution solve the original problem?
- What assumptions need verification?
- What's the simplest experiment to test this?
Artifact Rules
prd.md records requirements and acceptance:
- goal and user value
- confirmed facts
- requirements
- acceptance criteria
- out of scope
- open questions that still block planning
design.md records technical design for complex tasks:
- architecture and boundaries
- data flow and contracts
- compatibility and migration notes
- important trade-offs
- operational or rollback considerations
implement.md records execution planning for complex tasks:
- ordered implementation checklist
- validation commands
- risky files or rollback points
- follow-up checks before
task.py start
Lightweight tasks may have only prd.md. Complex tasks must have prd.md, design.md, and implement.md before task.py start.
implement.md is not a replacement for implement.jsonl. On sub-agent-dispatch workflows, implement.jsonl and check.jsonl must each contain at least one real spec/research entry before task.py start; the seed _example row does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through trellis-before-dev.
PRD Convergence Pass
Before declaring planning ready or running task.py start, rewrite prd.md once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.
The pass must be lossless:
- Collapse repeated facts into one authoritative section.
- Fold temporary brainstorm sections such as
What I already know,Assumptions, and resolvedOpen Questionsinto Goal, Background, Requirements, Technical Notes, or Acceptance Criteria. - Remove resolved open questions instead of leaving empty or already-answered sections.
- Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement.
- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping.
- Keep only genuinely blocking open questions.
After the pass, read prd.md top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
Quality Bar
Before declaring planning ready:
prd.mdcontains testable acceptance criteria.prd.mdhas passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.- Repository-answerable questions have already been answered through inspection.
- Remaining open questions are genuinely about user intent or scope.
- Complex tasks have
design.mdandimplement.md. - Sub-agent-dispatch tasks have real curated entries in both
implement.jsonlandcheck.jsonl; seed-only manifests are not ready. - The user has reviewed the final planning artifacts or explicitly approved proceeding.
Do not start implementation until the user approves or asks for implementation.
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.

