# 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.