Mycelium

Your AI agent's product thinking partner. v0.11.0

Mycelium ensures you build the right thing — not just build the thing right. It guides AI agents through structured discovery, strategy, and delivery using 42+ established product frameworks, 12 theory gates, and 38 skills. Drop it into any Claude Code project and run /interview.

npx degit haabe/mycelium my-project && cd my-project
# Start Claude Code, then:
/interview

Works for software, online courses, AI tools, and services. One command to start. The agent handles the rest.

What It Catches

In its first dogfood session, Mycelium forced a strategic pivot before any code was written — the founder's original positioning was invalidated by evidence the framework required them to gather. Without it, that mistake would have shipped.

Why It Exists

AI coding agents are powerful but unguided. They'll jump from an idea to code without discovery, skip security, ignore accessibility, repeat past mistakes, and inflate their own confidence. Spec-driven tools (Kiro, Spec Kit) help structure the coding — but they start at "what to build," never "should you build it." Mycelium starts earlier and stays longer.

Quick Start

New Project

Click "Use this template" on GitHub, or:

npx degit haabe/mycelium my-project
cd my-project

Then start Claude Code and run /interview. The agent guides you through purpose, vision, users, strategy, and classifies your project to determine what matters.

Existing Project

npx degit haabe/mycelium/CLAUDE.md ./CLAUDE.md
npx degit haabe/mycelium/.claude ./.claude

Then start Claude Code and run /interview.

Upgrading

Mycelium is not a software library -- it's a set of instructions that reshape agent behavior on every session start. Upgrading replaces framework files (skills, engine rules, hooks) while preserving your project state (canvas data, diamond state, decisions, memory).

Automated upgrade (recommended):

bash scripts/upgrade.sh          # upgrade to latest
bash scripts/upgrade.sh v0.12.0  # upgrade to specific version

The script reads .claude/manifest.yml to distinguish framework files from project state. It will never overwrite your populated canvas files, diamond state, decision log, or memory. It requires a clean git state (commit first) so you can revert if anything goes wrong.

After upgrading: Run /diamond-assess to see your diamonds through the new version's lens. Gates may have become stricter or new fields may be expected -- this is intentional, and /diamond-assess will tell you what needs attention.

Manual upgrade: See the upgrade checklist in .claude/manifest.yml for which files to replace vs preserve.

How It Works

Fractal Diamonds

Mycelium guides development through fractal diamonds -- recursive Discover/Define/Develop/Deliver cycles (based on the Double Diamond by the Design Council) that operate at every scale:

L0: Purpose     "Why do we exist?"           (Sinek, Christensen)
L1: Strategy    "Where do we play?"          (Wardley, North Star, Skelton)
L2: Opportunity "What problem to solve?"     (Torres, Allen, Cynefin)
L3: Solution    "How to solve it?"           (Gilad, Cagan, Downe)
L4: Delivery    "Build and ship"             (Forsgren, OWASP, SOLID)
L5: Market      "Reach users"               (Lauchengco, Shotton)

Each diamond has four phases: Discover (diverge) -> Define (converge) -> Develop (diverge) -> Deliver (converge).

Diamonds spawn child diamonds when complexity requires it. Parent diamonds continue while children execute. If delivery reveals a bad assumption, the diamond regresses back with new evidence. This creates smooth flow from idea to delivery without artificial phase breaks.

Diamond lifecycle: diamonds can be active, blocked, archived, or killed. Stale diamonds (30+ days without progress) are flagged for review.

Theory Gates (12 gates)

Every diamond transition must pass theory gates -- not just a confidence score, but evidence checks grounded in specific frameworks:

If ANY gate fails, the agent reports which gates failed, cites the theory, suggests the skill to run, and recommends the smallest action to satisfy each -- but does NOT proceed.

The Canvas (Source of Truth)

All product knowledge lives in .claude/canvas/*.yml -- 21 structured YAML files that serve as the single source of truth:

Canvas files are committed to git. They ARE your product documentation. Not all canvas files are required for every project -- the /interview skill classifies your project type and product type, then tells you which canvas files to focus on.

Harnessing System (What Prevents the Agent from Going Haywire)

Guardrails (.claude/harness/guardrails.md) -- 30 constraints across three enforcement tiers:

• BLOCK (2): Mechanically prevented by hooks. Secrets in code (G-S1), stale corrections (G-P5).
• REVIEW (13): /diamond-progress refuses to complete delivery until satisfied. Tests, a11y, usability (Nielsen), services quality (Downe), threat modeling, input validation, BVSSH, decision logging, error states, canvas updates, AI disclosure, regulatory awareness, privacy.
• NUDGE (15): Nudged by hooks, not blocking. Engineering principles (DRY, KISS, YAGNI, XP values), bias checks, data minimization, secure defaults, theory citations, devil's advocate, BVSSH dimensions, sustainable pace.

Anti-Patterns (.claude/harness/anti-patterns.md) -- 32 known failure modes across discovery, confidence, security, delivery, market/GTM, and strategic systems thinking:

• "Solution-first thinking", "Confidence inflation", "Security-later", "Dark pattern marketing", "Regression avoidance", and more

Cognitive Biases (.claude/harness/cognitive-biases.md) -- Per-stage bias checklist based on Shotton and Kahneman. 20+ biases mapped across L0-L5 including agent's own biases.

Security & Trust (.claude/harness/security-trust.md) -- Per-stage security requirements from OWASP, STRIDE, and Privacy by Design.

Engineering Principles (.claude/harness/engineering-principles.md) -- Explicit rules for DRY, KISS, YAGNI, SoC, SOLID, Law of Demeter, Clean Code.

5-Layer Hook Enforcement

Mycelium enforces guardrails through hooks that fire automatically at different points:

Total overhead: ~6,000 tokens/session (negligible vs typical 50K-200K sessions).

Four-Speed Feedback Loop System

Based on Gene Kim's Three Ways, Argyris's double-loop learning, and Meadows's leverage points:

Run /feedback-review to check health across all loops. Includes regression warning triggers (e.g., "DORA declined twice in a row") and Goodhart's Law protection (counter-metrics for every tracked metric).

The L5 -> L2 feedback loop: After launch, market signals feed back into new L2 Opportunity diamonds, closing the full cycle: Purpose -> Strategy -> Discovery -> Solution -> Delivery -> Market -> Discovery.

Self-Learning

• Corrections Memory -- Accumulated learning from mistakes. Read before every task. Pruned when > 30 entries.
• Pattern Library -- Successful patterns to reuse across diamonds.
• Reflexion Loop -- Implement, validate, self-critique, retry (max 3 iterations).
• Eval Benchmarks -- 6 scenarios across discovery, delivery, and integration categories.
• Prompt Optimization -- A/B testing of instruction changes against eval baselines.

Plain-Language Communication

Mycelium communicates in human language, not framework jargon:

• "Discovering what problems to solve" not "L2 Opportunity Discover phase"
• "Confidence: Moderate -- based on 2 user interviews" not "Confidence: 0.5"
• After each phase, the agent offers to capture learnings

Operations & Maintenance

• Day-to-day: Session resumption via /diamond-assess, corrections review via hooks
• Weekly: Diamond state review, canvas updates
• Monthly: BVSSH health check, Wardley map review, stale diamond cleanup
• Quarterly: North Star review, strategic landscape refresh, eval benchmarks
• Escape hatch: Documented bypass process for emergencies (production incidents, hotfixes) with mandatory payback

Skills Reference (38 skills)

Onboarding & Assessment

Discovery

Quality & Governance

Delivery

Market & Organization

Canvas & Orchestration

Self-Improvement

Theories & Frameworks Integrated

Usage Modes

Solo Developer

• Canvas is your shared memory with the agent
• Decision log provides cross-session continuity
• The agent is your product thinking partner
• Run /diamond-assess to continue where you left off

Team

• Canvas files committed to git = shared product documentation
• Any team member's agent reads the same canvas state
• Canvas updates are PR-reviewed like code changes
• Different team members can work on different diamonds simultaneously
• Use Agent Teams or worktrees for parallel delivery

Agent Orchestration

When the OST has multiple solutions to explore in parallel:

Lead Agent (main session)
  |-- Worker 1 (worktree: feature/ai-search)   -- explores Solution A
  |-- Worker 2 (worktree: feature/filters)      -- explores Solution B
  |-- Worker 3 (worktree: feature/feed-algo)    -- explores Solution C
  |
  Fan-in: Compare results, update ICE scores, select winner

Workers get read-only canvas access and worktree isolation. Only the lead agent updates canvas and progresses diamonds.

JiT Tooling (Language-Agnostic)

Mycelium works with any tech stack, including polyglot/multi-language projects. When delivery begins:

1. Auto-detects languages, frameworks, project shape (single app, monorepo, multi-service), existing tooling
2. Generates stack-appropriate validation commands, linting, testing
3. Configures security scanning for detected stack(s)
4. Agent asks user to confirm before proceeding

Universal principles (DRY, KISS, testing pyramid, OWASP) apply to all stacks. Specific tooling (test runners, linters, formatters) is discovered per project.

Directory Structure

your-project/
  CLAUDE.md                    # Root Mycelium agent instructions (v0.10.0)
  .claude/
    settings.json              # Shared hook config + permissions (committed)
    engine/                    # Diamond rules, theory gates, confidence thresholds, Cynefin routing
    canvas/                    # 21 YAML source-of-truth files
    diamonds/                  # Active diamond state tracking
    harness/                   # Guardrails, anti-patterns, biases, security, engineering principles
    memory/                    # Corrections, patterns, product journal, delivery journal
    domains/                   # Phase-specific agent behavior (discovery/delivery/quality)
    skills/                    # 38 invocable skills
    hooks/                     # 6-layer enforcement (gate, nudge, reflexion, stop-check, session-start, skill-gates)
    orchestration/             # Solo/team modes, agent teams, fan-out, operations, escape hatch
    jit-tooling/               # Language-agnostic delivery tooling + polyglot detection
    evals/                     # 6 benchmark scenarios + results
    optimization/              # Prompt A/B testing baselines + variants

Regulatory Awareness: EU AI Act

Mycelium itself is not regulated by the EU AI Act (Regulation 2024/1689). It is configuration files, not an AI system under Article 3(1). It is protected as an open-source component under Article 25(4) and Recital 102.

However, products built WITH Mycelium may be regulated. If you're building an AI-powered product that makes decisions about people, interacts with users, or operates in the EU market, you should assess your obligations:

• High-risk systems (employment, credit scoring, healthcare, education, law enforcement) require conformity assessments, documentation, and human oversight
• User-facing AI must disclose its AI nature (Article 50, effective August 2026)
• Generative AI must mark synthetic content as AI-generated

Mycelium includes a Regulatory Gate in its theory gates that prompts you to assess risk classification at the L3 Solution stage. See .claude/harness/security-trust.md for the full regulatory awareness guide.

Mycelium does not certify EU AI Act compliance. For compliance decisions, consult qualified EU AI law counsel.

Acknowledgments

Mycelium is substantially shaped by community feedback. See CONTRIBUTORS.md for detailed credits.

v0.9.0 was shaped by:

• Simon Rohrer — named the core weakness (inferential vs computational enforcement), referenced Böckeler's harness engineering article
• Daniel Bentes — provided the comparison with BDSK (synaptiai/bdsk) that clarified upstream thinking vs downstream enforcement

Contributing

Contributions are welcome. Mycelium is built on open product development theory -- if you see a gap in the frameworks, a missing bias, an incomplete guardrail, or a better way to harness agent behavior, please open an issue or PR.

Validating Changes

Before submitting a PR, run the structural integrity validation:

bash tests/validate-template.sh

This checks that all cross-references, counts, versions, and file structures are consistent. It also runs in CI on every push and PR.

Areas for Contribution

• New skills for frameworks not yet integrated
• JiT tooling improvements for specific tech stacks
• Eval scenarios that test agent harnessing quality
• Hook enforcement patterns for new Claude Code events
• Integration patterns with other AI coding tools

License

MIT License. See LICENSE.

Mycelium is not affiliated with any of the authors or publishers of the books and frameworks referenced. All theory citations are for educational purposes and to properly credit the intellectual foundations this system builds upon.