Mycelium Setup

• .mycelium/state.json
• .mycelium/context/product.md
• .mycelium/context/tech-stack.md
• .mycelium/context/workflow.md
• .mycelium/solutions/patterns/critical-patterns.md

See [.mycelium/ directory structure][mycelium-dir] for complete specification.

If all required files present (complete structure):

✅ Mycelium structure already exists and is complete.

Structure:
  ✓ .mycelium/state.json
  ✓ .mycelium/context/product.md
  ✓ .mycelium/context/tech-stack.md
  ✓ .mycelium/context/workflow.md
  ✓ .mycelium/solutions/patterns/critical-patterns.md
  ✓ .mycelium/plans/
  ✓ .mycelium/solutions/

Next steps:
  • Review context files: .mycelium/context/
  • Start planning: /mycelium-plan [description]
  • Full workflow: /mycelium-go [description]

→ EXIT (setup already complete)

If partially complete (missing required files):

⚠️  Incomplete .mycelium/ structure found.

Present:
  ✓ .mycelium/state.json
  ✓ .mycelium/context/product.md

Missing:
  ✗ .mycelium/context/tech-stack.md
  ✗ .mycelium/context/workflow.md
  ✗ .mycelium/solutions/patterns/critical-patterns.md

Options:
  1. Complete the missing files (recommended)
  2. Start fresh (deletes existing .mycelium/)
  3. Exit (manual fix required)

Enter 1-3:

Handle user choice:

• Option 1 (Complete): Continue to Step 4 (Create Directory Structure) to create only missing files
• Option 2 (Start fresh): rm -rf .mycelium/, then continue to Step 1
• Option 3 (Exit): Show guidance on how to manually fix, then EXIT

Step 1: Check for Existing Setup

Check if [setup_state.json][setup-state-schema] exists and determine next action.

┌─────────────────────────────────────┐
│ Does setup_state.json exist?       │
└─────────┬───────────────────────────┘
          │
    ┌─────┴─────┐
    NO          YES
    │           │
    │     ┌─────┴──────────────────────┐
    │     │ Check status field         │
    │     └─────┬──────────────────────┘
    │           │
    │     ┌─────┴─────┐
    │     │           │
    │  "completed"  "in_progress"
    │     │           │
    │     │           │
┌───▼─────▼───┐   ┌──▼─────────────────┐
│ Path A:     │   │ Path C:            │
│ Start fresh │   │ Resume from        │
│ setup       │   │ checkpoint         │
│             │   │                    │
│ → Step 2    │   │ Show progress      │
│             │   │ → current_section  │
└─────────────┘   └────────────────────┘
                  │
  ┌───────────────┘
  │ Path B:
  │ Setup complete
  │
  │ Info: Already done
  │ → EXIT
  └────────────────

Path A: No setup_state.json

→ Fresh setup, continue to Step 2

Path B: setup_state.json exists with status="completed"

✅ Setup already complete!

Completed: {completed_at}
Files created: {count} files

Next steps:
  /mycelium-plan [description]
  /mycelium-go [description]

→ EXIT

Path C: setup_state.json exists with status="in_progress"

⏸️  Resuming interrupted setup...

Progress:
  ✓ {completed_sections}
  → {current_section} (question {current_question})

Last updated: {last_updated}

Options:

1. Resume - Continue from where you left off
2. Restart - Delete state and start fresh
3. Exit - Manual intervention needed

Ask user choice → handle accordingly:

• Option 1 (Resume): Load answers, continue from current_section and current_question
• Option 2 (Restart): Delete .mycelium/setup_state.json, continue to Step 2
• Option 3 (Exit): Show current state details, EXIT

Step 2: Detect Project Type

Analyze the current directory to determine if this is a new or existing project.

Greenfield Detection

Indicators (new project):

• Empty directory or only has README
• No package.json, go.mod, Cargo.toml, requirements.txt, pyproject.toml
• No src/, lib/, app/, pkg/ directories
• No existing source code

Action: Run full interactive setup with all questions

Brownfield Detection

Indicators (existing project):

• Has package.json, go.mod, requirements.txt, Cargo.toml, etc.
• Has existing source code in src/, lib/, app/, etc.
• Has test files
• Has existing git repository

Action:

• Extract context from existing files
• Pre-populate answers by analyzing:
  • package.json → project name, dependencies, scripts
  • README.md → description, purpose
  • Existing code → language, framework, patterns
  • .gitignore → deployment target hints
• Ask user to confirm/correct detected values
• Only ask for information that cannot be inferred

Step 3: Interactive Setup

CRITICAL RULES:

1. ✅ Ask ONE question per turn
2. ✅ Wait for user response before proceeding
3. ✅ Offer 2-4 suggested answers + "Type your own" option
4. ✅ Maximum 5 questions per section
5. ✅ Update [setup_state.json][setup-state-schema] after EACH successful answer
6. ✅ Validate file write succeeded before continuing

Ask questions ONE AT A TIME following this pattern:

PRODUCT Section (what & why)

Question 1 of 4: Project Identity

What is this project?

Suggested answers:
  1. TaskFlow - A workflow automation tool
  2. DataHub - A data integration platform
  3. CodeReview - An automated code review system
  4. Type your own answer

Enter 1-4:

After user responds:

1. If 1-3: Extract project name and description
2. If 4: Prompt for custom "ProjectName - Description"
3. Save to [setup_state.json][setup-state-schema]:

   {
     "current_section": "product",
     "current_question": 2,
     "completed_sections": [],
     "answers": {
       "project_identity": "TaskFlow - A workflow automation tool"
     }
   }
   

4. Verify write succeeded: const state = await readFile('setup_state.json')
5. If write failed: Error "❌ Failed to save answer, cannot continue"
6. Continue to Question 2

Question 2 of 4: Problem Statement

What problem does this project solve?

Suggested answers:
  1. Manual processes waste developer time
  2. Lack of integration between tools
  3. Poor visibility into workflows
  4. Type your own answer

Enter 1-4:

After user responds: Save answer, update current_question: 3, verify, continue

Question 3 of 4: Target Users

Who are the target users?

Suggested answers:
  1. Software development teams (5-50 people)
  2. DevOps engineers
  3. Engineering managers
  4. Type your own answer

Enter 1-4:

After user responds: Save answer, update current_question: 4, verify, continue

After Question 3 (Target Users) complete: Update state:

{
  "current_section": "tech_stack",
  "current_question": 1,
  "completed_sections": ["product"]
}

Note: Goals are optional and can be added later to .mycelium/context/product.md

TECH STACK Section (with what)

For brownfield projects: Detect language/framework from files first, then confirm with user.

Question 1 of 4: Primary Language

What programming language?

Suggested answers:
  1. TypeScript
  2. Python
  3. Go
  4. Type your own (JavaScript, Rust, Java, etc.)

Enter 1-4:

After user responds: Save answer, update current_question: 2, verify, continue

Question 2 of 4: Framework

What framework or library?

Suggested answers:
  1. React + Next.js
  2. FastAPI (Python)
  3. Gin (Go)
  4. Type your own

Enter 1-4:

After Question 2 (Framework) complete: Update state:

{
  "current_section": "workflow",
  "current_question": 1,
  "completed_sections": ["product", "tech_stack"]
}

Note: Database and infrastructure are optional and can be added later to .mycelium/context/tech-stack.md

WORKFLOW Section (how to work)

Question 1 of 1: TDD Strictness

How strict should TDD enforcement be?

Suggested answers:
  1. strict - All code follows RED-GREEN-REFACTOR (recommended)
  2. flexible - TDD for new features, optional for fixes
  3. none - No TDD enforcement
  4. Type your own approach

Enter 1-4:

Default: strict

After user responds:

1. Save answer, update:

   {
     "current_section": null,
     "current_question": null,
     "completed_sections": ["product", "tech_stack", "workflow"],
     "answers": {
       "tdd_strictness": "strict",
       "commit_style": "conventional",
       "review_required": "recommended",
       "coverage_target": 80
     }
   }
   

2. Automatically apply recommended defaults:
   • Commit style: conventional (feat/fix/chore format)
   • Code review: recommended (for major changes)
   • Coverage target: 80%
3. Verify, continue to Step 4 (Create Directory Structure)

Note: Advanced settings (commit style, review requirements, coverage) use recommended defaults. Edit .mycelium/context/workflow.md to customize later.

Step 4: Create Directory Structure

Once all answers collected, create this structure:

project/
├── CLAUDE.md                    # Quick context file
├── .mycelium/                   # AI workflow artifacts
│   ├── context/                 # Project information
│   │   ├── product.md
│   │   ├── tech-stack.md
│   │   └── workflow.md
│   ├── plans/                   # Living plan documents
│   ├── solutions/               # Captured learnings
│   │   ├── performance-issues/
│   │   ├── database-issues/
│   │   ├── security-issues/
│   │   ├── ui-bugs/
│   │   ├── integration-issues/
│   │   └── patterns/
│   │       └── critical-patterns.md
│   ├── state.json               # Session state
│   └── setup_state.json         # Setup progress
└── docs/                        # User documentation (if not exists)

See [.mycelium/ directory structure][mycelium-dir] for complete documentation of this structure and all file purposes.

File Templates

CLAUDE.md:

# {project_name}

{product_description}

## Quick Context

**What**: {problem_statement}
**Who**: {target_users}
**Stack**: {primary_language} + {frameworks}

## Key Goals

{list_of_goals}

## Getting Started

See `.mycelium/context/` for detailed project information.

## Workflow

- `/mycelium-plan` - Plan new work
- `/mycelium-work` - Execute tasks
- `/mycelium-review` - Review code
- `/mycelium-capture` - Capture learnings

.mycelium/context/product.md:

---
product_name: {name}