Mimir

Your Ever-Evolving Engineering Playbook

Mimir helps you work more effectively by providing structured playbooks that your AI assistant can access directly in your IDE. Get guidance, generate work plans, track progress, and continuously improve your development process.

For architecture and design details, see docs/architecture/SAO.md

Core Entities

Mimir organizes your playbooks using 7 core entities:

1. Playbook - Top-level methodology container (e.g., "FDD", "Scrum")
2. Workflow - Sequence of activities for a process (e.g., "Build Feature")
3. Phase (optional) - Grouping for activities within workflows (e.g., "Inception", "Construction")
4. Activity - Unit of work with guidance (e.g., "Create screen mockup")
5. Artifact - Inputs/outputs of activities (e.g., "Component Specification", "Unit Tests")
6. Role - Who performs activities (e.g., "Frontend Engineer", "UX Designer")
7. Howto - Specific implementation instructions (e.g., "Creating mockups with Figma")

What Can Mimir Do?

Answer Playbook Questions via MCP

Your AI assistant can query Mimir directly from your IDE (powered by FastMCP):

You: "How do I build a TSX component per FDD playbook?"
AI: → Queries Mimir → Returns activity guidance and relevant Howtos

Generate Work Plans

Automatically create task breakdowns in GitHub or Jira:

You: "Plan implementation of scenario LOG1.1 and Screen LOG per FDD"
AI: → Generates work orders from playbook → Creates GitHub issues

Assess Project Progress

Check if you've completed all required artifacts for a phase:

You: "I'm supposed to finish inception phase next week. Did I produce all required artifacts?"
AI: → Scans codebase and issues → Reports status and gaps

Evolve Through Experience

When AI encounters issues during work, it can propose playbook improvements:

AI: → Detects repeated corrections → Creates Playbook Improvement Proposal (PIP)
You: → Reviews PIP in web UI → Approves with notes → New playbook version created

Access Playbook Library

Download playbooks from HOMEBASE based on your access level:

• Family-based: Software Engineering, UX Design, Testing, etc.
• Version tiers: LITE (Basic), FULL (Standard), EXTENDED (Premium)

Quick Start with Docker

Two containers: FOB (Django web UI + API) and MCP Facade (connects your AI IDE to FOB).

Step 1 — Run FOB

# Authenticate to ECR (one-time)
aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin \
    411113550285.dkr.ecr.us-east-1.amazonaws.com

# Run with persistent storage (optional: pass GITHUB_TOKEN + GITHUB_BUG_REPO for Feedback → Issues)
docker run -d \
  --name mimir-fob \
  -p 8000:8000 \
  -v ~/mimir-data:/app/data \
  -e MIMIR_USER=admin \
  -e MIMIR_PASSWORD=changeme \
  -e MIMIR_EMAIL=admin@localhost \
  411113550285.dkr.ecr.us-east-1.amazonaws.com/mimir:latest

open http://localhost:8000

Step 2 — Get your API token

curl -s -X POST http://localhost:8000/api/auth/token/ \
  -d "username=admin&password=changeme" | python3 -c \
  "import sys,json; print(json.load(sys.stdin)['token'])"

Step 3 — Configure MCP in your IDE

The MCP facade is published as a public Docker Hub image (featurefactory/mimir-mcp) — no registry login needed.

Devin (~/.config/devin/mcp_config.json), Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json), Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mimir": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MIMIR_DEV_ROOT=/Users/you/GitHub",
        "-v", "/Users/you/GitHub:/Users/you/GitHub",
        "-e", "MIMIR_SERVER_URL=http://localhost:8000",
        "-e", "MIMIR_TOKEN=<your-token>",
        "-e", "MCP_TRANSPORT=stdio",
        "featurefactory/mimir-mcp:latest"
      ]
    }
  }
}

Replace <your-token> with the token from Step 2. Restart your IDE after saving.

Export/import: filesystem MCP tools require MIMIR_DEV_ROOT and a matching Docker volume mount — see docs/DOCKER_QUICK_START.md.

Multi-platform: amd64 + arm64 · Data safety: SQLite in mounted volume · Hosted FOB: change MIMIR_SERVER_URL to https://mimir.featurefactory.io

See docs/DOCKER_QUICK_START.md for docker-compose setup and full reference.

Bug reports → GitHub Issues

The Feedback tab (and MCP report_bug / HTTP facade) create structured issues on GitHub. On the FOB (web) host set:

Variable	Description
GITHUB_TOKEN	Classic or fine-grained PAT with Issues: write on the target repo
GITHUB_BUG_REPO	Optional; default FeatureFactory-io/mimir
BUG_REPORT_DRY_RUN	Optional; 1 / true skips the API (smoke tests)

Docker Compose: add these to web service env (see .env.example). Do not put GITHUB_TOKEN on the MCP facade container — it calls the web API, which uses the token.

Maintainers publishing from CI configure GitHub Actions secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN — the workflow builds Dockerfile.mcp as featurefactory/mimir-mcp on each qualifying push (main, release/**, feat/**, releases, workflow dispatch). Legacy Azure Container Registry acrmimir was removed from the pipeline; when it is unused, tear it down in Azure (e.g. az login then az acr delete --name acrmimir --yes) and remove GitHub secrets ACR_USERNAME / ACR_PASSWORD if still present.

Prerequisites

• Python 3.11 or higher
• Graphviz (system dot binary — required for workflow activity diagrams; the graphviz pip package alone is not enough)
  • macOS: brew install graphviz
  • Debian/Ubuntu: sudo apt-get install graphviz
• IDE with MCP support (Claude Desktop, Cursor, Devin, etc.)
• Access credentials for HOMEBASE (optional, for syncing)
• Playwright browsers (optional — only for E2E tests): after pip install, run playwright install

Setup Steps

1. Clone the repository

   git clone https://github.com/petelind/mimir.git
   cd mimir
   

2. Configure environment

   cp .env.example .env   # edit values as needed (email, API keys, etc.)
   

   .env.example sets MIMIR_DB_PATH=mimir.dev.db so daily work stays in a personal SQLite file (gitignored). The committed mimir.db remains the shared seed only.

   Without a local .env, dev defaults may differ from .env.example (e.g. email via AWS SES instead of the console backend).

3. Create virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

4. Install dependencies

   pip install -r requirements.txt
   

5. Initialize database

   python manage.py migrate
   make dev-db-init    # once: copies seed mimir.db → mimir.dev.db
   

   Note: Committed mimir.db includes the FeatureFactory playbook (the workflow used to build Mimir). With MIMIR_DB_PATH=mimir.dev.db in .env, make run and make mcp use your personal copy; git will not track local users or experiments.

   After git pull updates the seed, refresh your sandbox: make refresh-dev-db.

6. Ensure local superuser

   Create or restore the conventional dev superuser used by MCP/facade tests:

   python manage.py create_default_admin
   

   Run this whenever your SQLite auth drifts after local experiments (recommended before pytest facade tests).

   For production or shared environments:

   python manage.py createsuperuser
   

   You'll be prompted for:

   • Username (required)
   • Email (optional, for password reset)
   • Password (minimum 8 characters)

7. Run tests

   Run unit and integration tests:

   pytest tests/
   

   E2E tests (optional) require Playwright browsers installed first:

   playwright install
   pytest tests/e2e/ -v
   

   Note: BDD feature files in docs/features/act-*/ serve as comprehensive UI specifications (46 files covering Acts 0-15). Step definitions will be implemented during development.

Quick Reference

Running the Application

# Start web UI (keep running in terminal)
make run
# → Open http://localhost:8000

# Test MCP server manually (different terminal)
make mcp
# → Press Ctrl+C to stop

# Personal DB (MIMIR_DB_PATH=mimir.dev.db in .env)
make dev-db-init      # once: copy seed → mimir.dev.db
make refresh-dev-db   # after pull: re-sync from committed mimir.db
make dev-db-reset     # wipe personal DB and recreate from seed

# Run all tests
pytest tests/

MCP Configuration Files

• Devin: ~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json; project: .devin/mcp_config.json)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

See the Quick Start section above for the config snippet.

---

How to Use

Mimir runs as two processes that work together:

1. Start the Web Interface

python manage.py runserver 8000

Open http://localhost:8000 in your browser and log in with your credentials.

Once logged in, you can:

• Browse playbooks: View activities, workflows, phases, artifacts, roles, and howtos
• Review PIPs: Approve or reject Playbook Improvement Proposals
• Compare versions: See what changed between playbook versions
• Edit locally: Customize playbooks for your team

2. Configure MCP in Your IDE

Register at mimir.featurefactory.io to get your token, then add to your IDE config:

Devin (~/.config/devin/mcp_config.json) · Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) · Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mimir": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MIMIR_DEV_ROOT=/Users/you/GitHub",
        "-v", "/Users/you/GitHub:/Users/you/GitHub",
        "-e", "MIMIR_SERVER_URL=https://mimir.featurefactory.io",
        "-e", "MIMIR_TOKEN=<your-token>",
        "-e", "MCP_TRANSPORT=stdio",
        "featurefactory/mimir-mcp:latest"
      ]
    }
  }
}

For a local FOB, set MIMIR_SERVER_URL=http://localhost:8000. Restart your IDE after saving.

Export/import filesystem tools require MIMIR_DEV_ROOT and a matching -v bind mount — see docs/DOCKER_QUICK_START.md.

3. Use MCP Tools in Your IDE

Once configured, your AI assistant has access to 16 Mimir MCP tools for managing playbooks, workflows, and activities:

Playbook Management (5 tools)

• create_playbook - Create new draft playbooks
• list_playbooks - List playbooks (filter by status: draft/released/all)
• get_playbook - Get detailed playbook info with nested workflows
• update_playbook - Update playbook details (auto-increments version)
• delete_playbook - Delete draft playbooks

Workflow Management (5 tools)

• create_workflow - Add workflows to playbooks
• list_workflows - List workflows for a playbook
• get_workflow - Get workflow details with activities
• update_workflow - Update workflow details
• delete_workflow - Delete workflows from playbooks

Activity Management (6 tools)

• create_activity - Add activities to workflows
• list_activities - List activities in a workflow
• get_activity - Get activity details with dependencies
• update_activity - Update activity guidance, name, phase
• delete_activity - Remove activities
• set_predecessor - Define activity dependencies (validates no circular deps)

Example Usage:

"Create a new playbook called 'Frontend Best Practices'"
"Add a workflow called 'Component Development' to playbook 5"
"List all activities in workflow 3"
"Update activity 7 to add more detailed guidance"

All tools support async operations and validate user permissions automatically.

Typical Workflow

Daily Development

1. Configure your IDE (one-time setup)

   Add Mimir to your IDE's MCP configuration (see section 2 above):

   • Devin: ~/.config/devin/mcp_config.json
   • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor: ~/.cursor/mcp.json

   Restart your IDE after configuration.

2. Start working with Mimir

   Once configured, interact with Mimir through your IDE's AI assistant:

   "Mimir, list available playbooks"
   "Mimir, show me the Build Page workflow"
   "Mimir, plan FOB-LOGIN-1 per BPE1 Plan Feature"
   "Mimir, implement backend per BPE2"
   

3. Optional: Web UI for management

   Start the web interface to manage playbooks visually:

   python manage.py runserver 8000
   

   Open http://localhost:8000 to:

   • Browse and edit playbooks
   • View workflows and activities
   • Manage methodology content

   Note: While a Playbook is in draft status, you can work with it directly: update, extend, and even delete - via both MCP and GUI. Once it's released, it can be revised only via PIPs (Playbook Improvement Proposals).

Troubleshooting

MCP Server Not Responding

1. Verify your token works:

   curl -s -H "Authorization: Token <your-token>" \
     http://localhost:8000/api/playbooks/
   

2. Test the MCP facade manually:

   docker run --rm -i \
     -e MIMIR_SERVER_URL=http://localhost:8000 \
     -e MIMIR_TOKEN=<your-token> \
     -e MCP_TRANSPORT=stdio \
     featurefactory/mimir-mcp:latest
   

   Send {"jsonrpc":"2.0","method":"tools/list","id":1} — you should get a list of 53 tools.

3. Check IDE logs:

   • Devin: View logs in MCP settings panel
   • Claude Desktop: Check ~/Library/Logs/Claude/
   • Cursor: Check IDE console for MCP connection errors

4. Common issues:

   • "Image not found": Run docker pull featurefactory/mimir-mcp:latest
   • "Unauthorized": Token expired — regenerate at your profile page
   • "Connection refused": FOB not running — check docker ps | grep mimir-fob

Database Locked

If you see "database is locked" errors:

# Ensure only one web server is running
pkill -f "manage.py runserver"

# Restart web server
python manage.py runserver 8000

Project Structure

Note: Internal code uses methodology as the technical term for accuracy (e.g., Django app name, models, commands), while user-facing terminology uses "playbooks" for accessibility. This is intentional - see SAO.md for details.

mimir/
├── docs/
│   ├── architecture/
│   │   └── SAO.md              # System architecture & design
│   ├── features/               # BDD specifications (46+ files)
│   │   ├── act-0-auth/         # Authentication, Onboarding, Navigation
│   │   ├── act-2-playbooks/    # Playbooks CRUDLF (5 files)
│   │   ├── act-3-workflows/    # Workflows CRUDLF (5 files)
│   │   ├── act-4-phases/       # Phases CRUDLF (5 files, optional entity)
│   │   ├── act-5-activities/   # Activities CRUDLF (5 files)
│   │   ├── act-6-artifacts/    # Artifacts CRUDLF (5 files)
│   │   ├── act-7-roles/        # Roles CRUDLF (5 files)
│   │   ├── act-8-howtos/       # Howtos CRUDLF (5 files)
│   │   ├── act-9-15/           # PIPs, Import/Export, Family, Sync, MCP, Settings, Errors
│   │   └── act-13-mcp/         # MCP integration specifications (4 files)
│   ├── mcp/                    # MCP documentation
│   │   ├── README.md           # MCP overview
│   │   └── *.md                # Implementation status documents
│   └── ux/
│       ├── user_journey.md     # Complete Acts 0-15 narrative
│       └── 2_dialogue-maps/
│           └── screen-flow.drawio  # Visual MVP flow diagram
├── mimir/                      # Django project
│   ├── methodology/            # Core app (internal name)
│   │   ├── models/             # Playbook, Workflow, Activity, etc.
│   │   ├── services/           # Business logic (PlaybookService, etc.)
│   │   ├── repository/         # Storage abstraction layer
│   │   └── views/              # Web UI views
│   └── mcp_integration/        # MCP server integration (Django app)
│       ├── tools.py            # 16 MCP tool functions (async)
│       ├── context.py          # User context management
│       └── management/
│           └── commands/
│               └── mcp_server.py  # Django command: mcp_server
├── tests/
│   ├── unit/                   # Unit tests (services, models)
│   ├── integration/            # Integration tests (MCP tools, workflows)
│   └── e2e/                    # End-to-end tests (Playwright)
├── manage.py
└── requirements.txt            # Includes fastmcp, pytest-asyncio

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

IDE-Specific Rules

Mimir maintains project rules in two formats to support different AI-powered IDEs:

• .windsurf/rules/*.md - For Devin / Windsurf-compatible IDE rules
• .cursor/rules/*.mdc - For Cursor IDE

Both rule sets contain identical content with different formatting. If you use Cursor and modify rules, ask your IDE to maintain sync between both formats to keep them consistent.

License

https://github.com/FeatureFactory-io/mimir#Apache-2.0-1-ov-file

Learning Resources

New to Django?

Quick Read (20 min): Django at a Glance

• Official Django overview
• Covers models, views, templates, URL routing
• Perfect primer before diving into Mimir's codebase

Video Tutorial (30 min): Django For Everybody - Introduction

• Dr. Chuck's accessible introduction
• Covers request/response cycle and MTV pattern
• From the popular "Django for Everybody" course

Bonus Quick Reference: Django Cheat Sheet

• One-page reference for common patterns
• Models, views, templates, forms at a glance

New to HTMX?

Quick Read (15 min): HTMX Documentation - Introduction

• Official docs covering core concepts
• AJAX requests with HTML attributes
• Swap strategies and event handling

Video Tutorial (25 min): HTMX Crash Course

• Practical examples of HTMX in action
• Progressive enhancement without JavaScript
• Perfect complement to Mimir's server-side approach

Interactive Examples (10 min): HTMX Examples

• Click Delete Row, Edit Row, Infinite Scroll examples
• Shows patterns Mimir uses for CRUD operations
• Live demos you can inspect

How Mimir Uses These Technologies

• Django: Custom views (no Django Forms), repository pattern, pytest testing
• HTMX: Partial page updates, form submissions, dynamic content loading
• Together: Server-rendered UI with smooth interactivity, testable without browser automation

See docs/architecture/SAO.md for Mimir's specific implementation patterns.

---

Learn More

• Architecture: docs/architecture/SAO.md - Complete system design
• User Journey: docs/features/user_journey.md - Complete Acts 0-15 narrative with all screens
• Feature Files: docs/features/ - 46 BDD specifications covering full CRUDLF for all entities
• Screen Flow: docs/ux/2_dialogue-maps/screen-flow.drawio - Visual MVP flow diagram
• UI Guidelines: docs/ux/IA_guidelines.md - Bootstrap design system, forms, validation, toasts
• GitHub Issues: MVP Milestone - Track development progress
• MCP Protocol: Model Context Protocol Specification

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Project Board: MVP Milestone