project-guides - Stay organized in LLM-based coding
Author: Pointmatic
Description: Stay organized and consistent using LLM workflow guides with project-specific overrides
Keywords: llm, human-in-the-loop, hitloop, documentation, workflow, guides, templates, python, cli, version-management, synchronization, project-management, development-tools, best-practices, override-support, yaml-config, cross-platform

# Stay organized in LLM-based coding

Stay organized and consistent using LLM workflow guides with project-specific overrides

Install project-guides in any repository with `pip install project-guides`, run `project-guides 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-guides update` to sync all non-overridden guides.

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-guides`

### 2. Initialize

Navigate to your project directory and initialize

`project-guides 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-guides override <guide-name>`

### 6. Update

Pull latest workflow improvements

`project-guides update`

### 7. Check Status

See which guides are current, outdated, or overridden

`project-guides status`

## Features

### Core Capabilities

#### Battle-Tested Workflows

Crafted guides walk your LLM from project concept through production release—planning docs, stories breakdown, step-by-step implementation.

#### Centralized Guide Templates

Maintain LLM workflow guides in one package and distribute them across all your projects with a single command.

#### Smart Version Tracking

Track which guide versions are installed in each project and update to the latest versions automatically.

#### Project-Specific Overrides

Lock customized guides to prevent accidental overwrites while still syncing other guides to latest versions.

#### Sync Latest Improvements

Pull the newest workflow refinements into all non-overridden guides across projects with one command.

### Operational Benefits

#### Zero Configuration

Works out of the box with sensible defaults—guides go in `docs/guides`, no config file needed for basic usage.

#### Clear Status Reporting

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

#### Automatic Backups

When updating overridden guides with --force, automatic .bak files preserve your customizations.

#### Safe Operations

Idempotent commands and explicit consent requirements ensure you never lose 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

82% test coverage with 59 comprehensive tests ensuring reliability and stability.

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

Guides enforce a proven methodology: planning documents, story breakdown, step-by-step implementation, approval gates.