@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/references/planning-config.md

@@ -1,200 +1,340 @@
-<planning_config>
-
-Configuration options for `.planning/` directory behavior.
-
-<config_schema>
-```json
-"planning": {
-  "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "branching_strategy": "none",
-  "phase_branch_template": "ez/phase-{phase}-{slug}",
-  "milestone_branch_template": "ez/{milestone}-{slug}"
-}
-```
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `commit_docs` | `true` | Whether to commit planning artifacts to git |
-| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"ez/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"ez/{milestone}-{slug}"` | Branch template for milestone strategy |
-</config_schema>
-
-<commit_docs_behavior>
-
-**When `commit_docs: true` (default):**
-- Planning files committed normally
-- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
-- Full history of planning decisions preserved
-
-**When `commit_docs: false`:**
-- Skip all `git add`/`git commit` for `.planning/` files
-- User must add `.planning/` to `.gitignore`
-- Useful for: OSS contributions, client projects, keeping planning private
-
-**Using ez-tools.cjs (preferred):**
-
-```bash
-# Commit with automatic commit_docs + gitignore checks:
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: update state" --files .planning/STATE.md
-
-# Load config via state load (returns JSON):
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" state load)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# commit_docs is available in the JSON output
-
-# Or use init commands which include commit_docs:
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init execute-phase "1")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# commit_docs is included in all init command outputs
-```
-
-**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
-
-**Commit via CLI (handles checks automatically):**
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: update state" --files .planning/STATE.md
-```
-
-The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
-
-</commit_docs_behavior>
-
-<search_behavior>
-
-**When `search_gitignored: false` (default):**
-- Standard rg behavior (respects .gitignore)
-- Direct path searches work: `rg "pattern" .planning/` finds files
-- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
-
-**When `search_gitignored: true`:**
-- Add `--no-ignore` to broad rg searches that should include `.planning/`
-- Only needed when searching entire repo and expecting `.planning/` matches
-
-**Note:** Most EZ Agents operations use direct file reads or explicit paths, which work regardless of gitignore status.
-
-</search_behavior>
-
-<setup_uncommitted_mode>
-
-To use uncommitted mode:
-
-1. **Set config:**
-   ```json
-   "planning": {
-     "commit_docs": false,
-     "search_gitignored": true
-   }
-   ```
-
-2. **Add to .gitignore:**
-   ```
-   .planning/
-   ```
-
-3. **Existing tracked files:** If `.planning/` was previously tracked:
-   ```bash
-   git rm -r --cached .planning/
-   git commit -m "chore: stop tracking planning docs"
-   ```
-
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
-
-</setup_uncommitted_mode>
-
-<branching_strategy_behavior>
-
-**Branching Strategies:**
-
-| Strategy | When branch created | Branch scope | Merge point |
-|----------|---------------------|--------------|-------------|
-| `none` | Never | N/A | N/A |
-| `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
-
-**When `git.branching_strategy: "none"` (default):**
-- All work commits to current branch
-- Standard EZ Agents behavior
-
-**When `git.branching_strategy: "phase"`:**
-- `execute-phase` creates/switches to a branch before execution
-- Branch name from `phase_branch_template` (e.g., `ez/phase-03-authentication`)
-- All plan commits go to that branch
-- User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
-
-**When `git.branching_strategy: "milestone"`:**
-- First `execute-phase` of milestone creates the milestone branch
-- Branch name from `milestone_branch_template` (e.g., `ez/v1.0-mvp`)
-- All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
-
-**Template variables:**
-
-| Variable | Available in | Description |
-|----------|--------------|-------------|
-| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
-| `{slug}` | Both | Lowercase, hyphenated name |
-| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
-
-**Checking the config:**
-
-Use `init execute-phase` which returns all config as JSON:
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init execute-phase "1")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
-```
-
-Or use `state load` for the config values:
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" state load)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
-```
-
-**Branch creation:**
-
-```bash
-# For phase strategy
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-
-# For milestone strategy
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-```
-
-**Merge options at complete-milestone:**
-
-| Option | Git command | Result |
-|--------|-------------|--------|
-| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
-| Merge with history | `git merge --no-ff` | Preserves all individual commits |
-| Delete without merging | `git branch -D` | Discard branch work |
-| Keep branches | (none) | Manual handling later |
-
-Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
-
-**Use cases:**
-
-| Strategy | Best for |
-|----------|----------|
-| `none` | Solo development, simple projects |
-| `phase` | Code review per phase, granular rollback, team collaboration |
-| `milestone` | Release branches, staging environments, PR per version |
-
-</branching_strategy_behavior>
-
-</planning_config>
+<planning_config>
+
+Configuration options for `.planning/` directory behavior.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "ez/phase-{phase}-{slug}",
+  "milestone_branch_template": "ez/{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.phase_branch_template` | `"ez/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `git.milestone_branch_template` | `"ez/{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for `.planning/` files
+- User must add `.planning/` to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Using ez-tools.cjs (preferred):**
+
+```bash
+# Commit with automatic commit_docs + gitignore checks:
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+
+# Load config via state load (returns JSON):
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is available in the JSON output
+
+# Or use init commands which include commit_docs:
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# commit_docs is included in all init command outputs
+```
+
+**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
+
+**Commit via CLI (handles checks automatically):**
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: update state" --files .planning/STATE.md
+```
+
+The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" .planning/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include `.planning/`
+- Only needed when searching entire repo and expecting `.planning/` matches
+
+**Note:** Most EZ Agents operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .planning/
+   ```
+
+3. **Existing tracked files:** If `.planning/` was previously tracked:
+   ```bash
+   git rm -r --cached .planning/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `phase` | At `execute-phase` start | Single phase | User merges after phase |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- Standard EZ Agents behavior
+
+**When `git.branching_strategy: "phase"`:**
+- `execute-phase` creates/switches to a branch before execution
+- Branch name from `phase_branch_template` (e.g., `ez/phase-03-authentication`)
+- All plan commits go to that branch
+- User merges branches manually after phase completion
+- `complete-milestone` offers to merge all phase branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `execute-phase` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `ez/v1.0-mvp`)
+- All phases in milestone commit to same branch
+- `complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+Use `init execute-phase` which returns all config as JSON:
+```bash
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init execute-phase "1")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
+```
+
+Or use `state load` for the config values:
+```bash
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" state load)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+```
+
+**Branch creation:**
+
+```bash
+# For phase strategy
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `phase` | Code review per phase, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+
+<smart_orchestration_config>
+
+**`smart_orchestration` block:**
+
+```json
+"smart_orchestration": {
+  "enabled": true,
+  "show_auto_prefix": true,
+  "auto_invoke": {
+    "preflight": ["progress", "execute-phase"],
+    "arch_review": ["execute-phase"],
+    "standup": []
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Master toggle for smart orchestration auto-invocations |
+| `show_auto_prefix` | `true` | Prefix auto-invoked agent output with `[AUTO]` label |
+| `auto_invoke.preflight` | `["progress", "execute-phase"]` | Commands that silently run health check before executing |
+| `auto_invoke.arch_review` | `["execute-phase"]` | Commands that auto-spawn tech lead review when `agent_discussion` enabled |
+| `auto_invoke.standup` | `[]` | Commands that auto-generate standup before running |
+
+**Disabling per-invocation:** Pass `--no-auto` flag to any command to skip smart orchestration for that run.
+
+</smart_orchestration_config>
+
+<agent_discussion_config>
+
+**`agent_discussion` block:**
+
+```json
+"agent_discussion": {
+  "enabled": false,
+  "pre_flight_observer": false,
+  "tech_lead_review": false,
+  "scrum_master_standup": false,
+  "cost_warning": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Master toggle for optional discussion agents |
+| `pre_flight_observer` | `false` | Spawn observer agent before execution to surface risks |
+| `tech_lead_review` | `false` | Auto-spawn tech lead review after `/ez:plan-phase` completes |
+| `scrum_master_standup` | `false` | Auto-generate standup report at session start |
+| `cost_warning` | `true` | Warn before spawning expensive agents (Opus-class) |
+
+**Enable via `/ez:settings`:** The settings workflow provides a guided UI for toggling these options. Avoid manual JSON edits.
+
+</agent_discussion_config>
+
+<sessions_config>
+
+**`sessions` block:**
+
+```json
+"sessions": {
+  "retention_policy": "keep_last_10",
+  "auto_compress_threshold": 50,
+  "chain_navigation_enabled": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `retention_policy` | `"keep_last_10"` | How many sessions to retain. Options: `"keep_all"`, `"keep_last_N"`, `"keep_days_N"` |
+| `auto_compress_threshold` | `50` | Compress session memory when token count exceeds this (in thousands) |
+| `chain_navigation_enabled` | `true` | Enable `--previous`/`--next`/`--chain` flags in `/ez:resume` |
+
+**Session files location:** `.planning/sessions/` — each session is a JSON file. Use `/ez:export-session` and `/ez:import-session` for cross-model handoffs.
+
+</sessions_config>
+
+<release_tiers_config>
+
+**`release.tiers` block:**
+
+```json
+"release": {
+  "tier": "mvp",
+  "tiers": {
+    "mvp": {
+      "coverage_threshold": 0,
+      "checklist_items": ["build_passes", "no_blockers"],
+      "git_strategy": "direct_to_main"
+    },
+    "medium": {
+      "coverage_threshold": 60,
+      "checklist_items": ["build_passes", "no_blockers", "tests_pass", "security_scan"],
+      "git_strategy": "pr_required"
+    },
+    "enterprise": {
+      "coverage_threshold": 80,
+      "checklist_items": ["build_passes", "no_blockers", "tests_pass", "security_scan", "coverage_gate", "changelog_updated", "rollback_plan"],
+      "git_strategy": "gitflow"
+    }
+  }
+}
+```
+
+| Tier | Coverage | Git Strategy | Checklist |
+|------|----------|--------------|-----------|
+| `mvp` | None | Direct to main | Build + no blockers |
+| `medium` | 60% | PR required | Build + tests + security scan |
+| `enterprise` | 80% | GitFlow (main + develop) | Full gates including rollback plan |
+
+**Hotfix behavior by tier:** MVP hotfixes merge directly; Medium requires PR; Enterprise merges to main AND syncs to develop. See `/ez:hotfix` documentation.
+
+**Set tier:** `node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set release.tier enterprise`
+
+</release_tiers_config>
+
+<package_manager_config>
+
+**`packageManager` block:**
+
+```json
+"packageManager": {
+  "default": "npm",
+  "autoDetect": true,
+  "respectLockfile": true
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default` | `"npm"` | Fallback package manager when auto-detection fails. Options: `"npm"`, `"yarn"`, `"pnpm"`, `"bun"` |
+| `autoDetect` | `true` | Detect package manager from lock file presence (`yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`) |
+| `respectLockfile` | `true` | Use `--frozen-lockfile` / `--ci` flags during install to prevent lock file mutations |
+
+**Auto-detection order:** `bun.lockb` → bun, `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm, fallback to `default`.
+
+**Set explicitly:** `node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set packageManager.default pnpm`
+
+</package_manager_config>
+
+</planning_config>

package/ez-agents/references/tier-strategy.md

@@ -0,0 +1,103 @@
+# Tier Strategy Reference
+
+Decision reference for git branching and release strategy per tier.
+
+## Quick Decision Matrix
+
+| Question | MVP | Medium | Enterprise |
+|----------|-----|--------|------------|
+| Git strategy | Trunk (tag main) | GitHub Flow | GitFlow |
+| Release branch | None | `release/vX.Y.Z` | `release/vX.Y.Z` from develop |
+| Hotfix to develop? | No | No | Yes |
+| PR required? | No | Yes (optional) | Yes (required) |
+| Coverage gate | 60% | 80% | 95% |
+| Checklist items | 6 | 18 | 30 |
+| MoSCoW scope | @must | @must + @should | All |
+| Rollback window | 30 min | 15 min | 5 min |
+
+## When to Use Each Tier
+
+**MVP** — You need to ship NOW
+- First public release
+- Early access / beta
+- Founder-driven sales demo
+- Internal tool, no SLA
+
+**Medium** — Real users, real consequences
+- General availability
+- Paying customers
+- Public-facing product
+- Team of 2-10 developers
+
+**Enterprise** — Compliance matters
+- Fortune 500 customers
+- Regulated industry (finance, health, legal)
+- SOC2 / GDPR required
+- 24/7 SLA commitment
+
+## Tier Promotion Path
+
+```
+Initial release → MVP v1.0.0
+  ↓ (enough users to need reliability)
+GA release → Medium v1.5.0
+  ↓ (enterprise deal signed)
+Enterprise → v2.0.0
+```
+
+Each promotion is additive — enterprise features are behind feature flags in the codebase from day one. Promotion just enables the flags and runs the stricter checklist.
+
+## Feature Flag Convention
+
+```javascript
+// In code: guard enterprise/medium features
+const ENABLE_SHOULD_FEATURES = process.env.ENABLE_SHOULD_FEATURES === 'true';
+const ENABLE_COULD_FEATURES = process.env.ENABLE_COULD_FEATURES === 'true';
+
+// MVP deploy: both = false (no overhead)
+// Medium deploy: SHOULD = true
+// Enterprise: SHOULD = true, COULD = true
+```
+
+## GitFlow (Enterprise) Branch Layout
+
+```
+main          ← production releases (tagged)
+develop       ← integration branch
+  feature/*   ← new features
+  fix/*        ← bug fixes
+release/vX.Y.Z ← release preparation (from develop → main)
+hotfix/*      ← emergency production fixes (from main → main + develop)
+```
+
+## GitHub Flow (Medium) Branch Layout
+
+```
+main          ← production (deploy on merge)
+  feature/*   ← all work branches
+  release/vX.Y.Z ← optional: release prep branch
+  hotfix/*    ← emergency fixes
+```
+
+## Trunk-Based (MVP) Branch Layout
+
+```
+main          ← production + development
+  task/*      ← short-lived feature branches (optional)
+              ← hotfix directly if needed
+```
+
+## Config Location
+
+Tier is stored in `.planning/config.json`:
+
+```json
+{
+  "release": {
+    "tier": "mvp",
+    "tiers": { ... }
+  }
+}
+```
+
+Update with: `node ez-tools.cjs tier-manager save-tier medium`