config-template.yml

# Product Forge Configuration
# Copy this file to .product-forge/config.yml in your project root
#
# All settings are optional — Product Forge will ask for missing values at runtime.
# See docs/config.md for full documentation.

# ─── Project Identity ──────────────────────────────────────────────────────────

# Human-readable project name (used in research prompts and report headers)
project_name: "My Project"

# Brief tech stack description (helps research agents find relevant libraries)
# Examples:
#   "Node.js + Express + Postgres"
#   "Next.js + Supabase"
#   "Django + React + Celery"
#   "Go + gRPC + CockroachDB"
#   "Ruby on Rails + Sidekiq"
#   "Spring Boot + Kafka + MySQL"
#   ".NET 8 + SQL Server + Azure"
project_tech_stack: ""

# Domain/industry (helps competitor and UX research focus)
# Examples:
#   "B2B SaaS productivity tool"
#   "consumer mobile fitness app"
#   "e-commerce marketplace"
#   "developer tooling / CLI"
#   "enterprise workflow automation"
#   "content platform / social"
project_domain: ""

# ─── Paths ─────────────────────────────────────────────────────────────────────

# Single-root project (backwards-compatible with pre-v1.5 configs).
# Use this if your project has ONE codebase at one path. Leave `codebase`
# block below unset; keep `codebase_path` only.
codebase_path: "."

# Monorepo mode (v1.5+). When `codebase` is set, it takes precedence over
# `codebase_path` and every command becomes workspace-aware. Features
# declare which workspace(s) they touch via `scope.paths` on .forge-status.yml.
#
# `paths` maps short workspace names (used in tasks.md `Paths:` lines and
# in portfolio reports) to relative directories under `root`.
#
# `workspace_type` lets test-plan / test-run / implement pick the correct
# runner. Supported: pnpm | yarn | npm | turbo | nx | rush | lerna | none.
# Set to "none" for plain multi-path layouts without a workspace manager.
#
# codebase:
#   root: "."
#   workspace_type: "pnpm"
#   paths:
#     backend:  "apps/api"
#     frontend: "apps/web"
#     shared:   "packages/shared"
#     mobile:   "apps/mobile"

# Directory where Product Forge feature artifacts are stored
# Avoid changing this after features have been created
features_dir: "features"

# Feature-ROOT placement strategy. Controls ONLY where each feature directory
# sits under features_dir; the internal artifact tree (research/, product-spec/,
# contracts/, .forge-status.yml, …) is invariant across every strategy.
# Options:
#   "flat"          — (default) immediate child: features/<slug>/
#   "domain-nested" — one grouping level: features/<domain>/<slug>/
#   "ddd"           — bounded-context, registry-backed (features/domains.yml): features/<context>/<slug>/
#   "workspace"     — monorepo workspace (scope.primary): features/<workspace>/<slug>/
# All four are active and selectable. `workspace` requires monorepo mode (a
# `codebase.paths` block). An absent key resolves to "flat" (byte-for-byte
# today's layout — no disk change).
# Avoid changing this after features have been created; relocate with `git mv`
# (the internal tree is self-path-free and moves intact).
storage_strategy: "flat"

# ─── SpecKit Integration ───────────────────────────────────────────────────────

# Default SpecKit mode for Phase 4 bridge
# Options:
#   "ask"      — always ask the user (default, recommended)
#   "classic"  — always use plan → tasks → implement
#   "v-model"  — always use full V-Model traceability
default_speckit_mode: "ask"

# Path to the project architecture constitution file (used in Phase 5 compliance check)
# The constitution defines mandatory patterns: resilience, EDA rules, code quality, etc.
# Leave empty to use the SpecKit default: .specify/memory/constitution.md
# constitution_path: ".specify/memory/constitution.md"

# ─── Research Defaults ─────────────────────────────────────────────────────────

# Default competitors to always include in competitor analysis
# Leave empty to let the agent find them automatically
default_competitors: []
  # - "Competitor One"
  # - "Competitor Two"

# Whether to run tech stack research by default (can always be overridden per feature)
default_tech_research: false

# Whether to run metrics/ROI analysis by default
default_metrics_research: false

# ─── Product Spec Defaults ─────────────────────────────────────────────────────

# Default wireframe detail level
# Options: "text" | "basic-html" | "detailed-html"
default_wireframe_detail: "basic-html"

# Default mockup style when creating mockups
# Options: "none" | "generic" | "project-styled"
default_mockup_style: "project-styled"

# ─── Lifecycle Behavior ────────────────────────────────────────────────────────

# How often to run progressive verification during implementation (Phase 6)
# Value = number of completed tasks between checkpoints. Set to 0 to disable.
progressive_verify_interval: 3

# Whether to run automatic quick sync-verify between phase transitions
# When true, the forge orchestrator checks relevant artifact layers at each transition
auto_sync_between_phases: true

# Whether Phase 9 (Release Readiness) is required or optional
# Options: "required" | "optional" | "skip"
release_readiness: "optional"

# ─── Feature Mode (v1.5.0) ─────────────────────────────────────────────────────

# Default phase map selected when a new feature is created.
# Options:
#   "express"  — 4-phase combined pass for trivial changes (product-spec minimal →
#                plan inline → implement → verify); first-class mode, escalatable
#                to lite/standard. See docs/policy.md §4.1.
#   "lite"     — 5 phases: problem-discovery (opt) → product-spec → plan → implement → verify
#   "standard" — full standard lifecycle: 8 always-on core phases + 12
#                optional/conditional = 20 phase slots (recommended for most features)
#   "v-model"  — standard bookends + V1–V13 delegated to the external
#                V-Model Extension Pack (leocamello/spec-kit-v-model ≥0.5.0).
#                REQUIRES that plugin to be installed separately:
#                  specify extension add v-model \
#                    --from https://github.com/leocamello/spec-kit-v-model/archive/refs/tags/v0.5.0.zip
#                Without it, selecting v-model mode aborts with the install
#                command — there is NO silent fallback to standard.
# See docs/policy.md §4 for escalation and deselection rules, and
# docs/v-model-integration.md for the full v-model orchestration contract.
default_feature_mode: "standard"

# Flow mode controls how strictly phases are sequenced (v1.6.0).
# Options:
#   "gated"  — classic: one phase at a time, human gate after each (default)
#   "fluid"  — "actions, not phases": any phase runnable on demand, dependencies
#              shown as enablers (what's possible) rather than hard gates.
#              sync-verify still guards drift. See docs/runtime.md.
flow_mode: "gated"

# Express track (v1.6.0) — a track below `lite` for trivial changes:
# a single combined spec→plan→implement→verify pass with no separate
# research / revalidate / bridge. The orchestrator's intake step (docs/policy.md
# §4) recommends a track from the change description; this sets the default it
# offers when nothing else is specified. Options: "express" | "lite" | "standard".
default_track_hint: "standard"

# ─── E2E Testing (v1.6.0) ──────────────────────────────────────────────────────

# Default end-to-end test runner. Product Forge generates E2E specs directly from
# the structured journey schema (product-spec/journeys/journeys.yml) and executes
# them with this runner. playwright-cli is the first-class, default implementation.
# Options: "playwright-cli" | "none"
e2e_runner: "playwright-cli"

# Accessibility gate (v1.6, W5-B2). Automated WCAG-AA floor woven into the
# Phase 8A generated journey specs and run by Phase 8B (test-run §4.7) via
# `@axe-core/playwright`. This is a deterministic minimum bar, NOT a substitute
# for manual a11y review.
# Options:
#   "axe"  — generate one WCAG-AA axe-core check per JRN (default for any
#            feature with browser journeys; a no-op for non-browser journeys,
#            which test-run §4.7 already skips).
#   "none" — do not generate the automated a11y floor.
a11y_gate: "axe"

# ─── Telemetry Providers (v1.6.0) ──────────────────────────────────────────────

# Real telemetry backends used by retrospective, monitoring-setup, and
# experiment-design (via MCP when available). Leave a provider unset to skip it.
# product_analytics: posthog | amplitude | none
# error_tracking:    sentry | none
# dashboards:        posthog | sentry | newrelic | none
# `posthog` and `sentry` are wired via their MCP servers (no extra setup beyond
# the MCP). `newrelic` is NOT MCP-wired — it requires the external
# newrelic-dashboard-builder skill. Default is "none" (no dashboards built).
telemetry:
  product_analytics: "none"
  error_tracking: "none"
  dashboards: "none"

# ─── Design System (v1.6.0) ────────────────────────────────────────────────────

# Product Forge keeps the design system in CODE (component library + tokens) as the
# single source of truth and HARVESTS a read-only manifest from it (it never
# duplicates the design system). Configure where to find it; leave empty to
# auto-detect (Storybook, Tailwind config, component dir, token files).
# design_system:
#   components_path: "packages/ui/src"      # component library root
#   tokens_path: "packages/ui/tokens"       # design tokens (json/css/ts)
#   storybook: true                          # harvest from Storybook if present

# ─── Skip-Reason Policy (v1.5.0) ───────────────────────────────────────────────

# When true, skipping an optional phase requires a free-text reason that is
# persisted in gates[].skip_reason and phases.<name>.skip_reason.
# See docs/policy.md §3.
require_skip_reason: true

# ─── Optional-Phase Governance ───────────────────────────────────────────────
#
# These force individual optional phases to run instead of being skippable.
# All default false (the phase stays optional and may be skipped per §3).
# See docs/policy.md §6.
#
#   require_pre_impl_review — force the pre-implementation review phase.
#   require_code_review     — force the code-review phase.
#   require_testing         — force the test-plan / test-run phases.
require_pre_impl_review: false
require_code_review: false
require_testing: false

# ─── Learning Loop → Hermes Skills (v1.7) ──────────────────────────────────────
#
# The retrospective always appends lessons to .product-forge/lessons.md (flat,
# per-project). When running inside Hermes (or any host exposing skill_manage),
# a recurring lesson can additionally be PROMOTED into a reusable Hermes skill so
# the pattern carries across projects and sessions (and is cheaper on every
# subsequent run). See docs/lessons-format.md §9.
#
#   promote_to_skills — master switch. Default false (lessons.md only).
#   min_recurrence    — promote a lesson's pattern only after it has recurred in
#                       at least this many DISTINCT features (avoids one-off
#                       trivia becoming a skill). Default 2.
#   require_confirmation — never write a skill without the user confirming the
#                       drafted SKILL.md first. Default true (recommended).
#   skill_category    — optional category passed to skill_manage (groups the
#                       generated skills, e.g. "product-forge-lessons").
learning:
  promote_to_skills: false
  min_recurrence: 2
  require_confirmation: true
  skill_category: "product-forge-lessons"

# ─── Cross-Model Review (v1.7) ─────────────────────────────────────────────────
#
# Opt-in cross-model review for `code-review --cross-model` (P1-B): export the
# consolidated gate-review.md + git diff as a portable package, have a DIFFERENT
# model review it, and ingest its findings back into the F-NNN namespace. A model
# reviewing its own family rationalizes; a different model brings different priors.
# See commands/code-review.md Step 2.5.
#
#   cross_model — default reviewer id used when --cross-model is passed without an
#                 explicit id. Any CLI-capable model/session: codex | gemini |
#                 claude | hermes | <local-model>. Empty = must pass the id on the
#                 command line. The reviewer runs OUT-OF-BAND; PF never silently
#                 invokes another paid model.
review:
  cross_model: ""

# ─── Sync-Verify Drift Budget (v1.5.0) ─────────────────────────────────────────

# Drift budget controls how sync-verify categorizes and reports differences.
# Values are upper bounds per feature: exceeding cosmetic→warning, structural→gate.
sync_verify:
  drift_budget:
    cosmetic: 20          # whitespace, ordering, date churn — tolerable
    structural: 0         # field meaning, contract shape — always gated
  # Whitelist of drift categories that sync-verify may auto-resolve.
  # Only "cosmetic" is supported; opt-in by setting to true.
  auto_resolve:
    cosmetic: false
  # Executable contract differ (v1.6, W5-B4). Consumed by sync-verify Layer 8 /
  # verify-full Layer 9. When set to "oasdiff" AND a regen source is configured
  # AND `oasdiff` is on PATH, FE↔BE OpenAPI drift becomes a deterministic tool
  # exit code instead of an LLM prose read. Otherwise the prose check is used.
  # (OpenAPI only — asyncapi.yaml/events stay on the prose path.)
  contract_differ: none          # none (default) | oasdiff
  contract_regen:                # only used when contract_differ != none
    cmd: ""                      # command that emits the code-derived OpenAPI spec to stdout
    out: ".forge-tmp/openapi.from-code.yaml"   # temp path the cmd writes to (NEVER inside contracts/)

# ─── Supply Chain (release-readiness) ──────────────────────────────────────────

# License gate for the dependency-license audit run by release-readiness (Phase 9).
# `license_allowlist` is the set of SPDX license IDs considered acceptable; a
# dependency whose license is outside this list is flagged as a release blocker.
# Leave the list as-is to use the permissive default, or tailor it to your
# organization's policy.
supply_chain:
  license_allowlist:
    - "MIT"
    - "Apache-2.0"
    - "BSD-2-Clause"
    - "BSD-3-Clause"
    - "ISC"
    - "0BSD"
    - "Unlicense"

# ─── Localization (i18n-harvest) ───────────────────────────────────────────────

# Locales the i18n-harvest phase should produce/verify translation coverage for.
# Leave empty to auto-detect from the existing i18n folder structure (or skip
# i18n entirely for English-only projects).
# Example: ["en", "es", "de", "fr"]
supported_locales: []

# ─── Advanced ──────────────────────────────────────────────────────────────────

# Maximum token budget target per generated document (approximate)
# Larger features will auto-decompose into multiple files
# Recommended: 3000-6000 tokens per file
max_tokens_per_doc: 4000

# Language for all generated documents
# Examples: "en", "ru", "de"
output_language: "en"