forgedock 1.0.1 → 1.0.2

package/commands/geo-audit.md

@@ -12,14 +12,81 @@ You are the GEO (Generative Engine Optimization) auditor. Pull AI referral data
 
 ---
 
+## Phase 0: Load Config
+
+Read `forge.yaml` from the current directory (or the path passed as `$ARGUMENTS`). Gate the entire command on the `services.analytics` section existing.
+
+```bash
+# Verify forge.yaml exists and analytics is configured
+GEO_CONFIG=$(python3 - <<'PYEOF'
+import yaml, sys, os
+
+config_path = os.environ.get('FORGE_CONFIG', 'forge.yaml')
+try:
+    cfg = yaml.safe_load(open(config_path))
+except FileNotFoundError:
+    print('ERROR: forge.yaml not found. Run `cp forge.yaml.example forge.yaml` and configure your project.')
+    sys.exit(1)
+
+svc = cfg.get('services', {})
+analytics = svc.get('analytics', {})
+if not analytics:
+    print('ERROR: forge.yaml missing services.analytics section — geo-audit requires analytics to be configured.')
+    print('Add services.analytics.umami and/or services.analytics.clarity to forge.yaml.')
+    sys.exit(1)
+
+paths = cfg.get('paths', {})
+proj = cfg.get('project', {})
+creds = paths.get('credentials', {})
+creds_file = creds.get('file', '') if isinstance(creds, dict) else ''
+
+domain = svc.get('domain', '')
+if not domain:
+    print('ERROR: forge.yaml missing services.domain — required for page compliance checks.')
+    sys.exit(1)
+
+umami = analytics.get('umami', {})
+clarity = analytics.get('clarity', {})
+owner = proj.get('owner', '')
+repo = proj.get('repo', '')
+
+print(domain)
+print('https://' + domain)
+print(umami.get('website_id', ''))
+print(umami.get('url', ''))
+print(clarity.get('project_id', ''))
+print(creds_file)
+print((owner + '/' + repo) if owner and repo else '')
+PYEOF
+)
+
+if echo "$GEO_CONFIG" | grep -q '^ERROR:'; then
+    echo "$GEO_CONFIG"
+    exit 1
+fi
+
+# Assign config variables
+DOMAIN=$(echo "$GEO_CONFIG" | sed -n '1p')
+SITE_URL=$(echo "$GEO_CONFIG" | sed -n '2p')
+UMAMI_WEBSITE_ID=$(echo "$GEO_CONFIG" | sed -n '3p')
+UMAMI_API=$(echo "$GEO_CONFIG" | sed -n '4p')
+CLARITY_PROJECT=$(echo "$GEO_CONFIG" | sed -n '5p')
+CREDENTIALS_FILE=$(echo "$GEO_CONFIG" | sed -n '6p')
+GH_REPO=$(echo "$GEO_CONFIG" | sed -n '7p')
+```
+
+---
+
 ## Constants
 
 ```
-DOMAIN = "alterlab.io"
-SITE_URL = "https://alterlab.io"
-UMAMI_WEBSITE_ID = "ccfb1cdd-5a05-4b41-8e61-48695b4ff6c0"
-UMAMI_API = "https://umami.alterlab.io"
-CLARITY_PROJECT = "v28wblv737"
+DOMAIN       = (from forge.yaml → services.domain)
+SITE_URL     = (from forge.yaml → "https://" + services.domain)
+UMAMI_WEBSITE_ID = (from forge.yaml → services.analytics.umami.website_id)
+UMAMI_API    = (from forge.yaml → services.analytics.umami.url)
+CLARITY_PROJECT  = (from forge.yaml → services.analytics.clarity.project_id)
+CREDENTIALS_FILE = (from forge.yaml → paths.credentials.file)
+GH_REPO      = (from forge.yaml → project.owner + "/" + project.repo)
 TODAY = (current date in YYYY-MM-DD)
 THIRTY_DAYS_AGO = (TODAY minus 30 days)
 
@@ -41,11 +108,11 @@ AI_REFERRERS = [
 
 ### 1A. Umami — AI Referrer Metrics
 
-Authenticate with Umami (credentials from `credentials.yaml`):
+Authenticate with Umami (credentials from credentials file set in forge.yaml):
 ```bash
-UMAMI_USER=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['umami']['username'])")
-UMAMI_PASS=$(python3 -c "import yaml; print(yaml.safe_load(open('/home/mrdubey/projects/ScraperAPI/credentials.yaml'))['umami']['password'])")
-UMAMI_TOKEN=$(curl -s -X POST "https://umami.alterlab.io/api/auth/login" \
+UMAMI_USER=$(python3 -c "import yaml; print(yaml.safe_load(open('$CREDENTIALS_FILE'))['umami']['username'])")
+UMAMI_PASS=$(python3 -c "import yaml; print(yaml.safe_load(open('$CREDENTIALS_FILE'))['umami']['password'])")
+UMAMI_TOKEN=$(curl -s -X POST "$UMAMI_API/api/auth/login" \
   -H "Content-Type: application/json" \
   -d "{\"username\":\"$UMAMI_USER\",\"password\":\"$UMAMI_PASS\"}" | jq -r '.token')
 ```
@@ -54,7 +121,7 @@ Then pull referrer metrics for the last 30 days:
 ```bash
 START_AT=$(date -d '30 days ago' +%s)000
 END_AT=$(date +%s)000
-curl -s "https://umami.alterlab.io/api/websites/ccfb1cdd-5a05-4b41-8e61-48695b4ff6c0/metrics?startAt=${START_AT}&endAt=${END_AT}&type=referrer" \
+curl -s "$UMAMI_API/api/websites/$UMAMI_WEBSITE_ID/metrics?startAt=${START_AT}&endAt=${END_AT}&type=referrer" \
   -H "Authorization: Bearer $UMAMI_TOKEN" | jq '.'
 ```
 
@@ -62,7 +129,7 @@ From the results, filter for AI_REFERRERS. Record each AI referrer's session cou
 
 Also pull landing page metrics to see WHERE AI traffic lands:
 ```bash
-curl -s "https://umami.alterlab.io/api/websites/ccfb1cdd-5a05-4b41-8e61-48695b4ff6c0/metrics?startAt=${START_AT}&endAt=${END_AT}&type=url" \
+curl -s "$UMAMI_API/api/websites/$UMAMI_WEBSITE_ID/metrics?startAt=${START_AT}&endAt=${END_AT}&type=url" \
   -H "Authorization: Bearer $UMAMI_TOKEN" | jq '.'
 ```
 
@@ -70,7 +137,7 @@ For previous period comparison (30-60 days ago):
 ```bash
 PREV_START=$(date -d '60 days ago' +%s)000
 PREV_END=$(date -d '30 days ago' +%s)000
-curl -s "https://umami.alterlab.io/api/websites/ccfb1cdd-5a05-4b41-8e61-48695b4ff6c0/metrics?startAt=${PREV_START}&endAt=${PREV_END}&type=referrer" \
+curl -s "$UMAMI_API/api/websites/$UMAMI_WEBSITE_ID/metrics?startAt=${PREV_START}&endAt=${PREV_END}&type=referrer" \
   -H "Authorization: Bearer $UMAMI_TOKEN" | jq '.'
 ```
 
@@ -96,17 +163,17 @@ Cross-reference Clarity referrer data with Umami to validate numbers.
 
 Get the sitemap to find all public pages:
 ```bash
-curl -s "https://alterlab.io/sitemap.xml" | grep -oP '<loc>\K[^<]+' | sort
+curl -s "$SITE_URL/sitemap.xml" | grep -oP '<loc>\K[^<]+' | sort
 ```
 
 Also check llms.txt for listed pages:
 ```bash
-curl -s "https://alterlab.io/llms.txt"
+curl -s "$SITE_URL/llms.txt"
 ```
 
 And the full version:
 ```bash
-curl -s "https://alterlab.io/llms-full.txt"
+curl -s "$SITE_URL/llms-full.txt"
 ```
 
 Build the list of all unique public pages from both sources.
@@ -133,7 +200,7 @@ curl -s "PAGE_URL" | grep -oP '<script type="application/ld\+json">\K[^<]+' | jq
 ```bash
 curl -s "PAGE_URL" | grep -oP 'property="og:title" content="\K[^"]+'
 ```
-- PASS: og:title exists and is NOT the generic site default (e.g., not just "AlterLab" or empty)
+- PASS: og:title exists and is NOT the generic site default (e.g., not just the project name or empty)
 - FAIL: missing or generic → flag "Missing/generic OG tags"
 
 Also check og:description:
@@ -152,7 +219,7 @@ Check if page URL appears in llms.txt content.
 ### 2C. Check robots.txt for AI Bots
 
 ```bash
-curl -s "https://alterlab.io/robots.txt"
+curl -s "$SITE_URL/robots.txt"
 ```
 
 Known AI crawler user-agents to check for:
@@ -297,16 +364,35 @@ gh issue edit {NUMBER} --milestone "geo-ai-discoverability"
 
 ### Add GEO issues to Project board
 
-For each created issue, add to the GitHub Project. Reference `~/projects/forge/docs/WORKFLOW.md` → "Project Board Integration" for field IDs.
+Read project board IDs from `forge.yaml → project_board`. If `project_board` is not configured, skip board integration.
 
 ```bash
-ISSUE_URL="https://github.com/RapierCraft/AlterLab/issues/${ISSUE_NUM}"
-ITEM_ID=$(gh project item-add 1 --owner RapierCraft --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
-if [ -n "$ITEM_ID" ]; then
-  gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id f75ad846 2>/dev/null || true  # Status=Todo
-  gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF98 --single-select-option-id 62864af4 2>/dev/null || true  # Lane=Fast
-  gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o --single-select-option-id 214c4d65 2>/dev/null || true  # Component=Platform
-  gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o --single-select-option-id {PRIORITY_OPTION_ID} 2>/dev/null || true  # Priority
+# Read project board config from forge.yaml
+BOARD_CONFIG=$(python3 - <<'PYEOF'
+import yaml, sys
+cfg = yaml.safe_load(open('forge.yaml'))
+board = cfg.get('project_board', {})
+if not board:
+    print('')
+    sys.exit(0)
+print(board.get('owner', cfg.get('project', {}).get('owner', '')))
+print(str(board.get('project_number', '')))
+print(board.get('project_id', ''))
+PYEOF
+)
+
+BOARD_OWNER=$(echo "$BOARD_CONFIG" | sed -n '1p')
+BOARD_NUMBER=$(echo "$BOARD_CONFIG" | sed -n '2p')
+BOARD_ID=$(echo "$BOARD_CONFIG" | sed -n '3p')
+
+if [ -n "$BOARD_OWNER" ] && [ -n "$BOARD_NUMBER" ]; then
+  ISSUE_URL="https://github.com/$GH_REPO/issues/${ISSUE_NUM}"
+  ITEM_ID=$(gh project item-add "$BOARD_NUMBER" --owner "$BOARD_OWNER" --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
+  if [ -n "$ITEM_ID" ] && [ -n "$BOARD_ID" ]; then
+    # Set Status, Lane, Priority using field IDs from forge.yaml → project_board.field_ids
+    # See docs/CONFIG.md → project_board section for how to get field IDs
+    echo "Issue added to project board. Set Status/Lane/Priority manually or configure field_ids in forge.yaml."
+  fi
 fi
 ```
 
@@ -336,8 +422,10 @@ fi
 
 ## Error Handling
 
+- **forge.yaml missing**: Print setup instructions and exit. Do not proceed without config.
+- **services.analytics missing**: Print configuration instructions and exit.
 - **Umami auth fails**: Try SOPS credentials. If still broken, skip Umami and note in report.
 - **Clarity MCP fails**: Skip Clarity data, proceed with Umami only.
-- **curl to alterlab.io fails**: Report "Site unreachable — cannot run compliance checks" and only show referral data.
+- **curl to site fails**: Report "Site unreachable — cannot run compliance checks" and only show referral data.
 - **No AI referral data at all**: Report "No AI referral traffic detected in the last 30 days" — this IS an insight (we need to improve discoverability).
 - **Rate limits or timeouts**: Note which checks were incomplete. Partial audit > no audit.

package/commands/incident-response.md

@@ -7,6 +7,9 @@ argument-hint: [issue number | "active" | "postmortem {issue}"]
 
 **Input**: $ARGUMENTS
 
+**Config variables used by this command** (set in `forge.yaml`):
+- `{REPO_PATH}` ← `paths.root` — project repository root
+
 You are the pipeline's incident response coordinator. When production goes down or a critical bug surfaces, this command orchestrates the response: validates the hotfix before deploy, reconstructs the incident timeline, and produces a post-incident analysis.
 
 **Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`.
@@ -106,7 +109,7 @@ You are validating a hotfix for a P0 production incident.
 
 Issue: #{NUMBER} — {TITLE}
 Fix branch: {FIX_BRANCH}
-Repo: /home/mrdubey/projects/ScraperAPI/alterlab
+Repo: {REPO_PATH}
 
 Your job:
 1. Read the fix diff: git diff origin/main..origin/{FIX_BRANCH}

package/commands/issue.md

@@ -35,12 +35,20 @@ The user's input (`$ARGUMENTS`) can be:
 
 ### 1A: Resolve target repository
 
+Read `forge.yaml` to build the routing table dynamically:
+
+```bash
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+GH_FLAG="-R $GH_REPO"
+REPO_PATH=$(yq '.paths.root' forge.yaml)
+STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
+# Satellite repos from forge.yaml → repos.satellites (each has: prefix, repo, staging_branch)
+```
+
 | Prefix | Repository | GH_REPO | GH_FLAG |
 |--------|-----------|---------|---------|
-| (none) / `alterlab:` | AlterLab | `RapierCraft/AlterLab` | (none) |
-| `forge:` | Forge | `RapierCraftStudios/forge` | `-R RapierCraftStudios/forge` |
-| `mcp:` | MCP Server | `RapierCraft/alterlab-mcp-server` | `-R RapierCraft/alterlab-mcp-server` |
-| `n8n:` | n8n Node | `RapierCraft/n8n-nodes-alterlab` | `-R RapierCraft/n8n-nodes-alterlab` |
+| (none) | Default project | `{GH_REPO}` from `forge.yaml → project.owner/repo` | (none / use `{GH_FLAG}`) |
+| `{satellite_prefix}:` | Satellite repo | `{satellite.repo}` from `forge.yaml → repos.satellites` | `-R {satellite.repo}` |
 
 ### 1B: Classify issue type
 
@@ -88,21 +96,10 @@ Pick ONE primary category label:
 
 ### 2A: Identify the domain
 
-For AlterLab issues, map to domains and their key files:
-
-| Domain | Key Entry Points |
-|--------|-----------------|
-| BILLING | `routers/billing.py`, `core/pricing.py`, `services/credit_service.py` |
-| SCRAPING | `unified_consumer.py`, `queues.py`, `domain_playbooks.json` |
-| AUTH | `core/auth.py`, `routers/auth.py`, `dependencies.py` |
-| DATABASE | `infra/migrations/`, `models/`, `db/` |
-| FRONTEND | `web/src/app/`, `web/src/components/`, `web/src/lib/` |
-| CORTEX | `cortex_client.py`, `routers/cortex.py` |
-| INFRA | `.github/workflows/`, `docker-compose.yml`, `docker-compose.prod.yml`, `infra/traefik/` |
+Map the issue to its domain and key files. Domain structure comes from the project — check `forge.yaml → review.context` and the project's `CLAUDE.md` for project-specific domain maps.
 
-For Forge issues: `commands/*.md`, `CLAUDE.md`, `install.sh`
-For MCP issues: read the repo's `src/` directory
-For n8n issues: read the repo's `nodes/` and `credentials/` directories
+For ForgeDock issues (this repo): `commands/*.md`, `CLAUDE.md`, `install.sh`, `bin/`
+For satellite repo issues: read the satellite repo's source directory (from `forge.yaml → repos.satellites`)
 
 ### 2B: Read the affected files
 
@@ -113,12 +110,12 @@ For n8n issues: read the repo's `nodes/` and `credentials/` directories
 3. **Import chains**: If the issue is about a function, check what imports it and what it imports.
 
 ```bash
-# For AlterLab — resolve the right branch to read from
-# Check staging first (most recent deployable state), then main
-git fetch origin staging main 2>/dev/null
+# Resolve the right branch to read from
+# Check the staging branch first (most recent deployable state), then the default branch
+git fetch origin {STAGING_BRANCH} {DEFAULT_BRANCH} 2>/dev/null
 
 # Read the files relevant to the issue
-# Use git show origin/staging:{filepath} for AlterLab files
+# Use git show origin/{STAGING_BRANCH}:{filepath} for project files
 ```
 
 ### 2C: Identify ALL affected files
@@ -423,11 +420,15 @@ else
 fi
 ```
 
-### 4D: Add to Project board (AlterLab only)
+### 4D: Add to Project board (if configured)
 
 ```bash
-# For AlterLab issues, add to the project board
-gh project item-add {PROJECT_NUMBER} --owner RapierCraft --url "${ISSUE_URL}" 2>/dev/null || true
+# Add to project board if forge.yaml → project_board is configured
+PROJECT_NUMBER=$(yq '.project_board.project_number // ""' forge.yaml)
+PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' forge.yaml)
+if [ -n "$PROJECT_NUMBER" ] && [ "$PROJECT_NUMBER" != "null" ]; then
+  gh project item-add "$PROJECT_NUMBER" --owner "$PROJECT_BOARD_OWNER" --url "${ISSUE_URL}" 2>/dev/null || true
+fi
 ```
 
 ### 4E: Report to user

package/commands/milestone.md

@@ -13,28 +13,51 @@ Milestones are the top-level planning unit. They group related issues into a shi
 
 **You have access to ALL tools** — Task tool, Skill tool, sub-agents, everything.
 
+## Config Resolution
+
+Read `forge.yaml` at the project root to resolve all project-specific variables before running any commands:
+
+```bash
+# Parse forge.yaml for project context
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+GH_FLAG="-R $GH_REPO"
+REPO_PATH=$(yq '.paths.root' forge.yaml)
+PROJECT_NAME=$(yq '.project.name' forge.yaml)
+STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
+PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' forge.yaml)
+PROJECT_NUMBER=$(yq '.project_board.project_number // "1"' forge.yaml)
+PROJECT_ID=$(yq '.project_board.project_id' forge.yaml)
+# Build satellite repo map from repos.satellites list
+# Each satellite: { prefix, repo, staging_branch }
+```
+
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, and `{PROJECT_ID}` references below are populated from `forge.yaml`.
+
+---
+
 ## Multi-Repo Support
 
-Milestones can span the AlterLab ecosystem. Project context (repo map, paths, conventions) comes from each project's `CLAUDE.md`.
+Milestones can span multiple repositories. Project context (repo map, paths, conventions) comes from `forge.yaml`.
 
 ### Cross-Repo Milestones
 
-Some milestones (e.g., "BYOS Authenticated Scraping") require changes across multiple repos — the platform, SDKs, MCP server, etc. For these:
+Some milestones require changes across multiple repos — the platform, SDKs, satellite services, etc. For these:
 
-- **The milestone is created in the primary repo** (usually `RapierCraft/AlterLab`)
-- **Issues are created in the repo where the code lives** — e.g., MCP server issues go to `RapierCraft/alterlab-mcp-server`
+- **The milestone is created in the primary repo** (`{GH_REPO}` — the default repo from `forge.yaml`)
+- **Issues are created in the repo where the code lives** — satellite repos come from `forge.yaml → repos.satellites`
 - **Each repo gets its own milestone branch** (`milestone/{slug}`) if it has issues in the milestone
-- **Issues reference the parent milestone** in their body: `Part of cross-repo milestone: **{TITLE}** (primary: RapierCraft/AlterLab)`
+- **Issues reference the parent milestone** in their body: `Part of cross-repo milestone: **{TITLE}** (primary: {GH_REPO})`
 
 ### Repo Prefixes (same as `/work-on`)
 
+Prefixes and repos are defined in `forge.yaml → repos.satellites`. Read the config to build the routing table:
+
 | Prefix | Repo |
 |--------|------|
-| _(none)_ | `RapierCraft/AlterLab` (default) |
-| `mcp:` | `RapierCraft/alterlab-mcp-server` |
-| `n8n:` | `RapierCraft/n8n-nodes-alterlab` |
+| _(none)_ | `{GH_REPO}` (default) |
+| `{SATELLITE_PREFIX}:` | `{SATELLITE_REPO}` (from `forge.yaml → repos.satellites`) |
 
-When decomposing a milestone, tag each proposed issue with its target repo. Use `-R` flag for non-default repos.
+When decomposing a milestone, tag each proposed issue with its target repo. Use `-R {SATELLITE_REPO}` flag for non-default repos.
 
 ---
 
@@ -76,7 +99,7 @@ Capture the milestone number from the response.
 ### Step 3: Create the milestone branch
 
 ```bash
-cd {REPO_PATH}  # default: /home/mrdubey/projects/ScraperAPI/alterlab
+cd {REPO_PATH}
 git fetch origin main
 git branch milestone/{slug} origin/main
 git push origin milestone/{slug}
@@ -86,7 +109,7 @@ git push origin milestone/{slug}
 
 Use a Task sub-agent to analyze the milestone scope and propose issues:
 
-> You are planning the scope for milestone "{TITLE}" on the AlterLab platform.
+> You are planning the scope for milestone "{TITLE}" on the {PROJECT_NAME} platform.
 >
 > **Milestone description**: {DESCRIPTION}
 >
@@ -95,19 +118,16 @@ Use a Task sub-agent to analyze the milestone scope and propose issues:
 > - Specific enough for the `/work-on` pipeline to pick up and implement
 > - Ordered by dependencies (if B needs A's API, A comes first)
 >
-> **AlterLab ecosystem context**:
-> - **Platform** (default): FastAPI backend (services/api/, services/worker/), Next.js frontend (web/), Docker microservices, PostgreSQL, Redis
-> - **Python SDK** (sdk/python/): Async client, httpx, pydantic
-> - **Node SDK** (sdk/node/): TypeScript client, axios
-> - **MCP Server** (alterlab-mcp-server/ — SEPARATE REPO): MCP tools for AI assistants, TypeScript, @modelcontextprotocol/sdk
-> - **n8n Node** (n8n-nodes-alterlab/ — SEPARATE REPO): n8n community node, TypeScript
-> - **Chrome Extension** (tools/chrome-extension/): Cookie capture for BYOS
+> **Project ecosystem context** (from `forge.yaml`):
+> - **Primary repo** (`{GH_REPO}`): The main project codebase at `{REPO_PATH}`
+> - **Tech stack**: {review.tech_stack from forge.yaml, or read CLAUDE.md for project context}
+> - **Satellite repos**: Read from `forge.yaml → repos.satellites` (each has a prefix and repo)
 >
-> Check the existing codebase to understand current architecture before proposing changes.
+> Check the existing codebase at `{REPO_PATH}` to understand current architecture before proposing changes.
 >
 > **Output format**: Numbered list of proposed issues, each with:
-> - **Title**: Actionable, specific (e.g., "Add per-token billing engine for LLM extraction")
-> - **Repo**: Which repo this issue belongs to (`alterlab`, `mcp`, `n8n`, or platform default)
+> - **Title**: Actionable, specific
+> - **Repo**: Which repo this issue belongs to (default or satellite prefix from forge.yaml)
 > - **Type**: `feature`, `bug`, `refactor`, `infra`
 > - **Priority**: P1-P3
 > - **Size**: S (1-2 files), M (3-5 files), L (6+ files)
@@ -126,8 +146,8 @@ Present the proposed issues to the user. Ask:
 For each approved issue, create it in the **correct repo** based on the scope analysis:
 
 ```bash
-# For AlterLab issues (default):
-gh issue create \
+# For default repo issues:
+gh issue create {GH_FLAG} \
   --title "{fix|feat|refactor}: {issue_title}" \
   --label "{type},{priority}" \
   --milestone "{TITLE}" \
@@ -190,7 +210,7 @@ Files that need changes:
 
 ## Context
 
-Part of cross-repo milestone: **{MILESTONE_TITLE}** (primary: RapierCraft/AlterLab)
+Part of cross-repo milestone: **{MILESTONE_TITLE}** (primary: {GH_REPO})
 **Type**: {feature|bug|refactor|infra}
 
 ## Dependencies
@@ -202,17 +222,17 @@ BODY_EOF
 
 ### Step 6B: Add issues to Project board
 
-For each created issue, add it to the GitHub Project board with initial fields. Reference `~/projects/forge/docs/WORKFLOW.md` → "Project Board Integration" for field IDs.
+For each created issue, add it to the GitHub Project board with initial fields. Reference `forge.yaml → project_board` for field IDs, or `docs/CONFIG.md` → "Project Board" for lookup commands.
 
 ```bash
 for ISSUE_NUM in {created_issue_numbers}; do
   ISSUE_URL="https://github.com/{GH_REPO}/issues/${ISSUE_NUM}"
-  ITEM_ID=$(gh project item-add 1 --owner RapierCraft --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
+  ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {PROJECT_BOARD_OWNER} --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
   if [ -n "$ITEM_ID" ]; then
-    gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id f75ad846 2>/dev/null || true  # Status=Todo
-    gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF98 --single-select-option-id 4ff6f9e6 2>/dev/null || true  # Lane=Feature
-    gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o --single-select-option-id {COMPONENT_OPTION_ID} 2>/dev/null || true  # Component (from repo — see WORKFLOW.md mapping)
-    gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o --single-select-option-id {PRIORITY_OPTION_ID} 2>/dev/null || true  # Priority (from label)
+    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_STATUS_FIELD_ID} --single-select-option-id {PROJECT_BOARD_STATUS_TODO_ID} 2>/dev/null || true  # Status=Todo
+    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_LANE_FIELD_ID} --single-select-option-id {PROJECT_BOARD_LANE_FEATURE_ID} 2>/dev/null || true  # Lane=Feature
+    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_COMPONENT_FIELD_ID} --single-select-option-id {COMPONENT_OPTION_ID} 2>/dev/null || true  # Component (from forge.yaml → project_board.fields)
+    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_PRIORITY_FIELD_ID} --single-select-option-id {PRIORITY_OPTION_ID} 2>/dev/null || true  # Priority (from label)
   fi
 done
 ```
@@ -308,13 +328,13 @@ Wait for confirmation.
 Before shipping, ensure the milestone branch is up to date with `staging` (picks up any fast-lane fixes that accumulated since the milestone branch was created):
 
 ```bash
-cd {REPO_PATH}  # default: /home/mrdubey/projects/ScraperAPI/alterlab
-git fetch origin staging milestone/{slug}
+cd {REPO_PATH}
+git fetch origin {STAGING_BRANCH} milestone/{slug}
 git checkout milestone/{slug}
-git merge origin/staging --no-edit
+git merge origin/{STAGING_BRANCH} --no-edit
 # If conflicts, report to user and STOP — do not auto-resolve
 git push origin milestone/{slug}
-git checkout staging
+git checkout {STAGING_BRANCH}
 ```
 
 ### Step 2.5: Pre-Merge Hunk-Loss Audit (MANDATORY before creating PR)
@@ -325,12 +345,12 @@ This step identifies "at-risk hunks" — staging-only content in files the miles
 
 ```bash
 cd {REPO_PATH}
-git fetch origin staging milestone/{slug}
+git fetch origin {STAGING_BRANCH} milestone/{slug}
 
 echo "=== Pre-Merge Hunk-Loss Audit ==="
 
-# Files the milestone branch changes vs staging
-MILESTONE_FILES=$(git diff --name-only origin/staging...origin/milestone/{slug})
+# Files the milestone branch changes vs the staging branch
+MILESTONE_FILES=$(git diff --name-only origin/{STAGING_BRANCH}...origin/milestone/{slug})
 
 if [ -z "$MILESTONE_FILES" ]; then
     echo "No files changed by milestone vs staging — nothing to audit. Proceeding to PR creation."
@@ -339,8 +359,8 @@ else
     # NOTE: $MILESTONE_FILES is intentionally unquoted here — word-splitting is required to pass
     # each filename as a separate path argument to git diff. Quoting would collapse the newline-
     # separated list into a single argument matching no real path, silently producing an empty diff.
-    # Filenames with spaces are not present in this codebase (AlterLab/Forge use standard paths).
-    AT_RISK=$(git diff origin/milestone/{slug}...origin/staging -- $MILESTONE_FILES 2>/dev/null)
+    # Filenames with spaces are not expected in standard project paths.
+    AT_RISK=$(git diff origin/milestone/{slug}...origin/{STAGING_BRANCH} -- $MILESTONE_FILES 2>/dev/null)
     AT_RISK_COUNT=$(echo "$AT_RISK" | grep -c '^@@' 2>/dev/null || echo 0)
 
     if [ "$AT_RISK_COUNT" -eq 0 ]; then
@@ -350,9 +370,9 @@ else
         echo "Affected files:"
         echo "$AT_RISK" | grep '^--- a/' | sed 's|^--- a/||'
 
-        echo "Rebasing milestone/{slug} onto origin/staging to absorb at-risk hunks..."
+        echo "Rebasing milestone/{slug} onto origin/{STAGING_BRANCH} to absorb at-risk hunks..."
         git checkout milestone/{slug}
-        git rebase origin/staging
+        git rebase origin/{STAGING_BRANCH}
 
         REBASE_EXIT=$?
         if [ "$REBASE_EXIT" -ne 0 ]; then
@@ -362,21 +382,21 @@ else
 
             # Abort the failed rebase and return to a clean state
             git rebase --abort 2>/dev/null || true
-            git checkout staging
+            git checkout {STAGING_BRANCH}
 
             # Truncate AT_RISK to safe size for issue body (avoid shell quoting issues with large diffs)
             AT_RISK_SNIPPET=$(echo "$AT_RISK" | head -60 | sed "s/'/'\\\\''/g")
 
-            gh issue create -R {GH_REPO} \
+            gh issue create {GH_FLAG} \
               --title "fix(milestone): rebase conflict during hunk-loss audit for milestone/{slug}" \
               --body "$(cat <<ISSUE_EOF
 ## Problem
 
-The pre-merge hunk-loss audit for milestone \`{slug}\` detected $AT_RISK_COUNT at-risk staging hunks, then attempted to rebase \`milestone/{slug}\` onto \`origin/staging\` to absorb them. The rebase conflicted and was aborted. Manual resolution is required before the milestone can ship.
+The pre-merge hunk-loss audit for milestone \`{slug}\` detected $AT_RISK_COUNT at-risk staging hunks, then attempted to rebase \`milestone/{slug}\` onto \`origin/{STAGING_BRANCH}\` to absorb them. The rebase conflicted and was aborted. Manual resolution is required before the milestone can ship.
 
 ## Root Cause
 
-Divergent changes between \`milestone/{slug}\` and \`origin/staging\` cannot be automatically rebased. Conflicting files must be resolved manually.
+Divergent changes between \`milestone/{slug}\` and \`origin/{STAGING_BRANCH}\` cannot be automatically rebased. Conflicting files must be resolved manually.
 
 ## Affected Files
 
@@ -401,7 +421,7 @@ ${AT_RISK_SNIPPET}
 Resolve the rebase conflict manually:
 \`\`\`bash
 git checkout milestone/{slug}
-git rebase origin/staging
+git rebase origin/{STAGING_BRANCH}
 # resolve conflicts in the files listed above
 git rebase --continue
 git push origin milestone/{slug} --force-with-lease
@@ -421,7 +441,7 @@ ISSUE_EOF
         # Rebase succeeded — push the rebased branch
         git push origin milestone/{slug} --force-with-lease
         echo "Rebase complete. Milestone branch now includes all $AT_RISK_COUNT at-risk staging hunks."
-        git checkout staging
+        git checkout {STAGING_BRANCH}
     fi
 fi
 ```
@@ -430,11 +450,11 @@ fi
 
 ```bash
 # Get the full diff summary (computed after Step 2.5 rebase, so it reflects the final state)
-DIFF_STATS=$(git diff origin/staging...origin/milestone/{slug} --stat)
-COMMIT_LOG=$(git log origin/staging..origin/milestone/{slug} --oneline)
+DIFF_STATS=$(git diff origin/{STAGING_BRANCH}...origin/milestone/{slug} --stat)
+COMMIT_LOG=$(git log origin/{STAGING_BRANCH}..origin/milestone/{slug} --oneline)
 
-gh pr create \
-  --base staging \
+gh pr create {GH_FLAG} \
+  --base {STAGING_BRANCH} \
   --head milestone/{slug} \
   --title "Ship: {MILESTONE_TITLE}" \
   --body "$(cat <<'PR_EOF'
@@ -446,8 +466,8 @@ gh pr create \
 {list of all closed issues in this milestone with PR references}
 
 ## Hunk-Loss Audit
-{If Step 2.5 rebase ran: "✓ Rebase completed — {AT_RISK_COUNT} at-risk staging hunks absorbed into milestone branch before this PR was created. All staging content is preserved."}
-{If Step 2.5 found no at-risk hunks: "✓ Clean — no at-risk staging hunks detected. Safe to merge."}
+{If Step 2.5 rebase ran: "✓ Rebase completed — {AT_RISK_COUNT} at-risk staging-branch hunks absorbed into milestone branch before this PR was created. All staging content is preserved."}
+{If Step 2.5 found no at-risk hunks: "✓ Clean — no at-risk staging-branch hunks detected. Safe to merge."}
 
 > ⚠ **IMPORTANT: Merge this PR using a MERGE COMMIT, not squash.** Squash-merging a milestone PR can silently drop staging-only hunks in files the milestone touches. Use the "Create a merge commit" option in the GitHub UI, or `gh pr merge {PR_NUMBER} --merge`.
 
@@ -544,19 +564,20 @@ To deploy: merge `staging → main` via GitHub web UI when ready.
 
 ## Action: Sync Milestone Branch
 
-Syncs the milestone branch with the latest `main` to pick up fast-lane fixes. Run periodically on long-lived milestones.
+Syncs the milestone branch with the latest default branch to pick up fast-lane fixes. Run periodically on long-lived milestones.
 
 ```bash
-cd {REPO_PATH}  # default: /home/mrdubey/projects/ScraperAPI/alterlab
-git fetch origin main milestone/{slug}
+cd {REPO_PATH}
+DEFAULT_BRANCH=$(yq '.branches.default' forge.yaml)
+git fetch origin $DEFAULT_BRANCH milestone/{slug}
 git checkout milestone/{slug}
-git merge origin/main --no-edit
+git merge origin/$DEFAULT_BRANCH --no-edit
 # If conflicts, report to user and STOP
 git push origin milestone/{slug}
-git checkout main
+git checkout $DEFAULT_BRANCH
 ```
 
-Report: "Synced milestone/{slug} with latest main. {N} new commits from main incorporated."
+Report: "Synced milestone/{slug} with latest `{DEFAULT_BRANCH}`. {N} new commits incorporated."
 
 ---