forgedock 1.0.1 → 1.0.2

package/commands/work-on/build/implement.md

@@ -19,8 +19,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraft/AlterLab`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraft/AlterLab`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--worktree {WORKTREE_PATH}` — absolute path to the git worktree (set by caller)
 - `--branch {BRANCH}` — feature branch name (e.g. `feat/my-feature`)
 
@@ -145,7 +145,7 @@ if [ -n "$NEW_ENV_VARS" ]; then
 fi
 ```
 
-**If any MISSING line is printed**: add the var to the missing location before proceeding to Phase I4. If the file doesn't exist in this repo (e.g. `ENV_VARS.md` is an AlterLab file, not a Forge file), skip that check silently.
+**If any MISSING line is printed**: add the var to the missing location before proceeding to Phase I4. If a file listed above doesn't exist in this repo (e.g. `ENV_VARS.md` or `env_validation.py` may not be present in all projects), skip that check silently.
 
 ### Check 2 — Deploy/infra restart risk
 

package/commands/work-on/build/validate.md

@@ -19,8 +19,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraft/AlterLab`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraft/AlterLab`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--worktree {WORKTREE_PATH}` — absolute path to the git worktree
 - `--files {CHANGED_FILES}` — space-separated list of changed files (from implement result)
 
@@ -99,7 +99,7 @@ python -m py_compile {PYTHON_FILES}
 ```
 Failures in `py_compile` are BLOCKING — fix before continuing.
 
-**TypeScript (AlterLab)**:
+**TypeScript (tsc)**:
 ```bash
 cd {WORKTREE_PATH}
 prettier --write {TS_FILES}

package/commands/work-on/build.md

@@ -21,8 +21,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BA
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraftStudios/forge`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--base {PR_BASE}` — PR target branch (e.g. `milestone/modular-pipeline-architecture` or `staging`)
 
 ---
@@ -36,16 +36,16 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 
 # Check investigation report
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 
 # Check if build already completed
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body'
 ```
 
 **Resume check**:
-- If `<!-- FORGE:BUILDER -->` or `<!-- ALTERLAB:BUILDER -->` comment exists → build already complete. Return `BUILD_RESULT: status: ALREADY_DONE` to router.
-- If no `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` comment with `<!-- INVESTIGATION:COMPLETE -->` → EXIT with `BUILD_RESULT: status: BLOCKED`, blocker: "Investigation not complete — run investigate first".
+- If `<!-- FORGE:BUILDER -->` comment exists → build already complete. Return `BUILD_RESULT: status: ALREADY_DONE` to router.
+- If no `<!-- FORGE:INVESTIGATOR -->` comment with `<!-- INVESTIGATION:COMPLETE -->` → EXIT with `BUILD_RESULT: status: BLOCKED`, blocker: "Investigation not complete — run investigate first".
 
 Extract from investigation report:
 - Affected files list

package/commands/work-on/close.md

@@ -19,8 +19,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMB
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraftStudios/forge`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--pr {PR_NUMBER}` — merged PR number
 - `--base {PR_BASE}` — branch the PR merged into (e.g. `milestone/modular-pipeline-architecture`)
 - `--branch {BRANCH}` — feature branch name (for worktree cleanup reference)
@@ -106,34 +106,63 @@ The `REMAINING_AFTER` variable is passed to Phase C2 to decide whether to close.
 
 Update the project board to reflect the merged state. This replaces the old Phase 5E project board update that existed before the modular refactor.
 
-```bash
-# Find the project item ID for this issue
-ISSUE_URL="https://github.com/{GH_REPO}/issues/{NUMBER}"
-ITEM_ID=$(gh project item-list 1 --owner RapierCraft --format json --limit 200 \
-  --jq ".items[] | select(.content.url == \"$ISSUE_URL\") | .id" 2>/dev/null | head -1)
-```
+**Read project board config from `forge.yaml`**. If the `project_board` section is absent or commented out, skip this phase entirely:
 
-If `ITEM_ID` is found:
 ```bash
-# Set Status=Done
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id 98236657 2>/dev/null || true  # Status=Done
-
-# Set Workflow=Merged
-gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
-  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA --single-select-option-id b510c537 2>/dev/null || true  # Workflow=Merged
+# Read project board config from forge.yaml
+PROJECT_BOARD_OWNER=$(yq '.project_board.owner // ""' forge.yaml 2>/dev/null || echo "")
+PROJECT_ID=$(yq '.project_board.project_id // ""' forge.yaml 2>/dev/null || echo "")
+PROJECT_NUMBER=$(yq '.project_board.project_number // ""' forge.yaml 2>/dev/null || echo "")
+STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' forge.yaml 2>/dev/null || echo "")
+WORKFLOW_FIELD_ID=$(yq '.project_board.field_ids.workflow // ""' forge.yaml 2>/dev/null || echo "")
+STATUS_DONE_OPTION_ID=$(yq '.project_board.option_ids.status.done // ""' forge.yaml 2>/dev/null || echo "")
+WORKFLOW_MERGED_OPTION_ID=$(yq '.project_board.option_ids.workflow.merged // ""' forge.yaml 2>/dev/null || echo "")
+
+if [ -z "$PROJECT_BOARD_OWNER" ] || [ -z "$PROJECT_ID" ] || [ -z "$STATUS_FIELD_ID" ]; then
+  echo "INFO: project_board not configured in forge.yaml — skipping board update"
+  # → STOP: do not proceed to ITEM_ID fetch or board update — continue to Phase C2
+else
+  # Project board is configured — find the item and update it
+
+  # Find the project item ID for this issue
+  ISSUE_URL="https://github.com/{GH_REPO}/issues/{NUMBER}"
+  ITEM_ID=$(gh project item-list "$PROJECT_NUMBER" --owner "$PROJECT_BOARD_OWNER" --format json --limit 200 \
+    --jq ".items[] | select(.content.url == \"$ISSUE_URL\") | .id" 2>/dev/null | head -1)
+
+  if [ -n "$ITEM_ID" ]; then
+    # Set Status=Done
+    if [ -n "$STATUS_FIELD_ID" ] && [ -n "$STATUS_DONE_OPTION_ID" ]; then
+      gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+        --field-id "$STATUS_FIELD_ID" --single-select-option-id "$STATUS_DONE_OPTION_ID" 2>/dev/null || true
+    fi
+
+    # Set Workflow=Merged
+    if [ -n "$WORKFLOW_FIELD_ID" ] && [ -n "$WORKFLOW_MERGED_OPTION_ID" ]; then
+      gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+        --field-id "$WORKFLOW_FIELD_ID" --single-select-option-id "$WORKFLOW_MERGED_OPTION_ID" 2>/dev/null || true
+    fi
+  else
+    echo "INFO: Issue #{NUMBER} not found on project board — skipping board update"
+  fi
+fi
 ```
 
-If `ITEM_ID` is empty (issue not on project board) → log and skip:
-```bash
-echo "INFO: Issue #{NUMBER} not found on project board — skipping board update"
+**Project board field IDs are read from `forge.yaml → project_board`**. To configure:
+```yaml
+project_board:
+  owner: "{your-github-org}"
+  project_number: 1
+  project_id: "PVT_kwHO..."
+  field_ids:
+    status: "PVTSSF_..."
+    workflow: "PVTSSF_..."
+  option_ids:
+    status:
+      done: "..."
+    workflow:
+      merged: "..."
 ```
-
-**Field reference** (project `PVT_kwHOCx3gR84BSK2L`):
-| Field | Field ID | Option | Option ID |
-|-------|----------|--------|-----------|
-| Status | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E` | Done | `98236657` |
-| Workflow | `PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA` | Merged | `b510c537` |
+To find your project IDs: `gh project list --owner {owner}` and `gh project field-list {number} --owner {owner}`.
 
 ---
 
@@ -220,18 +249,18 @@ gh issue edit {PARENT_REF} {GH_FLAG} --add-label "workflow:merged"
 Reconstruct the pipeline summary from GitHub state:
 
 ```bash
-# Get investigation verdict from FORGE:INVESTIGATOR comment (or legacy ALTERLAB:INVESTIGATOR)
+# Get investigation verdict from FORGE:INVESTIGATOR comment
 VERDICT=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body' \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' \
   | grep -oP '(?<=\*\*Verdict\*\*: )\w+' | head -1)
 
 CONFIDENCE=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body' \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' \
   | grep -oP '(?<=\*\*Confidence\*\*: )\w+' | head -1)
 
-# Get files changed from FORGE:BUILDER comment (or legacy ALTERLAB:BUILDER)
+# Get files changed from FORGE:BUILDER comment
 FILES_CHANGED=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body' \
+  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body' \
   | grep -oP '(?<=\*\*Files changed\*\*: )\d+' | head -1)
 ```
 

package/commands/work-on/decompose.md

@@ -19,8 +19,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraftStudios/forge`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 
 ---
 
@@ -33,11 +33,11 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 
 # Read investigation report (required — contains decomposition plan)
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 ```
 
 **Validation**:
-- If FORGE:INVESTIGATOR / ALTERLAB:INVESTIGATOR comment is absent → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "No investigation report found — run investigate first"
+- If FORGE:INVESTIGATOR comment is absent → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "No investigation report found — run investigate first"
 - If investigation report has no Decomposition Assessment section, OR the assessment does not list any sub-issues → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "Investigation report has no decomposition plan — re-run investigate with explicit decomposition scope"
 
 Extract from investigation report:
@@ -56,10 +56,10 @@ MILESTONE_TITLE=$(gh issue view {NUMBER} {GH_FLAG} --json milestone --jq '.miles
 
 ```bash
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:DECOMPOSED") or contains("ALTERLAB:DECOMPOSED"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:DECOMPOSED")) | .body'
 ```
 
-- If `<!-- FORGE:DECOMPOSED -->` or `<!-- ALTERLAB:DECOMPOSED -->` comment exists → decomposition already complete. EXIT with `DECOMPOSE_RESULT: status: ALREADY_DONE`.
+- If `<!-- FORGE:DECOMPOSED -->` comment exists → decomposition already complete. EXIT with `DECOMPOSE_RESULT: status: ALREADY_DONE`.
 
 ---
 

package/commands/work-on/investigate.md

@@ -1,6 +1,6 @@
 ---
 description: Investigate a GitHub issue — validate it's real, determine root cause, post findings
-argument-hint: [issue number] [--repo RapierCraftStudios/forge] [--gh-flag "-R RapierCraftStudios/forge"]
+argument-hint: [issue number] [--repo {owner}/{repo}] [--gh-flag "-R {owner}/{repo}"]
 ---
 
 # /work-on:investigate — Issue Investigation Subcommand
@@ -18,10 +18,10 @@ Standalone investigation phase for the work-on pipeline. Validates whether an is
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (default: `RapierCraftStudios/forge` when running in Forge context; for AlterLab issues use `RapierCraft/AlterLab`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 
-If called from `work-on`, these are passed through. If invoked standalone, defaults apply.
+If called from `work-on`, these are passed through. If invoked standalone, `--repo` and `--gh-flag` are resolved from `forge.yaml → project`.
 
 ---
 
@@ -33,8 +33,8 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, body: .bod
 ```
 
 **Resume logic**:
-- If `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` comment exists AND `<!-- INVESTIGATION:COMPLETE -->` is present in the SAME comment → investigation already complete, EXIT (return existing verdict to caller)
-- If `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted, delete the partial comment and restart:
+- If `<!-- FORGE:INVESTIGATOR -->` comment exists AND `<!-- INVESTIGATION:COMPLETE -->` is present in the SAME comment → investigation already complete, EXIT (return existing verdict to caller)
+- If `<!-- FORGE:INVESTIGATOR -->` comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted, delete the partial comment and restart:
   ```bash
   gh api repos/{GH_REPO}/issues/comments/{COMMENT_ID} -X DELETE
   ```
@@ -54,20 +54,16 @@ gh issue edit {NUMBER} {GH_FLAG} --remove-label "workflow:ready-to-build,workflo
 
 ### Resolve target repo and branch
 
-For Forge issues (repo = `RapierCraftStudios/forge`):
-- Key files: `commands/work-on.md`, `commands/review-pr.md`, `commands/quality-gate.md`, `commands/orchestrate.md`, `install.sh`, `CLAUDE.md`
+The target repo is `{GH_REPO}` (resolved from `forge.yaml → project`). The working directory is `{REPO_PATH}` (resolved from `forge.yaml → paths.root`).
 
-For AlterLab issues (repo = `RapierCraft/AlterLab`):
+**Domain-to-files mapping**: The repo's domain structure depends on the project. Before investigating, read the issue body and labels to identify the affected domain. Then look at the repo's directory structure under `{REPO_PATH}` to locate relevant files. Common entry points:
+- Command/prompt files: `commands/`, `.claude/commands/`
+- Backend services: any `services/`, `routers/`, `core/` directories
+- Frontend: any `web/`, `frontend/`, `src/` directories
+- Infrastructure: `.github/workflows/`, `docker-compose*.yml`, `infra/`
+- Config: `forge.yaml`, `.env.example`, any `config/` directory
 
-| Domain | Key files |
-|--------|-----------|
-| 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`, `infra/traefik/` |
+If the issue specifies a **Code branch** (`**Code branch**: \`{branch}\``), check out that branch — the affected files may not be on the default branch.
 
 ### Investigation steps
 
@@ -154,7 +150,7 @@ fi
 
 ```bash
 INVESTIGATION_BODY=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body' | head -1)
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' | head -1)
 ```
 
 ### Step 3: Generate filename and metadata
@@ -166,7 +162,7 @@ MILESTONE=$(gh issue view {NUMBER} {GH_FLAG} --json milestone --jq '.milestone.t
 # Generate slug from title: lowercase, replace non-alphanumeric with hyphens, collapse, truncate
 SLUG=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
 
-# Derive repo short name from GH_REPO (e.g., "RapierCraftStudios/forge" → "forge")
+# Derive repo short name from GH_REPO (e.g., "acme-org/acme-platform" → "acme-platform")
 REPO_SHORT=$(echo "{GH_REPO}" | sed 's|.*/||')
 
 GIST_FILENAME="${REPO_SHORT}_${NUMBER}_${SLUG}.md"

package/commands/work-on/review.md

@@ -19,8 +19,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 
 Parse from $ARGUMENTS:
 - `{NUMBER}` — issue number (required)
-- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraftStudios/forge`)
-- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `{owner}/{repo}` — resolved from `forge.yaml → project`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R {owner}/{repo}`)
 - `--worktree {WORKTREE_PATH}` — absolute path to the git worktree
 - `--branch {BRANCH}` — feature branch name (e.g. `feat/my-feature`)
 - `--base {PR_BASE}` — PR target branch (e.g. `milestone/modular-pipeline-architecture` or `staging`)
@@ -36,7 +36,7 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 
 # Get builder comment (for branch + commit info)
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body'
 
 # Check if PR already exists for this branch
 gh pr list {GH_FLAG} --head {BRANCH} --json number,state,url 2>/dev/null
@@ -45,7 +45,7 @@ gh pr list {GH_FLAG} --head {BRANCH} --json number,state,url 2>/dev/null
 **Resume check**:
 - If PR already exists AND is OPEN → skip to Phase R3 (invoke /review-pr)
 - If PR already exists AND is MERGED → return `REVIEW_RESULT: status: ALREADY_MERGED`
-- If no `<!-- FORGE:BUILDER -->` or `<!-- ALTERLAB:BUILDER -->` comment exists → EXIT with `REVIEW_RESULT: status: BLOCKED`, blocker: "FORGE:BUILDER comment not found — implement phase may not have completed"
+- If no `<!-- FORGE:BUILDER -->` comment exists → EXIT with `REVIEW_RESULT: status: BLOCKED`, blocker: "FORGE:BUILDER comment not found — implement phase may not have completed"
 
 ---
 

package/commands/work-on-monolithic.md

@@ -29,24 +29,23 @@ Orchestrator for the full issue lifecycle: investigate → build → review →
 
 ---
 
-## Multi-Repo Support
+## Project Configuration
 
-| Input | Resolves To |
-|-------|-------------|
-| `123` / `#123` | AlterLab (default): `RapierCraftStudios/AlterLab` |
-| `mcp:5` | MCP Server: `RapierCraftStudios/alterlab-mcp-server` |
-| `n8n:12` | n8n Node: `RapierCraftStudios/n8n-nodes-alterlab` |
+Read `forge.yaml` from the repository root. If missing, tell the user to run `npx forgedock init` and stop.
 
-**Context Variables** (set after resolving project):
+Resolve the following variables from `forge.yaml` before running any pipeline phase:
 
-| Variable | AlterLab | MCP | n8n |
-|----------|----------|-----|-----|
-| `GH_REPO` | `RapierCraftStudios/AlterLab` | `RapierCraftStudios/alterlab-mcp-server` | `RapierCraftStudios/n8n-nodes-alterlab` |
-| `REPO_PATH` | `/home/mrdubey/projects/ScraperAPI/alterlab` | `/home/mrdubey/projects/ScraperAPI/alterlab-mcp-server` | `/home/mrdubey/projects/ScraperAPI/n8n-nodes-alterlab` |
-| `STAGING_BRANCH` | `staging` | `main` | `main` |
-| `GH_FLAG` | _(empty)_ | `-R RapierCraftStudios/alterlab-mcp-server` | `-R RapierCraftStudios/n8n-nodes-alterlab` |
+| Variable | Source in forge.yaml | Description |
+|----------|----------------------|-------------|
+| `GH_REPO` | `project.owner` + `project.repo` | Full GitHub repo identifier (`owner/repo`) |
+| `REPO_PATH` | `paths.root` | Absolute path to the local repository |
+| `STAGING_BRANCH` | `branches.staging` | Branch for fast-lane PRs (no milestone) |
+| `WORKTREE_BASE` | `paths.worktree_base` | Directory where git worktrees are created |
+| `GH_FLAG` | _(empty for default repo; `-R owner/repo` for satellites)_ | Extra flag for `gh` CLI satellite repo calls |
 
-Satellite repos (MCP, n8n) have no staging — fast-lane PRs go to `main`.
+**Multi-repo routing** (optional): If `forge.yaml` contains a `repos.satellites` list, build the prefix routing table from it. Each satellite entry has `prefix`, `repo`, `staging_branch`, and `local_path`. Issues without a prefix route to the default `GH_REPO`. Satellite repos have no staging — their fast-lane PRs go to their configured `staging_branch` (typically `main`).
+
+If no `repos.satellites` section exists, only the primary repo is available — all issues route to `GH_REPO`.
 
 ---
 
@@ -189,7 +188,7 @@ Branch slug from title (lowercase, hyphenated, max 40 chars). Prefix: `fix/` (bu
 cd {REPO_PATH}
 git fetch origin
 BRANCH="fix/{slug}-{NUMBER}"
-git worktree add /home/mrdubey/projects/ScraperAPI/{WT_PREFIX}-worktrees/{BRANCH} -b {BRANCH} origin/{PR_BASE}
+git worktree add {WORKTREE_BASE}/{BRANCH} -b {BRANCH} origin/{PR_BASE}
 ```
 
 ### 3F: Implement
@@ -204,7 +203,7 @@ Fix HIGH/MEDIUM findings. Max 2 iterations. Skip for 1-file config/docs edits.
 
 ### 3G: Format and verify
 - Python: `black` + `isort` + `py_compile`
-- TypeScript (AlterLab): `prettier --write` + `tsc --noEmit` (BLOCKING if fails)
+- TypeScript (primary repo): `prettier --write` + `tsc --noEmit` (BLOCKING if fails)
 - TypeScript (satellite): `npm run build` + `prettier --write`
 
 ### 3H: Frontend proxy wiring check (MANDATORY)

package/commands/work-on.md

@@ -62,15 +62,31 @@ Orchestrator for the full issue lifecycle: investigate → decompose (if needed)
 
 ---
 
-## Multi-Repo Support
+## Project Configuration
 
-| Input | Resolves To | GH_REPO | STAGING_BRANCH |
-|-------|-------------|---------|----------------|
-| `123` / `#123` | AlterLab (default) | `RapierCraft/AlterLab` | `staging` |
-| `mcp:5` | MCP Server | `RapierCraft/alterlab-mcp-server` | `main` |
-| `n8n:12` | n8n Node | `RapierCraft/n8n-nodes-alterlab` | `main` |
+Read `forge.yaml` from the repository root before processing any issue.
 
-Satellite repos (MCP, n8n) have no staging — fast-lane PRs go to `main`.
+If `forge.yaml` is missing: stop and tell the user to run `npx forgedock init` to generate it.
+
+**Resolve these values from `forge.yaml`**:
+
+| Variable | Source field | Notes |
+|----------|-------------|-------|
+| `GH_REPO` | `project.owner` + `/` + `project.repo` | e.g. `acme-org/acme-platform` |
+| `GH_FLAG` | `-R {GH_REPO}` | Passed to all `gh` commands |
+| `REPO_PATH` | `paths.root` | Absolute path to repo root |
+| `WORKTREE_BASE` | `paths.worktree_base` | Base dir for git worktrees |
+| `STAGING_BRANCH` | `branches.staging` | Fast-lane PR target |
+| `PROJECT_BOARD_OWNER` | `project_board.owner` (or `project.owner` as fallback) | For `gh project` commands |
+| `PROJECT_BOARD_NUMBER` | `project_board.project_number` (or `1` as fallback) | Project number in `gh project` commands |
+
+**Multi-repo routing** (when `forge.yaml → repos` section is present):
+
+Parse issue input for a prefix (`<prefix>:<number>`). Look up `<prefix>` in `forge.yaml → repos.satellites[]`. Use that satellite's `repo` and `staging_branch` as `GH_REPO` and `STAGING_BRANCH`. If no prefix is given, use the default (`project.owner/project.repo`).
+
+If `forge.yaml → repos` is absent, only the default repo is available — prefixed issue numbers are invalid.
+
+Satellite repos (those without a `staging` branch) receive fast-lane PRs directly to `main`.
 
 ---
 
@@ -100,12 +116,12 @@ Add issue to project, set Status=In Progress, Lane, Component, Priority, Workflo
 
 ## Phase 1: Investigation
 
-**Skip if**: `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->` in the SAME comment.
+**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->` in the SAME comment.
 
 **Partial investigation**: If investigator comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted. Delete the partial comment and restart:
 ```bash
 COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .id')
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .id')
 gh api repos/{GH_REPO}/issues/comments/$COMMENT_ID -X DELETE
 ```
 
@@ -171,20 +187,14 @@ Mission: Validate whether the issue is real. Assume description is wrong until p
 
 **Resolve target repo and branch**:
 
-For Forge issues (repo = `RapierCraftStudios/forge`):
-- Key files: `commands/work-on.md`, `commands/review-pr.md`, `commands/quality-gate.md`, `commands/orchestrate.md`, `install.sh`, `CLAUDE.md`
+Read `forge.yaml → review.tech_stack` and `forge.yaml → review.key_paths` (if present) to identify which files are most relevant for the affected domain. If the `review` section is absent, use the issue labels, title keywords, and the affected files listed in the issue body to determine the domain. Start with the files the issue explicitly names, then expand to callers and related modules.
+
+**Workflow pipeline issues** (repo is a ForgeDock installation):
+- Key files: `commands/work-on.md`, `commands/review-pr.md`, `commands/quality-gate.md`, `commands/orchestrate.md`, `forge.yaml`, `bin/forgedock.mjs`
 
-For AlterLab issues (repo = `RapierCraft/AlterLab`):
+**Application issues** (all other repos):
 
-| Domain | Key files |
-|--------|-----------|
-| 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`, `infra/traefik/` |
+Use `forge.yaml → review.tech_stack` and the issue domain labels to identify entry points. If `forge.yaml → review.key_paths` lists domain-to-file mappings, use that table directly. Otherwise, infer key files from the issue body's Affected Files section.
 
 **INFRA domain known footguns** (read before writing any `.github/workflows/*.yml` changes):
 - **appleboy/ssh-action Go template preprocessing**: Any `{{` in a `script:` block is interpreted as a Go template directive **before the script reaches SSH**. This means `docker ps --format '{{.Names}}'` and `docker inspect --format '{{index .RepoTags 0}}'` will crash the action with exit 1. Both function calls (`{{index .X Y}}`) AND field accessors (`{{.Names}}`, `{{.Status}}`) fail on the action's empty data context. Shell error handlers (`|| fallback`, `set -e`, `2>/dev/null`) are bypassed because the failure is client-side. Always use `docker inspect IMAGE | jq -r '.[0].RepoTags[0]'` and `docker ps --format json | jq -r '.Names'` patterns in `appleboy/ssh-action` scripts. (Ref: forge#226 — 6-day silent deploy failure masked by `continue-on-error: true`)
@@ -194,11 +204,10 @@ For AlterLab issues (repo = `RapierCraft/AlterLab`):
 2. Read domain files — start with key files for the affected domain
 2.5. **Existing system search (conditional)**: If the issue describes a gap in a functional capability — content not being distributed, notifications not sending, jobs not running, data not being synced — MUST search for an existing automated system before proposing a new one. The issue body may name a specific tool or path (e.g., `reddit-bot/`, `marketing/`) — do NOT anchor on that path alone. Expand the search to all service layers:
    ```bash
-   # For AlterLab: check Herald, worker, and scheduler for the capability
-   grep -rn "{capability_keyword}" services/herald/app/scheduler/ services/herald/app/content/ services/worker/
-   grep -rn "{capability_keyword}" services/ --include="*.py" -l | head -20
+   # Check all service layers for the capability (adapt paths to your project structure)
+   grep -rn "{capability_keyword}" {REPO_PATH}/services/ --include="*.py" -l | head -20
    # Look for scheduled jobs, automated runners, existing integrations
-   grep -rn "scheduler\|celery\|cron\|nightly\|periodic" services/ --include="*.py" -l | head -10
+   grep -rn "scheduler\|celery\|cron\|nightly\|periodic" {REPO_PATH}/services/ --include="*.py" -l | head -10
    ```
    If an existing system is found that already handles the capability: the fix MUST route through the existing system (fix its config, env var, or gate) — NOT create a new parallel tool. Document the existing system in the investigation report and make it the centerpiece of the recommendation. This check is especially critical when the issue references a standalone tool directory (`reddit-bot/`, `scripts/`, `tools/`) — those directories often duplicate functionality that a service already owns. (Ref: forge#279 — investigator anchored on `reddit-bot/` from issue body, never checked `services/herald/app/scheduler/`, built parallel PRAW integration alongside Herald's existing automated crosspost scheduler)
 3. Verify claims — does the code actually have the problem described?
@@ -308,13 +317,13 @@ gh issue close {NUMBER} {GH_FLAG} --comment "Closing as invalid: {reason from in
 ```bash
 gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 ```
 
 **MANDATORY — Owner override detection**: After reading the investigation comment, read ALL comments on the issue to check for owner override signals:
 ```bash
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR")) | not) | {author: .user.login, body: .body}'
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR") | not) | {author: .user.login, body: .body}'
 ```
 
 Scan non-agent comments for override signals — phrases like "do not", "do NOT", "instead", "revert", "remove this", "override", "actually", or explicit disagreement with the investigation's recommendation. If an override comment is found from a repo owner or admin (not a bot):
@@ -402,7 +411,7 @@ gh issue edit {NUMBER} {GH_FLAG} \
 
 <!-- FORGE:PHASE_COMPLETE — Entering Phase 3 (Build). See Universal Phase Dispatcher: sub-phases 3A–3M execute in sequence. No sub-phase completion is terminal. -->
 
-**Skip if**: `<!-- FORGE:BUILDER -->` or `<!-- ALTERLAB:BUILDER -->` exists.
+**Skip if**: `<!-- FORGE:BUILDER -->` exists.
 
 **CRITICAL: You MUST execute ALL sub-phases 3A–3M in order. Do NOT skip phases 3C.5 (context) or 3C.6 (architect) — they post mandatory `FORGE:CONTEXT` and `FORGE:ARCHITECT` comments that Phase 3F reads as its primary input. Skipping them degrades build quality and causes review findings. After each sub-phase, continue to the next — no sub-phase is terminal.**
 
@@ -412,11 +421,11 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 
 # Read investigation report
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 
 # Check if build already completed
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body'
+  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body'
 ```
 
 If no investigation comment with `<!-- INVESTIGATION:COMPLETE -->` → STOP (investigation not complete).
@@ -745,7 +754,7 @@ black {PYTHON_FILES} && isort {PYTHON_FILES} && python -m py_compile {PYTHON_FIL
 ```
 `py_compile` failures are BLOCKING.
 
-**TypeScript (AlterLab)**:
+**TypeScript (primary repo — has tsconfig.json)**:
 ```bash
 cd {WORKTREE_PATH}
 prettier --write {TS_FILES} && tsc --noEmit
@@ -984,13 +993,16 @@ If multi-phase (`HAS_PHASE_HEADINGS > 0` AND `REMAINING_BEFORE > 0`): do NOT che
 If single-phase or final phase: check off all `[ ]` items, add PR reference.
 
 ### 6B: Project board update (Status=Done, Workflow=Merged)
+
+Resolve `PROJECT_BOARD_OWNER` and `PROJECT_BOARD_NUMBER` from `forge.yaml → project_board` (fields: `owner`, `project_number`). Fall back to `forge.yaml → project.owner` and project number `1` if `project_board` section is absent.
+
 ```bash
 ISSUE_URL="https://github.com/{GH_REPO}/issues/{NUMBER}"
-ITEM_ID=$(gh project item-list 1 --owner RapierCraft --format json --limit 200 \
+ITEM_ID=$(gh project item-list {PROJECT_BOARD_NUMBER} --owner {PROJECT_BOARD_OWNER} --format json --limit 200 \
   --jq ".items[] | select(.content.url == \"$ISSUE_URL\") | .id" 2>/dev/null | head -1)
 ```
 
-If found: set Status=Done, Workflow=Merged using project field IDs.
+If found: set Status=Done, Workflow=Merged using project field IDs from `forge.yaml → project_board.field_ids`.
 
 ### 6C: Ensure issue is closed
 

package/docs/CODEX.md

@@ -69,7 +69,7 @@ When a repo-local adapter exists under `.agents/skills/`, it becomes authoritati
 - different default GitHub repo resolution
 - Codex-native worktree roots
 - Forge-specific review heuristics
-- best-effort handling of project-board steps that are AlterLab-specific upstream
+- best-effort handling of project-board steps that may be project-specific upstream
 
 ## Trust and Global Config