Skip to content

Configuration

project-guide uses a simple YAML configuration file to store project-specific settings.

Configuration File

The .project-guide.yml file is created automatically when you run project-guide init. It's stored in your project root.

Default Configuration

version: "2.0"
installed_version: "2.0.13"
target_dir: "docs/project-guide"
metadata_file: ".metadata.yml"
current_mode: "code_velocity"
overrides: {}

Configuration Fields

version

The configuration file format version. Currently "2.0".

installed_version

The version of the project-guide package that was used to install or last update the files. Used alongside content hashing to determine which files need updating.

target_dir

The directory where project-guide files are installed. Defaults to docs/project-guide.

You can customize this:

target_dir: "documentation/workflows"

metadata_file

The name of the metadata file used to track file state. Defaults to .metadata.yml.

current_mode

Tracks the active development mode. Changed via the project-guide mode command. project-guide includes 15 modes to match different development workflows.

overrides

A mapping of template paths to override metadata. Managed automatically by the override and unoverride commands.

Example:

overrides:
  templates/modes/debug-mode.md:
    reason: "Custom debugging workflow for our project"
    locked_version: "2.0.10"
    last_updated: "2026-03-15"

Override fields:

  • reason -- Why the override was created
  • locked_version -- The package version when the override was set
  • last_updated -- When the override was last modified

Zero Configuration

project-guide works out of the box with sensible defaults. You don't need to create or modify the configuration file manually unless you want to customize behavior.

Custom Target Directory

To use a custom target directory, specify it during initialization:

project-guide init --target-dir custom/path

Or modify the configuration file:

target_dir: "custom/path"

All commands will respect this setting.

Shell Completion

project-guide supports Tab completion for commands, flags, and mode names in bash, zsh, and fish. Completion is opt-in — add a one-line eval 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)"

Fish (~/.config/fish/completions/project-guide.fish): 

_PROJECT_GUIDE_COMPLETE=fish_source project-guide | source

After updating your shell config, restart your shell (or source the file). Then:

  • project-guide <TAB> completes command names (init, mode, status, etc.)
  • project-guide mode <TAB> completes mode names from the active project's .metadata.yml (dynamic — works with any custom modes)
  • project-guide --<TAB> completes flags

See Installation Options for more details.

Content Hash Sync

project-guide uses content hashing (not version numbers) to track file state. This enables smart updates that:

  • Detect exactly which files have changed upstream
  • Only update non-overridden files
  • Show which files are current, outdated, or overridden
  • Preserve your customizations

Manual Configuration

While not recommended, you can manually edit .project-guide.yml if needed. The file uses standard YAML syntax.

Warning

Manual edits should be done carefully. Invalid YAML will cause commands to fail.

Next Steps