multishot

From one spec to a complete AI project pipeline, automatically.

multishot transforms a single markdown spec into a full, executable development flow. It builds your phase roadmap, expands each step into testable AI prompts, and runs them in sequence, all while enforcing strict logging and success criteria.

Suggest a Feature or Report a Bug

---

Table of Contents

• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • CLI Options
• Roadmap
• Contributing
• License
• Contact
• Acknowledgments

---

About The Project

multishot turns a single project specification into an actionable, multi-phase workflow for AI development. It reads your high-level goals, generates phase outlines, expands them into task prompts with logging constraints, and then executes each task sequentially through a configured AI CLI.

Key capabilities:

• Deterministic generation of multishot/phases.md from multishot/project.md
• Per-phase task prompt creation under multishot/Phase*/task*.md
• Sequential task execution that halts on the first failure and surfaces the offending phase/task
• Strict adherence to logging rules and the Success/Failure stdout contract

Built With

• Node.js (18+)
• Commander
• Vitest

---

Getting Started

Prerequisites

• Codex CLI (others coming soon)
• Node.js 18 or later
• A project specification stored at multishot/project.md (see docs/sample-project.md for inspiration)

Installation

# install the CLI globally from GitHub
npm install -g alfreema/multishot

# verify the command is on your path
multishot --help

---

Usage

# generate phase plan
multishot --gen-phases

# generate task prompts for every phase
multishot --gen-tasks

# execute all task prompts sequentially
multishot --run-tasks

# execute only a single phase
multishot --run-phase "Phase 1"

CLI Options

• --cli <codex-cli>
  Selects the backing AI CLI. Defaults to codex-cli (currently the only supported integration).

• --gen-phases
  Reads multishot/project.md and produces multishot/phases.md.

• --gen-tasks
  Scans multishot/phases.md, generates per-phase prompts under multishot/PhaseX/taskY.md, and stops if any target directory already exists.

• --run-tasks
  Iterates every generated task prompt (multishot/PhaseX/taskY.md), executing them through the configured CLI until completion or the first failure.

• --run-phase <phase>
  Executes all tasks for a single phase, by phase name (e.g., --run-phase "Phase1").

---

Model Selection

• Generation (--gen-phases, --gen-tasks) uses gpt-5-medium.
• Execution (--run-tasks, --run-phase) uses gpt-5-codex-low.

These defaults are applied internally when invoking the configured CLI.

---

Roadmap

• Support additional CLI integrations (Claude, OpenAI realtime, etc.)
• Rich status reporting and summaries after task execution
• Optional retries for infra-classified failures

See the open issues for a full list of proposed features and known issues.

---

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/my-feature)
3. Commit your Changes (git commit -m 'feat: add amazing feature')
4. Push to the Branch (git push origin feat/my-feature)
5. Open a Pull Request

Please open an issue first to discuss major changes or architectural shifts.

---

License

Distributed under the MIT License. See LICENSE for more information.

---

Contact

Aaron Freeman - GitHub

Project Link: https://github.com/alfreema/multishot

---

Acknowledgments

• Best-README-Template
• Commander.js
• Vitest