project-guide banner

Stay organized and in control with adaptive workflow prompts

Install project-guide in any repository with pip install project-guide, run project-guide init, then tell your LLM to "Read docs/guides/project-guide.md and start." The guide walks the LLM through planning documents, breaking work into stories, and implementing each story step-by-step. You just say "proceed" after each step. The developer stays in charge—guiding features, flow, and taste—while the LLM handles the typing.


This is "HITLoop" (human-in-the-loop) development: the developer directs, the LLM executes. The pace is "flaming agile"—an entire production-ready backend can be completed in 6-12 hours. When you customize a guide for your project, mark it as overridden so future package updates skip it. When you want the latest workflow improvements, run project-guide update to sync all non-overridden guides.

Quick Start

1. Install

Install via pip or pipx for system-wide CLI access

pip install project-guide

2. Initialize

Navigate to your project directory and initialize

project-guide init

3. Start

Tell your LLM to read the guide and begin

Read `docs/guides/project-guide.md` and start.

4. Collaborate

Say "proceed" after each step as the LLM works

proceed

5. Customize

Mark guides as overridden when you customize them

project-guide override <guide-name>

6. Update

Pull latest workflow improvements

project-guide update

7. Check Status

See which guides are current, outdated, or overridden

project-guide status

Features

Core Capabilities

Battle-Tested Workflows

Crafted workflow prompts from concept through production release in one place.

Adaptive Guidance

Switch project between plan, code, and debug modes to get the right instructions for each task.

Version Management

Track and update all prompt docs in a project with a single command.

Custom Prompt Lock

Lock a customized LLM prompt in any project to prevent future updates for that prompt document.

CLI Interface

Eight intuitive commands for all operations.

Zero Configuration

Works out of the box with sensible defaults.

Operational Benefits

Clear Status Reporting

See at a glance which guides are current, outdated, overridden, or missing with color-coded status output.

Gentle 'Forced' Updates

Automatic `.bak` files created if you `--force` update a custom prompt document.

Safe Operations

Idempotent commands and explicit consent requirements protect your project-specific customizations.

Lightweight & Fast

Minimal dependencies (click, pyyaml, packaging) mean fast installation and no bloat.

Cross-Platform

Runs on macOS, Linux, and Windows with Python 3.11+ for consistent workflows everywhere.

Well Tested

Comprehensive test coverage minimum of 85% ensures reliability.

Development Philosophy

HITLoop Development

You direct features, flow, and taste. The LLM handles the typing. Human-in-the-loop collaboration at its best.

Flaming Agile Pace

Complete an entire production-ready backend in 6-12 hours with structured, methodical LLM collaboration.

Structured Workflow

The workflow enforces a focused methodology: planning, coding, debugging, etc. with approval gates.