project-guides 1.2.6

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

A Python CLI tool that installs and synchronizes battle-tested LLM workflow guides across projects, supporting version tracking and project-specific overrides to keep documentation consistent while preserving customizations.

Why project-guides?

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.

Key Features:

• 📚 Battle-Tested Workflows - Crafted guides from concept through production release
• 🔄 Version Management - Track and update guides across projects automatically
• ✏️ Project-Specific Overrides - Lock customized guides to prevent overwrites
• 🔒 Automatic Backups - Preserve customizations when forcing updates
• 🎨 CLI Interface - Seven intuitive commands for all operations
• 🧪 Well Tested - 82% test coverage with 53 comprehensive tests
• ⚡ Zero Configuration - Works with sensible defaults out of the box
• 🌐 Cross-Platform - Runs on macOS, Linux, and Windows with Python 3.11+

Installation

Via pip

pip install project-guides

Via pipx (recommended for CLI tools)

pipx install project-guides

Quick Start

1. Initialize guides in your project

cd /path/to/your/project
project-guides init

This creates:

• .project-guides.yml - Configuration file
• docs/guides/ - Directory with guide templates

2. Check guide status

project-guides status

Output:

project-guides v1.1.2 (installed: v1.1.2)

Guides status:
  ✓ project-guide.md                         v1.1.2  (current)
  ✓ best-practices-guide.md                  v1.1.2  (current)
  ✓ debug-guide.md                           v1.1.2  (current)

All guides are up to date.

3. Customize a guide (optional)

project-guides override debug-guide.md "Custom debugging workflow for this project"

4. Update guides to latest version

project-guides update

Overridden guides are skipped by default. Use --force to update them (creates backups).

Command Reference

init

Initialize project-guides in the current directory.

project-guides init [OPTIONS]

Options:

• --target-dir PATH - Directory for guides (default: docs/guides)
• --force - Overwrite existing configuration

Examples:

# Initialize with default settings
project-guides init

# Use custom directory
project-guides init --target-dir documentation/workflows

# Force reinitialize
project-guides init --force

status

Show status of all installed guides.

project-guides status

Output includes:

• Current package version
• Installed version in project
• Status of each guide (current, outdated, overridden, missing)
• Override reasons

update

Update guides to the latest version.

project-guides update [OPTIONS]

Options:

• --guides NAME - Update specific guides only (repeatable)
• --force - Update even overridden guides (creates backups)
• --dry-run - Show what would change without applying

Examples:

# Update all guides (skips overridden)
project-guides update

# Update specific guides
project-guides update --guides project-guide.md --guides debug-guide.md

# Force update all (creates backups for overridden)
project-guides update --force

# Preview changes
project-guides update --dry-run

override

Mark a guide as customized to prevent automatic updates.

project-guides override GUIDE_NAME REASON

Arguments:

• GUIDE_NAME - Name of the guide file
• REASON - Why this guide is customized

Example:

project-guides override debug-guide.md "Custom debugging workflow with project-specific tools"

unoverride

Remove override status from a guide.

project-guides unoverride GUIDE_NAME

Example:

project-guides unoverride debug-guide.md

overrides

List all overridden guides.

project-guides overrides

Output:

Overridden guides:

debug-guide.md
  Reason: Custom debugging workflow with project-specific tools
  Since: v0.12.0
  Last updated: 2026-03-03

purge

Remove all project-guides files from the current project.

project-guides purge [OPTIONS]

Options:

• --force - Skip confirmation prompt

Examples:

# Purge with confirmation prompt
project-guides purge

# Purge without confirmation
project-guides purge --force

What gets removed:

• .project-guides.yml configuration file
• Guides directory (e.g., docs/guides/) and all contents

Warning: This action cannot be undone. Use with caution.

Configuration

The .project-guides.yml file stores project configuration:

version: "1.0"
installed_version: "1.1.2"
target_dir: "docs/guides"
overrides:
  debug-guide.md:
    reason: "Custom debugging workflow with project-specific tools"
    locked_version: "1.0.0"
    last_updated: "2026-03-09"

Fields:

• version - Config file format version
• installed_version - Version of guides currently installed
• target_dir - Where guides are stored
• overrides - Map of customized guides with metadata

Available Guides

Core Guides

• project-guide.md - Complete workflow for starting new projects with LLMs
• best-practices-guide.md - Development best practices and lessons learned
• debug-guide.md - Debugging strategies and troubleshooting workflows

Documentation Guides

• documentation-setup-guide.md - Setting up MkDocs documentation
• README.md - README template and guidelines

Developer Guides

• developer/codecov-setup-guide.md - Code coverage with Codecov
• developer/github-actions-guide.md - CI/CD with GitHub Actions

Troubleshooting

"Configuration file not found"

Problem: Running commands outside a project-guides initialized directory.

Solution:

project-guides init

"Guide already exists"

Problem: Trying to initialize when guides already exist.

Solution:

# Use --force to overwrite
project-guides init --force

# Or manually remove existing guides
rm -rf docs/guides .project-guides.yml
project-guides init

"Permission denied"

Problem: Insufficient permissions to write files.

Solution:

# Check directory permissions
ls -la docs/

# Fix permissions if needed
chmod -R u+w docs/

Updates not appearing

Problem: Guides show as current but you expect updates.

Solution:

# Check if guide is overridden
project-guides overrides

# Force update if needed
project-guides update --force

Development

Setup

# Clone repository
git clone https://github.com/pointmatic/project-guides.git
cd project-guides

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=project_guides --cov-report=term-missing

# Run specific test file
pytest tests/test_cli.py -v

Code Quality

# Linting
ruff check project_guides/ tests/

# Type checking
mypy project_guides/

# Format code
ruff format project_guides/ tests/

Documentation Development

The project uses MkDocs with Material theme for documentation.

# Install documentation dependencies
pip install -e ".[docs]"

# Preview documentation locally (with live reload)
mkdocs serve
# Open http://127.0.0.1:8000

# Build documentation
mkdocs build

# Build with strict mode (fails on warnings)
mkdocs build --strict

Directory Structure:

• docs/site/ - Documentation source files (markdown)
• site/ - Built documentation (generated, gitignored)
• mkdocs.yml - MkDocs configuration
• .github/workflows/deploy-docs.yml - Automated deployment to GitHub Pages

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Ensure all tests pass and maintain coverage above 80%
4. Run linting and type checks before submitting
5. Write clear commit messages referencing issues when applicable
6. Submit a pull request with a description of changes

Development Workflow

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and test
pytest tests/
ruff check .
mypy project_guides/

# Commit and push
git commit -m "Add feature: description"
git push origin feature/your-feature-name

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Copyright (c) 2026 Pointmatic

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

📚 Full documentation is available at pointmatic.github.io/project-guides

• Getting Started - Installation and quick start
• User Guide - Commands, workflows, and override management
• Developer Guide - Contributing and development setup
• Workflow Guides - Bundled LLM workflow guides in your project

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: GitHub Pages

---

Made with ❤️ for LLM-assisted development workflows