Mode-driven templates for organized LLM development

Install project-guide in any repository with pip install project-guide, run project-guide init, then tell your LLM to "Read docs/project-guide/go.md and start." A single rendered entry point dynamically assembles instructions from 15 development modes—planning, setup, coding, debugging, documentation, refactoring, and more—using Jinja2 templates. Type "go" to advance through each step. Switch modes as needed to get the right guidance for the task at hand.

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 file for your project, lock it so future package updates skip it. When you want the latest workflow improvements, run project-guide update to sync all non-locked files.

View on GitHub Install from PyPI Read Documentation

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 rendered entry point

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

4. Advance

Type "go" to advance through each workflow step

go

5. Switch Modes

Change modes to match your current task

project-guide mode <mode-name>

6. Update

Pull latest workflow improvements

project-guide update

7. Check Status

See which files are current, outdated, or locked

project-guide status

Features

Core Capabilities

Mode-Driven Workflows

15 development modes—planning, setup, coding, debugging, documentation, refactoring, and more—each tailored with the right instructions for the task.

Dynamic Rendering

Jinja2 templates assemble a single rendered entry point (go.md) from mode-specific content, so the LLM always sees exactly what it needs.

Hash-Based Sync

Content-hash tracking detects changes precisely, so updates only touch files that actually differ from the package version.

File Override Lock

Lock any customized file to prevent future package updates from overwriting your project-specific changes.

Compact Status

Color-coded status output shows at a glance which files are current, outdated, locked, or missing.

Zero Configuration

Works out of the box with sensible defaults. Run init and start working immediately.

Operational Benefits

Cross-Platform

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

Well Tested

131 tests with 91% coverage ensure reliability across platforms and edge cases.

Lightweight and Fast

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

Selective File Updates

Use the --files flag to update specific files, or update everything at once with a single command.

Shell Completion

Tab completion for commands, flags, and mode names in bash, zsh, and fish — including dynamic completion of mode names from your project's metadata.

Safe Operations

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

Gentle Forced Updates

Automatic .bak files created if you force-update a locked file, so nothing is lost.

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 across 15 modes with approval gates at every step.