project-guide 2.0.18

Stay organized and in control with adaptive LLM workflow prompts.

A Python CLI tool that installs, renders, and synchronizes battle-tested LLM workflow prompts across projects using mode-driven Jinja2 templates, with content-hash sync and project-specific overrides to keep documentation consistent while preserving customizations.

Why project-guide?

The go.md prompt provides the LLM with a structured workflow:

• Adapts for your current development mode (plan, code, debug, document, refactor)
• Lets you stay in charge: guiding features, flow, and taste
• Handles the typing so you can stay focused on the big picture

How It Works

• Install project-guide in any repository
• Initialize the Project-Guide system
• (optional) Set the project mode (plan, code, debug, etc.)
• Tell your LLM to read docs/project-guide/go.md (in your IDE, or however you prefer)

Human-in-the-Loop Development

This is "HITLoop" (human-in-the-loop) development: you direct, the LLM executes--it is not vibe-coding. Instead you are following the development closely and interactively guiding and improving the flow. The pace is "flaming agile"--an entire production-ready backend can be completed in 6-12 hours.

Customization and Updates

When you customize a file 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 files.

Key Features

• Battle-Tested Workflows - Crafted workflow prompts from concept through production release in one place
• Mode-Driven Templates - 15 modes rendered via Jinja2 so go.md always matches your current task
• Content-Hash Sync - SHA-256 hash comparison detects changes without relying on version numbers
• Custom File Lock - Lock customized files to prevent update overwrites
• Gentle Force Updates - Automatic .bak files created if you --force update a custom file
• CLI Interface - Eight intuitive commands for all operations
• Well Tested - 91% test coverage with 129 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-guide

Via pipx (recommended for CLI coding tools)

pipx install project-guide

Dependencies

click, jinja2, pyyaml, packaging

Quick Start

1. Initialize in your project

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

This creates:

• .project-guide.yml - Configuration file
• docs/project-guide/ - Mode templates, artifact templates, and metadata
• docs/project-guide/go.md - Rendered LLM instructions (default mode)

The rendered go.md and .bak.* backup files are gitignored.

2. Tell your LLM to read the guide

Read docs/project-guide/go.md

The LLM follows the instructions, asks clarifying questions, and generates artifacts. Type go to advance through steps.

3. Switch modes as you progress

project-guide mode plan_concept      # Define problem & solution
project-guide mode plan_features     # Define requirements
project-guide mode plan_tech_spec    # Define architecture
project-guide mode plan_stories      # Break into stories
project-guide mode plan_phase        # Add a new phase to stories
project-guide mode code_velocity     # Implement stories fast
project-guide mode code_test_first   # TDD red-green-refactor
project-guide mode debug             # Debug with test-first approach
project-guide mode document_brand    # Brand descriptions
project-guide mode document_landing  # GitHub Pages + MkDocs docs
project-guide mode refactor_plan     # Plan a refactor
project-guide mode refactor_document # Document a refactor

Each mode re-renders docs/project-guide/go.md with focused instructions for that workflow.

4. List available modes

project-guide mode

Output:

Current mode: plan_concept

Available modes:
  -> default                   Getting started -- full project lifecycle overview
     plan_concept              Generate a high-level concept (problem and solution space)
     plan_features             Generate feature requirements (what the project does)
     plan_tech_spec            Generate a technical specification prompt (how it's built)
     plan_stories              Generate a user stories prompt
     plan_phase                Add a new phase to stories
     code_velocity             Generate code with velocity
     code_test_first           Generate code with a test-first approach
     debug                     Debug code with a test-first approach
     document_brand            Generate brand descriptions
     document_landing          Generate landing page and docs
     refactor_plan             Plan a refactor
     refactor_document         Document a refactor
     ...

5. Update files

pip install --upgrade project-guide
project-guide update

Overridden files are skipped. Modified files prompt for confirmation. Backups are always created before overwrites.

6. Customize a file (optional)

project-guide override templates/modes/debug-mode.md "Custom debugging for this project"

Command Reference

init

Initialize project-guide in the current directory.

project-guide init [OPTIONS]

Options:

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

Examples:

# Initialize with default settings
project-guide init

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

# Force reinitialize
project-guide init --force

mode

Set or show the active development mode.

project-guide mode [MODE_NAME]

Without argument: Lists current mode and all available modes.

With argument: Switches to the specified mode and re-renders go.md.

Examples:

# Show current mode and list all modes
project-guide mode

# Switch to velocity coding mode
project-guide mode code_velocity

# Switch to debugging mode
project-guide mode debug

status

Show status of all installed files and current mode. Output is compact and grouped into Mode, Guide, and Files sections with color.

project-guide status [OPTIONS]

Options:

• --verbose / -v - Show detailed file-level information

Output includes:

• Current package version and installed version
• Active mode
• Status of the rendered guide
• Status of each file (current, outdated, overridden, missing)
• Override reasons (in verbose mode)

update

Update files to the latest version. Uses SHA-256 content hash comparison to detect changes.

project-guide update [OPTIONS]

Options:

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

Examples:

# Update all files (skips overridden)
project-guide update

# Update specific files
project-guide update --files templates/modes/debug-mode.md

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

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

override

Mark a file as customized to prevent automatic updates.

project-guide override FILE_NAME REASON

Arguments:

• FILE_NAME - Name of the file (positional)
• REASON - Why this file is customized (positional)

Example:

project-guide override templates/modes/debug-mode.md "Custom debugging workflow with project-specific tools"

unoverride

Remove override status from a file.

project-guide unoverride FILE_NAME

Arguments:

• FILE_NAME - Name of the file (positional)

Example:

project-guide unoverride templates/modes/debug-mode.md

overrides

List all overridden files.

project-guide overrides

Output:

Overridden files:

templates/modes/debug-mode.md
  Reason: Custom debugging workflow with project-specific tools
  Since: v2.0.0
  Last updated: 2026-03-03

purge

Remove all project-guide files from the current project.

project-guide purge [OPTIONS]

Options:

• --force - Skip confirmation prompt

Examples:

# Purge with confirmation prompt
project-guide purge

# Purge without confirmation
project-guide purge --force

What gets removed:

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

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

Configuration

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

version: "2.0"
installed_version: "2.0.15"
target_dir: "docs/project-guide"
metadata_file: ".metadata.yml"
current_mode: "code_velocity"
overrides:
  templates/modes/debug-mode.md:
    reason: "Custom debugging workflow for this project"
    locked_version: "2.0.0"
    last_updated: "2026-04-07"

Fields:

• version - Config file format version
• installed_version - Version of files currently installed
• target_dir - Where templates are stored
• metadata_file - Hidden metadata file inside target dir (default: .metadata.yml)
• current_mode - Active development mode
• overrides - Map of customized files with metadata

Available Modes

Planning Modes

Mode	Command	Output
Concept	project-guide mode plan_concept	docs/specs/concept.md
Features	project-guide mode plan_features	docs/specs/features.md
Tech Spec	project-guide mode plan_tech_spec	docs/specs/tech-spec.md
Stories	project-guide mode plan_stories	docs/specs/stories.md
Phase	project-guide mode plan_phase	New phase added to stories

Coding Modes

Mode	Command	Workflow
Velocity	project-guide mode code_velocity	Direct commits, fast iteration
Test-First	project-guide mode code_test_first	TDD red-green-refactor cycle
Debug	project-guide mode debug	Test-driven debugging

Documentation Modes

Mode	Command	Output
Branding	project-guide mode document_brand	docs/specs/brand-descriptions.md
Landing Page	project-guide mode document_landing	GitHub Pages + MkDocs docs

Refactoring Modes

Mode	Command	Workflow
Plan	project-guide mode refactor_plan	Plan a refactor
Document	project-guide mode refactor_document	Document a refactor

Troubleshooting

"Configuration file not found"

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

Solution:

project-guide init

"File already exists"

Problem: Trying to initialize when files already exist.

Solution:

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

# Or manually remove existing files
rm -rf docs/project-guide .project-guide.yml
project-guide 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: Files show as current but you expect updates.

Solution:

# Check if file is overridden
project-guide overrides

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

Development

Setup

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

# 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_guide --cov-report=term-missing

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

Code Quality

# Linting
ruff check project_guide/ tests/

# Type checking
mypy project_guide/

# Format code
ruff format project_guide/ 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 switch -c feature/your-feature-name

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

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

• Getting Started - Installation and quick start
• User Guide - Commands, workflows, and override management
• Developer Guide - Contributing and development setup

Support

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

---

Made for LLM-assisted development workflows