forgedock 1.1.11 → 1.3.0

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

@@ -1,6 +1,6 @@
 ---
 description: Validation agent — quality gate loop, format/verify, proxy check, deploy check
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--files FILE1 FILE2...]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--files FILE1 FILE2...]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -254,6 +254,65 @@ fi
 
 ---
 
+## Phase V3.6: Browser Signal Check
+
+**Skip if**: No TypeScript/TSX files were changed, OR `forge.yaml → services.app_url` is absent or empty.
+
+After static proxy checks, run a lightweight live browser check using Playwright MCP tools to surface console errors, failed network requests, and basic performance metrics for any changed UI routes. This check is advisory — findings are surfaced as warnings in the V5 summary but do NOT block the gate unless the browser session is available AND returns ERROR-level console output.
+
+```bash
+cd {WORKTREE_PATH}
+APP_URL=$(yq '.services.app_url // ""' forge.yaml 2>/dev/null || echo '')
+if [ -z "$APP_URL" ]; then
+    echo "SKIPPED — services.app_url not configured in forge.yaml (browser signal check requires a running app URL)"
+else
+    echo "BROWSER SIGNAL CHECK: navigating $APP_URL"
+fi
+```
+
+**When APP_URL is configured**, perform the following using Playwright MCP tools:
+
+**Step 1 — Navigate**
+Use `browser_navigate` to load `{APP_URL}`. If the changed files include a specific page route (e.g., `web/src/app/dashboard/page.tsx`), derive the route path and navigate there instead (e.g., `{APP_URL}/dashboard`).
+
+**Step 2 — Capture console messages**
+```
+browser_console_messages
+```
+Classify findings:
+- Any message at `error` level → **MEDIUM** finding: `BROWSER-CONSOLE-ERROR | MEDIUM | console | {message}`
+- Any message at `warn` level → **LOW** advisory: `BROWSER-CONSOLE-WARN | LOW | console | {message}`
+- Ignore `info` and `log` levels
+
+**Step 3 — Capture network failures**
+```
+browser_network_requests filter="static:false"
+```
+Check for HTTP 4xx and 5xx responses on non-static requests. Exclude known third-party analytics/tracking domains.
+- HTTP 4xx or 5xx response → **HIGH** finding: `BROWSER-NETWORK-FAIL | HIGH | network | {url} returned {status}`
+
+**Step 4 — Capture performance metrics (LCP-ish)**
+```
+browser_evaluate function="() => {
+  const nav = performance.getEntriesByType('navigation')[0];
+  const paint = performance.getEntriesByType('paint');
+  const fcp = paint.find(e => e.name === 'first-contentful-paint');
+  return {
+    domContentLoaded: nav ? Math.round(nav.domContentLoadedEventEnd) : null,
+    loadTime: nav ? Math.round(nav.loadEventEnd) : null,
+    fcp: fcp ? Math.round(fcp.startTime) : null
+  };
+}"
+```
+Classify:
+- `loadTime > 4000` ms → **HIGH** finding: `BROWSER-PERF | HIGH | performance | page load time {loadTime}ms exceeds 4s threshold`
+- `loadTime > 2500` ms → **MEDIUM** finding: `BROWSER-PERF | MEDIUM | performance | page load time {loadTime}ms exceeds 2.5s threshold`
+- `fcp > 1800` ms → **LOW** advisory: `BROWSER-PERF | LOW | performance | FCP {fcp}ms — consider lazy-loading or code splitting`
+
+**Advisory scope**: Browser signal findings are included in the V5 summary under "Browser Signals". They do NOT block the gate (GATE_PASSED stays true) unless a BROWSER-NETWORK-FAIL HIGH finding is present on the primary app URL (indicating the app is completely broken for that route). Console ERROR findings are MEDIUM — surfaced for human review, not blocking.
+
+---
+
 ## Phase V4: Deployment Completeness Check
 
 **Skip if**: No new environment variables were introduced in the changed files.
@@ -304,6 +363,8 @@ Where `{SCOPE}` is the command or module scope from the contract (e.g. `work-on`
 
 This is the **only** commit for this build cycle. It replaces the old `git commit` that was previously in `implement.md` Phase I4. Do NOT create a separate commit for validation fixes — they are absorbed into this single commit.
 
+**Attribution**: The commit message is exactly the conventional-commit line above — nothing more. Do NOT append a `Co-Authored-By: Claude` trailer, a `🤖 Generated with Claude Code` line, or any assistant-tool attribution. Pipeline output is ForgeDock-branded; the assistant signature must never enter the repo's commit history. (A PreToolUse guard hard-blocks it as a backstop — see `bin/hooks/pre-tool-use.mjs` Rule 5.)
+
 ### V5 Post-Commit Ancestry Audit (MANDATORY)
 
 After committing, run the ancestry audit to detect merge commits from unrelated branches before the branch is pushed:
@@ -396,9 +457,10 @@ This module runs at **Step 3F.5** — after implement, before commit (3J) and PR
 
 ```
 3F  → Implement (by implement.md) — code written, staged (not committed)
-3F.5 → [THIS MODULE] Validate — gate loop, format, proxy, deploy checks
+3F.5 → [THIS MODULE] Validate — gate loop, format, proxy, browser signals, deploy checks
 3G  → (covered by Phase V2 above)
 3H  → (covered by Phase V3 above)
+3H.5 → (covered by Phase V3.6 above — browser signal check for UI changes)
 3I  → (covered by Phase V4 above)
 3J  → V5 commit happens here after GATE_PASSED=true (single commit for implementation + any fixes)
 ```

package/commands/work-on/build.md

@@ -1,6 +1,6 @@
 ---
 description: Build subcommand — create worktree, post contract, sequence context/architect/implement/validate
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -154,6 +154,13 @@ gh issue edit {NUMBER} {GH_FLAG} \
 
 Post `<!-- FORGE:CONTRACT -->` comment documenting what will be built and why:
 
+**Before posting, read the attribution config**:
+```bash
+SHOW_ATTRIBUTION=$(yq '.branding.show_attribution // "true"' forge.yaml 2>/dev/null || echo "true")
+[ "$SHOW_ATTRIBUTION" = "false" ] && ATTRIBUTION_LINE="" || ATTRIBUTION_LINE="
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)"
+```
+
 ```bash
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CONTRACT -->
 ## Builder Contract
@@ -180,7 +187,8 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CONTRACT -->
 
 ### Out of Scope
 
-{OUT_OF_SCOPE_ITEMS}"
+{OUT_OF_SCOPE_ITEMS}
+${ATTRIBUTION_LINE}"
 ```
 
 Contract must be grounded in the investigation report. Every deliverable file must appear in the affected files list from the investigator. Adversarially validate the proposed fix against adjacent system layers before posting.

package/commands/work-on/close.md

@@ -1,6 +1,6 @@
 ---
 description: Close subcommand — update project board, final issue body, parent tracker, summary report, trajectory log
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/work-on/decompose.md

@@ -1,6 +1,6 @@
 ---
 description: Decompose subcommand — break a complex issue into ordered sub-issues, post FORGE:DECOMPOSED, stop
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -106,30 +106,14 @@ For each sub-issue, prepare:
 
 ## Phase D3: Create Sub-Issues
 
-For each sub-issue (in dependency order):
+For each sub-issue (in dependency order), route creation through the `/issue` create-hook's programmatic invocation contract (`commands/issue.md` Programmatic Invocation Contract, added in #2085) instead of calling `gh issue create` directly. `/issue`'s Phase 2D runs the same `scripts/issue-dedup.sh` check this file used to run manually — the standalone pre-check below is removed; dedup is now enforced inside the create-hook on every call, with no bypass path. <!-- Changed: forge#2086 — route through /issue create-hook -->
 
-**Before creating each sub-issue, run the deterministic dedup check:** <!-- Added: forge#1335 -->
+**Compose the sub-issue body to a temp file** (avoids quoting issues when passed as `--body-file`):
 
 ```bash
 SUB_TITLE="{fix|feat|refactor}: {SUB_ISSUE_TITLE}"
-DEDUP_RESULT=$(scripts/issue-dedup.sh "$SUB_TITLE" {GH_FLAG} 2>&1)
-DEDUP_EXIT=$?
-if [ "$DEDUP_EXIT" -eq 1 ]; then
-  echo "DEDUP: Sub-issue near-duplicate detected — $DEDUP_RESULT"
-  echo "Skipping creation. Comment on the existing issue instead."
-  # Do NOT call gh issue create for this sub-issue
-elif [ "$DEDUP_EXIT" -eq 2 ]; then
-  echo "DEDUP: Usage error — $DEDUP_RESULT"
-  # Do NOT call gh issue create for this sub-issue — fix the invocation and retry
-fi
-```
-
-Only call `gh issue create` when the dedup script exits 0 (no match):
-
-```bash
-gh issue create {GH_FLAG} \
-  --title "{fix|feat|refactor}: {SUB_ISSUE_TITLE}" \
-  --body "$(cat <<'SUB_BODY_EOF'
+SUB_BODY_FILE="$(mktemp)"
+cat > "$SUB_BODY_FILE" <<'SUB_BODY_EOF'
 ## Problem
 
 {1-3 sentences: what this sub-issue specifically addresses. What's wrong or what needs to be built for this sub-task.}
@@ -155,11 +139,30 @@ Files that need changes:
 **Parent**: #{NUMBER}
 {If depends on another sub-issue: "**Depends on**: #{SUB_ISSUE_N} — {reason}"}
 SUB_BODY_EOF
-)" \
-  --label "{PRIORITY_LABEL}" \
-  --milestone "{MILESTONE_TITLE}"
 ```
 
+**Invoke `/issue` in programmatic mode**:
+
+```
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"${SUB_TITLE}\" --body-file \"${SUB_BODY_FILE}\" --label \"{PRIORITY_LABEL}\" --milestone \"{MILESTONE_TITLE}\""))
+```
+
+`/issue` runs Phase 2D dedup, Phase 3F body validation, then creates the issue (Phase 4) — no separate pre-check needed on this side.
+
+**Extract the created sub-issue number from the Skill output** (see `commands/issue.md` Phase 4C/4E — it echoes `Created: {url}` and reports `**#{NUMBER}**: {title}`):
+
+```bash
+# Match either the "Created: {url}" line (extract trailing /issues/N) or the "**#{NUMBER}**" bold report line.
+SUB_NUMBER=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE 'issues/[0-9]+' | head -1 | grep -oE '[0-9]+')
+[ -z "$SUB_NUMBER" ] && SUB_NUMBER=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE '\*\*#[0-9]+\*\*' | head -1 | grep -oE '[0-9]+')
+
+if [ -z "$SUB_NUMBER" ]; then
+  echo "WARNING: /issue did not report a created issue number for sub-issue '${SUB_TITLE}' — likely a Phase 2D dedup STOP (near-duplicate found) or a usage error. Skipping this sub-issue: do not reference it in the parent tracker or in dependent sub-issue bodies. Review the Skill output above and, if a near-duplicate exists, comment on the existing issue instead."
+fi
+```
+
+If `SUB_NUMBER` is empty, treat this sub-issue as not created — do not add it to the parent tracker checklist (Phase D4) and do not reference it as a dependency in later sub-issues.
+
 **Append Prior Investigation section** (conditional — only if `GIST_URLS` from Phase D1.5 is non-empty):
 
 After creating each sub-issue, append the `## Prior Investigation` section containing all parent Gist URLs. This keeps the Gist references machine-readable for downstream agents.
@@ -215,6 +218,13 @@ gh issue edit {NUMBER} {GH_FLAG} --body "${CURRENT_BODY}${TRACKER}"
 
 ## Phase D5: Post FORGE:DECOMPOSED Comment
 
+**Before posting, read the attribution config**:
+```bash
+SHOW_ATTRIBUTION=$(yq '.branding.show_attribution // "true"' forge.yaml 2>/dev/null || echo "true")
+[ "$SHOW_ATTRIBUTION" = "false" ] && ATTRIBUTION_LINE="" || ATTRIBUTION_LINE="
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)"
+```
+
 ```bash
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:DECOMPOSED -->
 ## Decomposition Complete
@@ -229,7 +239,7 @@ This issue has been broken into sub-issues. Each sub-issue runs through its own
 ### Decomposition Rationale
 
 {brief summary of why this issue was decomposed and the dependency ordering chosen}
-
+${ATTRIBUTION_LINE}
 <!-- FORGE:DECOMPOSED:COMPLETE -->"
 ```
 

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 {owner}/{repo}] [--gh-flag "-R {owner}/{repo}"]
+argument-hint: "[issue number] [--repo {owner}/{repo}] [--gh-flag \"-R {owner}/{repo}\"]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -380,7 +380,7 @@ if [ "$ATTRIBUTION_ANNOTATION_LINK" = "true" ]; then
   ANNOTATION_LINK_FOOTER="
 
 ---
-*Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)*"
+*⚒️ Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)*"
 fi
 ```
 

package/commands/work-on/remediate.md

@@ -1,6 +1,6 @@
 ---
 description: Remediate subcommand — checkout a needs-human PR, fix review findings, re-review, and re-gate with a FORGE:REMEDIATION paper trail
-argument-hint: [PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]
+argument-hint: "[PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/work-on/review.md

@@ -1,6 +1,6 @@
 ---
 description: Review subcommand — push branch, create PR, invoke /review-pr with --auto-merge
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH] [--base PR_BASE]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH] [--base PR_BASE]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -159,7 +159,7 @@ ATTRIBUTION_PR_FOOTER=$(grep -A5 "^attribution:" forge.yaml 2>/dev/null | grep "
 If `ATTRIBUTION_PR_FOOTER` is `true`, append the following footer to the PR body (once — never duplicate on retries):
 
 ```
-> Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.
+> ⚒️ Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.
 ```
 
 ### R2C: Create PR
@@ -188,13 +188,15 @@ Closes #{NUMBER}
 **Implementation branch**: \`{BRANCH}\`
 **Base**: \`{PR_BASE}\`
 {IF_ATTRIBUTION_PR_FOOTER_TRUE:
-> Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.}"
+> ⚒️ Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.}"
 ```
 
 **Note**: `Closes #{NUMBER}` documents intent but does NOT auto-close for non-default-branch PRs. The close subcommand handles explicit closure after merge.
 
 **Attribution guard**: The footer line is appended once at PR creation. If the PR already exists (resume path), do NOT append the footer again — check the existing PR body first.
 
+**No assistant attribution**: The PR body is exactly the sections above (plus the optional ForgeDock footer). Do NOT add a `🤖 Generated with Claude Code` line, a `Co-Authored-By: Claude` trailer, or any assistant-tool attribution — the pipeline is ForgeDock-branded. A PreToolUse guard hard-blocks it as a backstop (`bin/hooks/pre-tool-use.mjs` Rule 5).
+
 If PR creation fails because a PR already exists for this branch:
 ```bash
 gh pr list {GH_FLAG} --head {BRANCH} --json number,url --jq '.[0]'

package/commands/work-on-monolithic.md

@@ -1,6 +1,6 @@
 ---
 description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
-argument-hint: [issue number]
+argument-hint: "[issue number]"
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/work-on.md

@@ -1,6 +1,6 @@
 ---
 description: Pick up a GitHub issue and run the full investigate-build-review-merge pipeline
-argument-hint: [issue number or "next" to pick highest priority]
+argument-hint: "[issue number or \"next\" to pick highest priority]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -926,10 +926,18 @@ For each sub-issue:
 - **Milestone**: same as parent
 
 ### 2C: Create sub-issues
+
+Route through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` § "Programmatic Invocation Contract") instead of calling the raw issue-creation command directly — this gets dedup (Phase 2D) and body validation (Phase 3F) for free on every decomposition-spawned sub-issue.
+
 ```bash
-gh issue create {GH_FLAG} \
-  --title "{fix|feat|refactor}: {SUB_ISSUE_TITLE}" \
-  --body "$(cat <<'SUB_BODY_EOF'
+SUB_ISSUE_TITLE_FULL="{fix|feat|refactor}: {SUB_ISSUE_TITLE}"
+# Defense-in-depth: /issue's arg tokenizer (commands/issue.md, forge#2094) uses
+# an xargs-based tokenizer that never expands backtick/$(...) substitution, so
+# this is no longer required for safety — but strip it anyway so the raw title
+# stays readable if it round-trips through any other eval-based consumer.
+SUB_ISSUE_TITLE_FULL=$(printf '%s' "$SUB_ISSUE_TITLE_FULL" | tr '`' "'" | sed 's/\$(/$ (/g')
+SUB_ISSUE_BODY_FILE=$(mktemp)
+cat <<'SUB_BODY_EOF' > "$SUB_ISSUE_BODY_FILE"
 ## Problem
 
 {1-3 sentences: what this sub-issue specifically addresses. What's wrong or what needs to be built.}
@@ -955,9 +963,22 @@ Files that need changes:
 **Parent**: #{NUMBER}
 {If depends on another sub-issue: "**Depends on**: #{SUB_ISSUE_N} — {reason}"}
 SUB_BODY_EOF
-)" \
-  --label "{PRIORITY_LABEL}" \
-  --milestone "{MILESTONE_TITLE}"
+
+# --milestone is only passed when the parent has one (see Phase 2B — "Milestone: same as parent").
+MILESTONE_ARG=""
+[ -n "{MILESTONE_TITLE}" ] && MILESTONE_ARG="--milestone \"{MILESTONE_TITLE}\""
+Skill(skill="issue", args="--title \"$SUB_ISSUE_TITLE_FULL\" --body-file \"$SUB_ISSUE_BODY_FILE\" --label \"{PRIORITY_LABEL}\" ${MILESTONE_ARG}")
+rm -f "$SUB_ISSUE_BODY_FILE"
+
+# /issue has no machine-readable return contract — resolve the created issue's number by
+# exact-title search immediately after the call (used by Phase 2D's tracker checklist).
+# Retry to absorb GitHub Search API indexing lag.
+SUB_ISSUE_NUM=""
+for _resolve_attempt in 1 2 3; do
+  SUB_ISSUE_NUM=$(gh issue list {GH_FLAG} --search "in:title \"${SUB_ISSUE_TITLE_FULL}\"" --state open --limit 1 --json number --jq '.[0].number // empty')
+  [ -n "$SUB_ISSUE_NUM" ] && break
+  sleep 2
+done
 ```
 
 ### 2D: Update parent issue body

package/docs/AIDER.md

@@ -0,0 +1,264 @@
+# Aider Support
+
+ForgeDock has an additive Aider-native install path. The goal is to give Aider
+users access to the ForgeDock pipeline without regressing the existing Claude
+Code or Codex setups.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the workflow spec for all runtimes
+
+Claude Code wrapper:
+- `install.sh` (or `npx forgedock`) symlinks command files into `~/.claude/commands/`
+
+Codex wrapper:
+- `install-codex.sh` generates namespaced skills in `~/.codex/skills/`
+
+**Aider wrapper** (this document):
+- `install-aider.sh` writes `~/.aider-forge.md` — a conventions file Aider
+  loads at session start via `--read`
+- The conventions file provides runtime mapping rules and entry point references
+- Aider reads ForgeDock command specs on demand with `/read $FORGE_HOME/commands/x.md`
+
+This is intentionally a conventions-file architecture, not a duplicate command
+tree. The shared `commands/` directory remains the single source of truth.
+
+## Install
+
+### Option A — standalone bash installer
+
+```bash
+cd /path/to/forgedock
+./install-aider.sh
+```
+
+This writes `~/.aider-forge.md` with ForgeDock conventions and runtime mapping
+rules.
+
+### Option B — via npx forgedock
+
+If you already use `npx forgedock` for Claude Code:
+
+```bash
+npx forgedock
+```
+
+When `aider` is detected on your PATH, `npx forgedock` writes `~/.aider-forge.md`
+as an additional install step. No existing Claude Code files are affected.
+
+## Usage
+
+### Per-session (command line)
+
+```bash
+aider --read ~/.aider-forge.md
+```
+
+### Always-on (`.aider.conf.yml`)
+
+Add to your project's `.aider.conf.yml`:
+
+```yaml
+read:
+  - ~/.aider-forge.md
+```
+
+Or to `~/.aider.conf.yml` for global application across all projects.
+
+### Loading a pipeline command
+
+Once Aider has the conventions file loaded, load a command spec on demand:
+
+```
+/read /path/to/forgedock/commands/work-on.md
+```
+
+Then follow the command spec step by step, using `/run` for all shell
+operations.
+
+## Tool Translation Rules
+
+ForgeDock command specs reference Claude Code-specific tools. Translate them
+to Aider equivalents:
+
+| Claude Code | Aider equivalent | Notes |
+|-------------|-----------------|-------|
+| `Skill("work-on", args="123")` | `/read $FORGE_HOME/commands/work-on.md` | Load the spec and execute it |
+| `Skill("review-pr", args="456")` | `/read $FORGE_HOME/commands/review-pr.md` | Load the spec and execute it |
+| `Skill("quality-gate")` | `/read $FORGE_HOME/commands/quality-gate.md` | Load the spec and execute it |
+| `Bash("git status")` | `/run git status` | Direct shell execution |
+| `Read("path/to/file")` | Read the file directly | Aider's native file read |
+| `Grep(pattern, path)` | `/run rg 'pattern' path` | Use `rg` (ripgrep) |
+| `Glob("**/*.md")` | `/run find . -name "*.md"` | Shell find |
+| `WebFetch(url)` | `/run curl -s url` | curl or wget |
+| `Agent(...)` / `Task(...)` | Continue the sub-task yourself | No sub-agent support; inline it |
+| `EnterWorktree(path)` | `/run cd path` then use `/run` | Work in worktree directory |
+
+### Nested Skill references
+
+When a command spec calls `Skill("x")` or references another command:
+
+```
+# Load the referenced command spec manually:
+/read $FORGE_HOME/commands/x.md
+```
+
+Map command names to file paths:
+- `Skill("work-on")` → `commands/work-on.md`
+- `Skill("review-pr")` → `commands/review-pr.md`
+- `Skill("quality-gate")` → `commands/quality-gate.md`
+- `Skill("orchestrate")` → `commands/orchestrate.md`
+
+## GitHub Operations
+
+All FORGE annotations are written to GitHub issue/PR comments via the `gh`
+CLI. Use `/run gh ...` for every GitHub operation.
+
+### Label management
+
+```bash
+/run gh issue edit 123 -R OWNER/REPO --add-label "workflow:investigating"
+/run gh issue edit 123 -R OWNER/REPO --remove-label "workflow:investigating"
+```
+
+### Reading existing annotations
+
+```bash
+/run gh api repos/OWNER/REPO/issues/123/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
+```
+
+### Writing a FORGE annotation comment
+
+```bash
+/run gh issue comment 123 -R OWNER/REPO --body "<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+
+**Verdict**: CONFIRMED
+...
+<!-- INVESTIGATION:COMPLETE -->"
+```
+
+For multi-line comment bodies, write the content to a temp file first:
+
+```bash
+cat > /tmp/comment.md << 'EOF'
+<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+...
+<!-- INVESTIGATION:COMPLETE -->
+EOF
+/run gh issue comment 123 -R OWNER/REPO --body "$(cat /tmp/comment.md)"
+```
+
+### Creating a PR
+
+```bash
+/run gh pr create -R OWNER/REPO \
+  --base staging \
+  --head feat/my-branch-123 \
+  --title "feat: description (#123)" \
+  --body "$(cat /tmp/pr_body.md)"
+```
+
+## Worktrees
+
+ForgeDock uses git worktrees to isolate branch work. Create one with:
+
+```bash
+/run git fetch origin
+/run git worktree add .claude/worktrees/feat-my-feature-123 \
+  -b feat/my-feature-123 origin/staging
+```
+
+Work inside the worktree for all file edits and commits. Aider's `/run`
+commands execute in the worktree directory if you `cd` to it:
+
+```bash
+/run cd /path/to/repo/.claude/worktrees/feat-my-feature-123
+```
+
+Or pass the path explicitly in each command:
+
+```bash
+/run git -C /path/to/repo/.claude/worktrees/feat-my-feature-123 status
+```
+
+## FORGE Annotation Protocol
+
+Every pipeline stage writes a structured annotation to GitHub. Key rules:
+
+1. **Idempotency**: Check for existing annotations BEFORE starting a phase.
+   Do not re-run a completed phase.
+2. **Compaction resilience**: Write annotations AFTER completing each
+   significant step. GitHub is the persistent state layer.
+3. **Restart partial annotations**: If an annotation exists without its
+   `:COMPLETE` sentinel, delete it and restart the phase.
+4. **Respect label state**: Labels track workflow state. Read and set them
+   at each phase boundary.
+
+### Label state machine
+
+```
+workflow:investigating
+    → workflow:ready-to-build   (investigation complete)
+    → workflow:building         (build started)
+    → workflow:in-review        (PR created)
+    → workflow:merged           (PR merged) [TERMINAL]
+
+workflow:invalid                [TERMINAL]
+workflow:decomposed             [TERMINAL]
+needs-human                     [TERMINAL]
+```
+
+Stop the pipeline when any terminal label is set.
+
+## Feasibility Analysis
+
+Aider is the highest-feasibility non-Claude agent for ForgeDock because:
+
+| Capability | Requirement | Aider support |
+|-----------|-------------|---------------|
+| Load instruction files | `--read` flag / `.aider.conf.yml` | Native |
+| Execute shell commands | `gh`, `git`, `rg` via shell | `/run` command |
+| Read/write files | File editing | Native |
+| GitHub API | `gh` CLI | Via `/run gh ...` |
+| Multi-step workflows | Follow sequential instructions | Supported |
+| Compaction resilience | Re-read GitHub state at phase start | Supported (via `/run gh ...`) |
+
+**Limitation**: Aider has no native sub-agent/parallel task model (`Agent(...)`,
+`Task(...)`). Phase 3 parallel context gathering (`FORGE:CONTEXT`) and
+multi-agent review (`review-pr-agents.md`) must be executed sequentially.
+For the orchestrate command (`/orchestrate`), run one issue at a time or
+use separate Aider sessions per issue.
+
+## Trust and Configuration
+
+Aider does not have a project trust model. Once `~/.aider-forge.md` is loaded,
+all operations in that session have access to shell execution via `/run`.
+
+**Security note**: ForgeDock's shell operations are limited to `gh`, `git`,
+`rg`, `find`, and standard POSIX tools. The conventions file does not execute
+arbitrary code at load time — it only provides instruction text.
+
+## Usage Notes
+
+- Use `--read ~/.aider-forge.md` on every session, or add it to
+  `.aider.conf.yml` for automatic loading.
+- Load command specs on demand with `/read $FORGE_HOME/commands/x.md` —
+  do not load all commands at once.
+- Keep `CLAUDE.md` and `AGENTS.md` aligned with ForgeDock conventions;
+  Aider and Claude Code can differ at the wrapper layer but not on FORGE
+  workflow invariants (annotation format, label state machine, branch
+  naming, worktree conventions).
+- For pipeline stages that post FORGE annotations, always write the body
+  to a temp file before passing to `gh issue comment` to avoid shell
+  quoting issues with multi-line content.
+
+## Reference
+
+- [FORGE Protocol spec](FORGE-PROTOCOL.md) — annotation format, label state machine, conformance tests
+- [Codex adapter](CODEX.md) — parallel reference for OpenAI Codex CLI
+- [Pipeline commands](../commands/) — shared workflow specs (authoritative for all runtimes)
+- [`install-aider.sh`](../install-aider.sh) — installer script