Mycelium
Four questions before the first source file, so you and your coding agent don't spend the weekend building the wrong thing.
- Source repo
- haabe/mycelium
- Stars
- ★ 47
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 61/100 · Some gaps
At a glance
- Works with
- Portable with changesClaude CodeChatGPT · Codex (Partial support)
- You'll need
- Typical use
- An individual developer with a Thursday idea who wants ten minutes of written assumptions in the repo before letting the agent start.
- Main limitation
- The four questions are asked once per repo and never again — by the author's own admission nothing brings you back in November to check August's assumption.
- Source review
- 61/100 · Some gaps
What does this agent do, and when should you use it?
Mycelium is a Claude Code plugin that forces product discovery to happen before code exists, by gating the agent on written reasons. Setup runs through /mycelium:start, which asks four questions — what the problem is, who has it, what you are assuming, and what would show you wrong — and writes the answers into the repo as plain YAML canvas files that travel with the code in git. A six-layer structure (L0 Purpose through L5 Market) means each layer has to be opened with a stated reason before the layer below can be built. From then on, hooks hold work back: the agent cannot create a brand-new source file before anything is recorded, and once you have started, product work waits on a delivery diamond with its reasons written above it. The author measures roughly six thousand tokens always-on per session; everything else loads on use. It is pre-1.0, with schema and skill names moving between minor versions.
/mycelium:start sets up the repo and asks four questions whose answers become the spec. After that a first-source-file stop fires whenever the agent reaches for a new source file and none of the discovery record exists; editing existing code never meets it, and in repos with a dozen or more source files you are asked once, ever. Once work has started, building the product waits until a delivery diamond is open with its reasons above it, for new files and edits alike. Putting anything in front of real people waits for a record of who it reaches; a new diamond waits for the one above it to say what it builds on; and when your corrections file changes under the agent, it re-reads it before continuing. The agent cannot write the files that switch a stop off without asking you, a key the agent wrote into a file cannot be committed or pushed, and code you declare a prototype is free. Market feedback is drawn as a dotted line from L5 back to L2 Opportunity rather than to the top, on the reasoning that what the market says usually changes which problem is worth solving next.
- An individual developer with a Thursday idea who wants ten minutes of written assumptions in the repo before letting the agent start.
- A weekend vibe-coder who wants to avoid discovering in December what was obvious in August.
- A PM or product owner who wants JTBD, opportunity solution trees and Wardley mapping wired into something executable rather than left as a bookshelf of theory.
- A team that wants its coding agent to hold a written reason before building, and to leave a decision log with evidence strength marked (for example
speculation). - A developer already on opencode, Codex or Cursor who wants to port the files and skills into their own agent setup.
- Someone evaluating the 'AI built it and nobody came' risk who wants to read the author's read of 46 shipped-and-ignored posts and the case docs.
How do you install or deploy this agent?
In Claude Code, signed in:
/plugin marketplace add haabe/mycelium
/plugin install mycelium@haabe-mycelium # the marketplace id is haabe-mycelium
/mycelium:startInstall paths for other agents (opencode, Codex, Cursor) are in docs/install-paths.md; the README does not spell those commands out here. To leave:
/plugin uninstallHow do you use this agent?
Run /mycelium:start once in a repo to set it up, then pick how deep you want to go and answer the four questions; the answers are written as YAML in the canvas. Example of the shape it produces:
why: >-
So that a vibe-coding project crashing hard stops being a private, quiet defeat
and becomes something a person takes to peers.
who:
today: >-
Unknown — not yet observed. Founder has seen rants online but has not spoken to
anyone. Founder's own behaviour (in-cohort): fixes silently, tells no one.
evidence:
validated: false
strength: speculationIf you would rather not answer, write the date and your own words into the skip files:
.claude/state/discovery-skip-ack
.claude/state/delivery-skip-ackThe agent can write either one only if you agree.
What are this agent's strengths and limitations?
- The gates are structural rather than advisory: they fire on the agent's own write actions, covering new source files, delivery work, and putting things in front of real people.
- Reasoning lives in git beside the code as plain YAML, so you can later tell whether you had a reason in August or only wanted one — and it reads fine after uninstall.
- Thirty-odd theories (JTBD, opportunity solution trees, Wardley mapping, DORA metrics) are wired into one plugin instead of sitting as unread books.
- The author states a falsifiable test: run it on at least three real projects, and if the brief never once changed what you built, uninstall it.
- The four questions are asked once per repo and never again — by the author's own admission nothing brings you back in November to check August's assumption.
- Pre-1.0: schema and skill names move between minor versions and migrations accompany them, which is early for teams needing a stable interface.
- Documented escape hatches: a command the agent runs that writes files (a scaffolder or a clone) still gets through, and what you commit yourself is not checked unless you let setup add the check to git.
- Thin validation: three of the author's own projects, three people through a May test cohort, and one stranger since.
- Always-on cost: the author measures about six thousand tokens per session, with the rest loading on use.
How does this agent compare with similar options?
The README names alternatives for cases where Mycelium is the wrong fit: Paddo's boring agents when the decision is already made and you need throughput, Addy Osmani's agent-skills when scope is settled and you want it built faster, and Spotify's shunt (in spotify/portal-ai-plugins, plugins/shunt) when the work is decided and you want a smaller token bill via model routing. The author also says this will feel like bureaucracy if what you are making carries no risk of being the wrong thing, and that several people editing one canvas at once is not built.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mycelium This agent | 61 · Some gaps | — | ★ 47 | today | Python | Claude Code |
| Postiz Agent CLI | 54 · Major gaps | CLIFreemium | ★ 523 | 4d ago | TypeScript | Claude Code |
| SandBase Skills Library | 50 · Major gaps | Agent plugin / skillFree + model costs | ★ 202 | 23d ago | Python | Codex · Claude Code |
| YouTube Fetcher to Markdown | 83 · Good | Agent plugin / skillFree | ★ 494 | 12d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The README enumerates each hook's blocking scope, the skip files (discovery-skip-ack, delivery-skip-ack), the rule that the agent cannot disable a stop without asking, and that an agent-written key cannot be committed; SECURITY.md states there are no servers, accounts, or data collection. Permission boundaries and user confirmation are documented, so least_privilege/user_confirmation/data_flow_transparency/rollback score 2. However, sensitive-data handling is only a principle with no implementation evidence; dependency security rests on SHA-pinned actions and a signed-commit claim with no dependency manifest or scanning; external effects (hooks writing to the user's repo, git operations) are described but not sandboxed; source attribution is only README/CONTRIBUTORS with no verified publisher, so those score 1.
auto-release.yml and release-audit.yml give a detailed, self-consistent account of release-gap detection, Latest mis-tagging, and fail-loud behavior, and _assert.sh defends against false-green, SIGPIPE, and crashed test bodies, so failure_messages scores 3. Dependency availability shows only SHA-pinned actions with no runtime dependency declaration or version constraints; self-consistency is good between README and workflows but lacks checkable runtime behavior evidence, so 2 and 1.
The README states Claude Code support with ports to opencode/Codex/Cursor, links install-path docs, names when not to use it (decisions settled, throughput needed), and describes triggers (new source file, delivery diamond, public exposure) concretely, so audience_and_scenarios/capability_boundaries/trigger_precision/environment_fit score 2. The deduction: cross-agent ports are asserted via doc links with no adapter code or tests shown.
LICENSE is full MIT and the known_limitations section candidly lists the four-questions-once weakness, scoring 3; information architecture, install notes, examples (vibe-rant transcript, minilisp case), and versioning/changelog are present, scoring 2. But the README admits pre-1.0 status with schema and skill names moving between minor versions, so naming_stability drops to 1; maintenance responsibility is described as a solo maintainer in SECURITY.md but the publisher is unverified, so 2.
Output is readable YAML canvas and decision logs that survive uninstall, so output_usability scores 2; marginal_value is supported by real cases (the macOS file viewer killed, vibe-rant confidence 0.15), scoring 2; cost is roughly six thousand tokens per session and the author admits no business case found, so cost_benefit scores 2. Deduction: effectiveness evidence is mostly author self-report with few cases and no independent reproduction.
The README gives an explicit counting rule for the 46 posts (floor, not a rate) and links the full record, so claim_traceability scores 2; fact_inference_separation is decent, marking the vibe-rant brief as speculation with confidence 0.15, scoring 2. But cross_source_corroboration relies on the author's own repos and a single stranger's case with no third-party verification, dropping to 1.
- Publisher identity is unverified; verify provenance and signed commits before installing.
- The README states pre-1.0 status with schema and skill names moving between minor versions; pin a version for team use.
- Sensitive-data handling, dependency security, and external effects are principle-level claims without checkable implementation or scanning evidence.
- Effectiveness evidence is mostly author self-report with few cases; validate on at least three real projects as the author suggests.
- The four questions are asked once per repo with no revisit, so long-term assumptions need manual re-checking.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.328.0 v0.328.0 - A project's scope is asked before the brief
Release notes excerpt
2026-10-18. The brief flow asked its four questions and then offered a test, a prototype or "Go deeper". Whether the project is a solo hobby, a solo product or a team product was asked only inside Go deeper, so a builder who picked the test or a prototype was never asked. project_type stayed empty and every confidence bar ran at the base meant for a team shipping to strangers. On the maintainer's own hobby project (plugin 0.317.5, 2026-10-09 to 10-18) the first L0 gate noted "project_type unset, so no adaptation" and held it to …View on GitHub ↗ -
v0.327.1 v0.327.1 - The lesson-triggers fire log names the lessons
Release notes excerpt
2026-10-16. The fire log 0.327.0 wrote held a time and the hook's name. That says a lesson was shown, not which one, so the real-use test the hook ships for could not tell whether the lesson behind a later repeat had been put in front of the agent. The maintainer's threat model for the hook listed this as the one thing to fix before it is switched on. What changed - Each row of .claude/state/lesson-triggers-fires.jsonl now carries a detail: the tool, and the ids of the lessons refused and shown, for example tool=Bash refused=a shown=b,c. Only the ids the agent was …View on GitHub ↗ -
v0.327.0 v0.327.0 - A lesson on record can be shown at the call it is about
Release notes excerpt
2026-10-16. On the dogfood project, 86 of 96 corrections over a month repeated a lesson already written down, and the corrections file was opened in 12 of 71 sessions. Four builders outside the project describe the same thing in their own posts. A replay of the 86 repeats, against rules frozen before it read them, found that showing the matching lesson at the moment of the call reached the most of them: 31, against 14 for the checks that already existed. This release ships that, off by default, so the maintainer can test it in his own sessions first. What changed …View on GitHub ↗
FAQ
Will it stop my agent from creating files at all and block the workflow?
What if I don't want to answer the questions?
.claude/state/discovery-skip-ack and the first-file stop goes quiet in that repo for good. Build work you don't want tracked has its own file, .claude/state/delivery-skip-ack, which says what it covers and when it runs out. The agent can write either one only if you agree, and where there is nobody to ask it is refused.Which agent does it run on, and can I move it?
docs/install-paths.md — the README says one stranger ran it through one of those.How much does it cost in tokens?
What happens to my data if I uninstall?
/plugin uninstall. Your canvas stays behind as plain YAML and reads fine without any of the plugin.