MasterMind

AI-driven project planning. MasterMind feeds a project proposal and a structured question set through a local LLM (Ollama) in fixed execution phases, producing a written plan plus per-phase summaries you can review before writing any code.

It is built around the IDIOT method — a project execution framework that breaks any project into five ordered phases:

1. Investigation — audience, goals, sub-problems, prior art, tech choice
2. Design — architecture, required tech, cost, scale
3. Implementation — build the design piece by piece
4. Optimization — improve without sacrificing quality
5. Testing — user-proposed tests, derived test cases, unit/E2E tests
6. Follow-up — suggested next steps

questions.json encodes the full question tree for each phase (including nested sub-questions); IDIOTMethod.txt is the human-readable framework document.

How it works

proposal + IDIOT method + system prompt
        │
        ▼
┌──────────────────────────────┐
│ Investigation  (N questions) │ ──► question_001.txt … question_NNN.txt
├──────────────────────────────┤
│ Design           (N questions) │ ──► design_summary.txt
├──────────────────────────────┤
│ Implementation … Follow-up     │ ──► … _summary.txt
└──────────────────────────────┘
        │
        ▼
experiment_results.json  (per-phase index of summary files)

• Each question is sent to the model with the project proposal, the IDIOT method, and a sliding context window (the last 5 accumulated answers) so context stays bounded on long runs.
• After every phase, a second model call writes a concise per-phase summary.
• All outputs land in a folder named after your project.

Requirements

• Python 3.10+
• Ollama running locally (default: http://localhost:11434)
• A model pulled locally, e.g.:

ollama pull gpt-oss:20b

Quickstart

python3 scripts/mastermind_cli.py \
  --project "Meilisearch UI" \
  --proposal "ProjectProposals/Meilisearch UI/proposal.txt" \
  --idiot IDIOTMethod.txt \
  --prompt-file "ProjectProposals/Meilisearch UI/system-prompt.txt" \
  --model gpt-oss:20b

Outputs appear in ./Meilisearch UI/.

Options

Flag	Default	Description
--project NAME	required	Project name; a folder with this name stores the outputs (alphanumeric, -, _ only)
--proposal PATH	required	Project proposal document (text)
--idiot PATH	required	IDIOT method document (text)
--prompt-file PATH	system_prompt.txt	System prompt file
--model NAME	gpt-oss:20b	One of gpt-oss:20b, qwen3:30b, devstral:24b, llama3.3:70b
--questions-file PATH	questions.json (repo root)	Question tree JSON
--output-dir PATH	current directory	Where the project folder is created (must be under the current directory)
--ollama-url URL	$OLLAMA_URL or http://localhost:11434/api/generate	Ollama endpoint
--api-key KEY	$OLLAMA_API_KEY	Optional bearer token for Ollama
--timeout SECONDS	120	Per-request timeout

The question tree supports nested subQuestions, which are asked in depth-first order. Empty questions are skipped.

Project layout

.
├── IDIOTMethod.txt                 # The IDIOT execution framework
├── questions.json                  # Phase → question tree
├── ProjectProposals/
│   └── Meilisearch UI/             # Example proposal + system prompt
├── scripts/
│   └── mastermind_cli.py           # The CLI
└── tests/
    └── test_mastermind_cli.py

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

MIT — see LICENSE.