project-guide 2.9.0

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 - Intuitive commands for every step of the workflow (init, mode, status, update, heal, override, purge, …)
• Auto-Heal - Every command silently repairs the install if drift is detected; prompts only when there's actual work to do, so a fresh clone is one project-guide <anything> away from being usable
• Shell Completion - Tab completion for commands, flags, and mode names (bash, zsh, fish)
• Well Tested - Comprehensive test coverage across CLI, rendering, and action modules
• 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

Shell Completion (Optional)

Enable Tab completion for commands, flags, and mode names. Add to your shell startup file:

# bash (~/.bashrc)
eval "$(_PROJECT_GUIDE_COMPLETE=bash_source project-guide)"

# zsh (~/.zshrc)
eval "$(_PROJECT_GUIDE_COMPLETE=zsh_source project-guide)"

See Installation Options for fish and full details.

Quick Start

1. Initialize in your project

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

This creates:

• .project-guide.yml - Configuration file (tracked)
• docs/project-guide/go.md - Rendered LLM instructions (unignored but intentionally untracked as of v2.8.0 — must be visible to IDE-integrated LLMs, but kept out of git so branch switches don't trip on it)
• docs/project-guide/ - Mode templates, artifact templates, and metadata (gitignored bundled data)

Everything under docs/project-guide/ is gitignored except go.md (which the LLM reads). The gitignored template tree is bundled static data — project-guide heal repopulates it on first invocation in a fresh clone, and the auto-hook makes that healing run silently before any other command.

Upgrading from v2.6.x – v2.7.x? Earlier project-guide versions left go.md tracked by historical accident. v2.8.0 flips the policy to untracked-by-default to eliminate branch-switch and merge friction. If heal warns that go.md is tracked, run once on your default branch:

git rm --cached docs/project-guide/go.md && git commit -m "untrack go.md per project-guide v2.8.0"

The file stays visible to your IDE LLM (the gitignore block hasn't changed), but it stops appearing in diffs and stops blocking git switch.

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 scaffold_project  # Scaffold license, manifest, README, CHANGELOG
project-guide mode code_direct       # 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 archive_stories   # Archive completed stories.md before next phase
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

Modes are displayed in category groups with availability markers:

• → — current mode (cyan background highlight)
• ✓ — all prerequisites met (green)
• ✗ — unmet prerequisites (yellow, dimmed)

On a real terminal, a numbered selection menu is shown so you can switch by entering a number. Under --no-input, CI=1, or piped input, only the listing is shown.

Current mode: code_direct

  Planning
  ✓  2  plan_concept               Generate a high-level concept
  ✓  3  plan_features              Generate feature requirements
  ...

  Coding
  →  6  code_direct                Generate code directly, test after
  ✓  7  code_test_first            Generate code with a test-first approach
  ...

Select mode [1-15, Enter to cancel]:

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. Safe to run unattended — re-running on an already-initialized project is a silent exit-0 no-op, and the --no-input flag (plus auto-detection) ensures CI runners and post-hooks never hang on stdin.

project-guide init [OPTIONS]

Options:

• --target-dir PATH - Directory for templates (default: docs/project-guide)
• --force - Overwrite existing configuration
• --no-input - Do not read from stdin; use defaults where sensible. Fail loudly if any prompt has no default. (Also auto-enabled by CI=1 or non-TTY stdin.)

Examples:

# Initialize with default settings
project-guide init

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

# Force reinitialize
project-guide init --force

Unattended / CI use

project-guide init is safe to invoke from any unattended context (CI runners, pyve post-hooks, subprocess pipelines, shell scripts). Four independent triggers all enable skip-input mode, in priority order — the first match wins:

# 1. Explicit flag
project-guide init --no-input

# 2. PROJECT_GUIDE_NO_INPUT env var (truthy: 1, true, yes, on — case-insensitive)
PROJECT_GUIDE_NO_INPUT=1 project-guide init

# 3. CI env var (auto-detected on most CI runners)
CI=1 project-guide init

# 4. Non-TTY stdin (piped input, subprocess, closed stdin)
echo "" | project-guide init

Idempotent re-run: Running project-guide init a second time on a project that is already initialized is a silent exit-0 no-op (with an informational message). Use --force to re-run the full install and overwrite existing files. This makes the command safe to call unconditionally from automated flows.

mode

Set or show the active development mode.

project-guide mode [MODE_NAME]

Without argument: Lists all modes grouped by category with ✓/✗/→ markers. Shows an interactive selection menu on TTY.

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

Options:

• --verbose / -v — Show unmet prerequisite file paths beneath each ✗ entry
• --no-input — Show listing only; skip interactive menu

Examples:

# Show grouped listing (+ interactive menu on TTY)
project-guide mode

# Show listing with prerequisite details
project-guide mode --verbose

# Switch to direct coding mode
project-guide mode code_direct

# Switch to debugging mode
project-guide mode debug

archive-stories

Archive docs/specs/stories.md and re-render a fresh one for the next phase. Wraps the deterministic archive action declared on the archive_stories mode.

project-guide archive-stories

This command:

1. Reads the latest version from the highest ### Story X.y: vN.N.N heading in stories.md.
2. Detects the highest ## Phase <Letter>: heading (informational only).
3. Extracts the ## Future section verbatim if present.
4. Moves stories.md to <spec_artifacts_path>/.archive/stories-vX.Y.Z.md.
5. Re-renders a fresh empty stories.md from the bundled artifact template, carrying the ## Future section over.

If any pre-check fails (no versioned stories, archive target already exists, source file missing) the command errors and leaves the workspace untouched. If the re-render fails after the move, the source is rolled back from .archive/.

This command is intended to be run by the LLM after the developer has approved the archive in project-guide mode archive_stories.

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 with prerequisites status
• Status of the rendered guide
• File counts (current, need updating, missing, overridden)
• Stories section: total/done/in-progress/planned counts + next story (when stories.md exists)
• Per-file detail and per-phase story breakdown (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
• --no-input - Non-interactive mode (reserved for future prompts)
• --quiet / -q - Suppress per-file progress output

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

heal

Repair the install: create missing template files and refresh stale ones to match the bundled package. Silent when there's nothing to do; prompts to apply when drift is detected.

project-guide heal [OPTIONS]

Options:

• --no-input - Auto-yes the [Y/n] prompt and emit a one-line stderr notice when writes occur (also auto-enabled by CI=1, PROJECT_GUIDE_NO_INPUT=1, or non-TTY stdin)

When to use it:

• After cloning a repo that has project-guide init'd output but the template tree is gitignored — heal repopulates it.
• After accidentally editing or deleting a bundled template file and wanting to restore the canonical version.
• Whenever you're not sure whether the install is up-to-date with the package version.

Auto-hook: every project-guide invocation (including --help and --version) calls heal first via a group-level hook, so the fresh-clone case usually resolves itself silently the first time you run any command. The hook is silent in the steady state and prompts only when there's actual drift.

Tracked-go.md warning (v2.8.0+): if docs/project-guide/go.md is in your git index, heal emits a stderr warning with a copyable migration command. The current policy is untracked-by-default — go.md stays visible to IDE LLMs (because it's unignored) but is kept out of the index so branch switches don't trip on it. The warning is non-fatal; the consumer applies the migration on their own schedule.

Examples:

# Interactive: prompts on drift
project-guide heal

# Unattended (CI, scripts, embedding callers)
project-guide heal --no-input

git-push

Wrap gitbetter's git-push with a commit message auto-derived from the most-recently-completed-and-not-yet-committed story in docs/specs/stories.md. Optional: requires gitbetter on PATH.

project-guide git-push [BRANCH_NAME]

Arguments:

• BRANCH_NAME (optional) - Passed through to gitbetter for branch-aware push flows (e.g. switching to a feature branch and offering cleanup after merge)

Heading-to-message transformation:

### Story G.a: v1.2.3 New command `foo` with "Hello" [Done]
                                ↓
       G.a: v1.2.3 New command 'foo' with 'Hello'

Backticks and double quotes become single quotes; single quotes pass through; the colon after the story ID is preserved (it's the anchor for the already-committed check).

Hard errors (exit 1):

• No [Done] story in stories.md
• The last [Done] story is already committed — the wrapper does not second-guess; resolve manually with raw git-push
• Multiple [Done] stories are uncommitted — commit them one at a time with explicit messages via raw git-push
• git-push not on PATH — install gitbetter: brew install pointmatic/tap/gitbetter

Examples:

# Most common: ready to commit the just-completed story to the current branch
project-guide git-push

# Feature-branch push (gitbetter switches to the branch first, offers cleanup after merge)
project-guide git-push feature/heal-command

Optional dependency. gitbetter is not required for any other project-guide command. Install it only if you want this wrapper:

brew install pointmatic/tap/gitbetter

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
• --no-input - Skip confirmation (also auto-enabled by CI=1 or non-TTY stdin)
• --quiet / -q - Suppress per-file progress output

Examples:

# Purge with confirmation prompt
project-guide purge

# Purge without confirmation
project-guide purge --force

# Unattended purge (CI / non-interactive)
project-guide purge --no-input --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.4.12"
target_dir: "docs/project-guide"
metadata_file: ".metadata.yml"
current_mode: "code_direct"
test_first: false
pyve_version: "1.2.3"          # null if pyve not installed

overrides:
  templates/modes/debug-mode.md:
    reason: "Custom debugging workflow for this project"
    locked_version: "2.0.0"
    last_updated: "2026-04-07"

metadata_overrides:             # optional — per-project mode field patches
  plan_stories:
    next_mode: scaffold_project

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
• test_first - Default coding approach (false = code_direct, true = code_test_first)
• pyve_version - Detected pyve version at init time; null if pyve not installed
• overrides - Map of file-level update locks with reason and timestamp
• metadata_overrides - Per-project patches for individual mode fields (next_mode, files_exist, info, description)

Available Modes

Project Planning Modes

One-time-per-project work — the four spec documents that establish the project before any code lands.

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 + docs/specs/project-essentials.md (initial population)
Stories	project-guide mode plan_stories	docs/specs/stories.md

Coding Modes

Mode	Command	Workflow
Direct	project-guide mode code_direct	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

Release Planning Modes

Repeated per release — phase planning (pre-1.0 vs. post-1.0), end-of-phase archive.

Mode	Command	Purpose
Phase	project-guide mode plan_phase	Pre-1.0 phase planning. New phase added to stories.md + append to project-essentials.md
Production Phase	project-guide mode plan_production_phase	Post-1.0 mandatory phase planning. Adds production-readiness checklist + breaking-change negotiation + explicit version-bump target
Archive Stories	project-guide mode archive_stories	Move completed stories.md to .archive/ and re-render an empty one for the next phase

Refactoring Modes

Mode	Command	Workflow
Plan	project-guide mode refactor_plan	Update concept/features/tech-spec for new capabilities or legacy migration; terminal step refreshes project-essentials.md (creates it for legacy projects)
Document	project-guide mode refactor_document	Update README, brand descriptions, landing page, and MkDocs config

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

Quick reference. See CONTRIBUTING.md for the full guide (PR process, release process, code-style commands, coverage expectations).

Setup

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

# Main environment: editable install.
pyve run pip install -e .

# Dev testenv: pytest, ruff, mypy.
pyve testenv init
pyve testenv install -r requirements-dev.txt

Running Tests

pyve test                                      # all tests
pyve test tests/test_cli.py                    # one file
pyve test --cov=project_guide --cov-report=term-missing

Code Quality

pyve testenv run ruff check project_guide tests
pyve testenv run ruff format project_guide tests
pyve testenv run mypy project_guide

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! See CONTRIBUTING.md for the full PR process. Quick summary:

1. Fork and branch off main.
2. Test locally: pyve test and pyve testenv run ruff check project_guide tests must pass.
3. PR against pointmatic/project-guide:main with a description that explains the why.
4. CI must be green; a maintainer will review.

For non-trivial changes, scope the work via a story in docs/specs/stories.md before opening the PR — see CONTRIBUTING.md for the recommended workflow.

Security

To report a vulnerability, do not file a public GitHub issue. Use GitHub Security Advisories for a private report — see SECURITY.md for the supported- versions policy, response expectations, and the threat model.

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