Skip to content

Feature Flags

Feature flags control how mcp-guide behaves, what features are enabled, and how content is delivered. You can set flags globally (affecting all projects) or per-project (for specific contexts).

Viewing Flags

Use the guide://_flags commands to view and manage flags:

guide://_flags                           # Show all flags with available commands
guide://_flags/list                      # List all flags (project and feature)
guide://_flags/project/list              # List project-specific flags
guide://_flags/feature/list              # List feature flags (global)

See: Commands for complete flag command reference.

How Flags Work

Flags can be set at two levels:

Project flags - Apply to a specific project:

guide://_flags/project/set/workflow
guide://_flags/project/set/workflow/false
guide://_flags/project/set/content-style?value=plain
guide://_flags/project/remove/workflow      # Remove override, use feature flag value

Feature flags - Apply across all projects by default:

guide://_flags/feature/set/workflow
guide://_flags/feature/set/content-format?value=mime
guide://_flags/feature/remove/autoupdate    # Remove flag entirely

When resolving what value to use, project flags take precedence over feature flags, which take precedence over defaults.

Managing Flags

Use the flag commands to get, set, and remove flags:

# Get flag values
guide://_flags/project/get/workflow
guide://_flags/feature/get/autoupdate

# Set flag values
guide://_flags/project/set/workflow/true
guide://_flags/feature/set/content-format?value=mime

# Remove flags
guide://_flags/project/remove/workflow      # Revert to feature flag value
guide://_flags/feature/remove/autoupdate    # Remove flag entirely

Core Feature Flags

Flag Description Type Default
workflow Enables workflow phase tracking (discussion, planning, implementation, check, review). Can be true (all phases), false (disabled), or list of phase names. boolean or list[string] false
workflow-file Path to workflow tracking file. Supports variables: {project-name}, {project-key}, {project-hash}. string .guide.yaml
workflow-consent Controls phase transition consent requirements. Can be true (default consent rules), false (no consent required), or custom rules specifying which phases require consent to enter or exit. boolean or dict true
openspec Enables OpenSpec integration for structured change management. Adds OpenSpec-specific commands and workflow instructions. boolean false
startup-instruction Content expression to load when project session starts. Queued as high-priority instruction for immediate agent context. Supports any valid content expression (collection, category, or pattern). string (not set)
content-style Controls markdown formatting in template output. plain = strips all formatting, headings = renders heading markers only, full = renders all markdown. string plain
content-format Controls content MIME type. text = plain text, mime = MIME multipart format. string text
path-documents Directory path for workflow tracking documents (plans, checklists, summaries). Supports both relative (.todo/) and absolute (~/.goose/projects/knowledge/) paths. Auto-added to allowed_write_paths. string .todo/
path-export Directory path for exported knowledge content. Agent-specific defaults: Goose uses ~/.goose/projects/{project-hash}/knowledge/, others use .kiro/knowledge/. Auto-added to allowed_write_paths. string (agent-specific)
allow-client-info Enables collection of client environment information (OS, hostname, user, git remotes). Privacy-sensitive. boolean false
autoupdate Enables automatic update prompting at startup when new documentation versions are available. Prompts agent to run the update_documents tool. Global only (cannot be set per-project). boolean false
guide-development Enables development features for mcp-guide itself. boolean false
format-resource Controls how template {{#resource}} references are rendered. When false or unset (default), renders as guide:// URIs. When true, renders as get_content(...) tool calls. boolean false
format-command Controls how template command references are rendered. When false or unset (default), renders as guide://_command URIs. When true, renders as prompt-style command references using the current prompt prefix and prompt name. boolean false

Notes:

  • workflow set to true enables all 5 default phases: discussion, planning, implementation, check, review
  • workflow can be a list to enable specific phases: ["discussion", "planning", "implementation"] (discussion and implementation are mandatory)
  • workflow-consent set to true applies default consent: implementation requires entry consent, review requires exit consent
  • workflow-consent can be a dict for custom consent: {"planning": ["entry"], "implementation": ["entry", "exit"]}
  • path-documents and path-export accept both relative paths (.todo/) and absolute paths (/tmp/knowledge/, ~/.goose/knowledge/)
  • Path flags automatically add trailing slash if missing and normalize backslashes to forward slashes
  • Path flags are validated for security: path traversal (../, ..\\) is blocked
  • For absolute paths, system directories (/etc, /sys, /proc) are blocked
  • Resolved path flag values are automatically added to allowed_write_paths for security policy compliance

Using Flags in Templates

Conditional Content

Use requires-* in frontmatter:

---
requires-workflow: true
---

# Workflow Instructions

Follow the {{workflow.phase}} phase guidelines...

Document is included only if workflow flag is set and not false.

Next Steps