docs: defer branch to copilot instructions

.gemini/GEMINI.md

@@ -4,11 +4,9 @@ This file provides guidance to Gemini agents when working with code in this repo
 
 ## Configuration
 
-<!-- BRANCH PARAMETER: Change this value to load instructions from a different branch -->
-<!-- Valid values: main, optimization, feature/*, or any valid branch name -->
-**Active Branch:** `main`
+**Branch:** MUST be read from [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
-All remote URLs in this document use the configured branch above. Replace `{branch}` placeholders with the active branch value.
+All remote URLs in this document use the branch configured in `../.github/copilot-instructions.md`. Replace `{branch}` placeholders with that value.
 
 ## Repository Overview
 
@@ -144,7 +142,7 @@ GitHub UI: https://github.com/nam20485/agent-instructions/blob/{branch}/<file-pa
 Raw URL:   https://raw.githubusercontent.com/nam20485/agent-instructions/{branch}/<file-path>
 ```
 
-Replace `{branch}` with the configured branch from the Configuration section (default: `main`).
+Replace `{branch}` with the branch configured in [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>` (fallback: `main` only if unavailable).
 
 **Single Source of Truth:**
 - Dynamic workflows and assignments MUST be fetched from remote canonical repository
@@ -185,9 +183,9 @@ Replace `{branch}` with the configured branch from the Configuration section (de
 
 ## Branch Strategy
 
-- **Main branch:** `main` (development happens here)
-- **Development branch:** `development` (default for PRs)
-- Protected branches require feature branch + PR workflow
+- **Branch:** MUST be read from [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>`.
+- **MUST NOT:** Do not hardcode branch values in entrypoints.
+- **Common conventions:** `main` and `development` may exist, but agents must follow the configured branch.
 
 ## Important Constraints
 

.qwen/QWEN.md

@@ -4,11 +4,9 @@ This file provides guidance to Qwen agents when working with code in this reposi
 
 ## Configuration
 
-<!-- BRANCH PARAMETER: Change this value to load instructions from a different branch -->
-<!-- Valid values: main, optimization, feature/*, or any valid branch name -->
-**Active Branch:** `main`
+**Branch:** MUST be read from [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
-All remote URLs in this document use the configured branch above. Replace `{branch}` placeholders with the active branch value.
+All remote URLs in this document use the branch configured in `../.github/copilot-instructions.md`. Replace `{branch}` placeholders with that value.
 
 ## Repository Overview
 
@@ -144,7 +142,7 @@ GitHub UI: https://github.com/nam20485/agent-instructions/blob/{branch}/<file-pa
 Raw URL:   https://raw.githubusercontent.com/nam20485/agent-instructions/{branch}/<file-path>
 ```
 
-Replace `{branch}` with the configured branch from the Configuration section (default: `main`).
+Replace `{branch}` with the branch configured in [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>` (fallback: `main` only if unavailable).
 
 **Single Source of Truth:**
 - Dynamic workflows and assignments MUST be fetched from remote canonical repository
@@ -185,9 +183,9 @@ Replace `{branch}` with the configured branch from the Configuration section (de
 
 ## Branch Strategy
 
-- **Main branch:** `main` (development happens here)
-- **Development branch:** `development` (default for PRs)
-- Protected branches require feature branch + PR workflow
+- **Branch:** MUST be read from [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>`.
+- **MUST NOT:** Do not hardcode branch values in entrypoints.
+- **Common conventions:** `main` and `development` may exist, but agents must follow the configured branch.
 
 ## Important Constraints
 

AGENTS.md

@@ -4,7 +4,7 @@ Guidance for AI agents working in this repository.
 
 ## Configuration
 
-**Active Branch:** `main` <!-- Change for: main, optimization, feature/* -->
+**Branch:** MUST be read from [`.github/copilot-instructions.md`](.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
 ## Quick Start
 

CLAUDE.md

@@ -4,8 +4,7 @@ Guidance for Claude Code (claude.ai/code).
 
 ## Configuration
 
-<!-- BRANCH: Change to load from different branch (main, optimization, feature/*) -->
-**Active Branch:** `main`
+**Branch:** MUST be read from [`.github/copilot-instructions.md`](.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
 ## Instructions
 

GEMINI.md

@@ -4,7 +4,7 @@ Guidance for Gemini.
 
 ## Configuration
 
-**Active Branch:** `main`
+**Branch:** MUST be read from [`.github/copilot-instructions.md`](.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
 ## Instructions
 

QWEN.md

@@ -4,7 +4,7 @@ Guidance for Qwen.
 
 ## Configuration
 
-**Active Branch:** `main`
+**Branch:** MUST be read from [`.github/copilot-instructions.md`](.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
 ## Instructions
 

ai_instruction_modules/ai-core-instructions.md

@@ -129,6 +129,9 @@ prerequisites: none
 - **[Repository Summary](../ai-repo-summary.md):** High-level repo info.
 - **Core:** [Executive Summary](./ai-executive-summary.md), [Preferences](./ai-personal-preferences.md), [Quick Ref](./ai-quick-reference.md), [Workflow Config](./ai-workflow-config.md).
 
+### Expert Consultation
+- **[Agent Instructions Expert](./agent/agent-instructions-expert.md):** MUST delegate instruction/workflow lookups (workflows, assignments, canonical URLs, branch resolution rules) to this subagent.
+
 ### Optional (Activity Based)
 - **Environment:** [Local](./ai-local-environment.md), [Terminal](./ai-terminal-management.md), [PowerShell](./ai-powershell-instructions.md).
 - **Testing:** [Validation](./ai-testing-validation.md).

ai_instruction_modules/ai-shared-agent-context.md

@@ -44,6 +44,12 @@ if $condition is true:
 
 **Canonical:** `nam20485/agent-instructions`
 
+### Branch configuration authority
+
+- **MUST:** All agent-specific entrypoints MUST read `{branch}` from [`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) → `<configuration><branch>`.
+- **Fallback:** If the bootstrap config cannot be read, default to `main`.
+- **MUST NOT:** Do not hardcode branch values in entrypoints.
+
 **URL Translation:**
 - UI: `https://github.com/.../blob/{branch}/...`
 - Raw: `https://raw.githubusercontent.com/.../{branch}/...`

ai_instruction_modules/ai-workflow-assignments.md

@@ -43,6 +43,8 @@ See **[ai-workflow-development-guide.md](../ai-workflow-development-guide.md)**
 
 **Execution:** `continue-task-work`, `gather-context`, `perform-task`, `recover-from-error`, `report-progress`
 
+**Validation:** `validate-agent-instructions-expert-usage`
+
 **Review:** `create-test-cases`, `pr-approval-and-merge`, `pr-review-comments`, `request-approval`, `validate-assignment-completion`
 
 **Documentation:** `analyze-plan-issue`, `analyze-progress-doc`, `debrief-and-document`, `continuous-improvement`, `update-from-feedback`, `update-plan-issue`
@@ -55,7 +57,7 @@ See **[ai-workflow-development-guide.md](../ai-workflow-development-guide.md)**
 
 **Events:** `pre-script-begin`, `pre-assignment-begin`, `post-assignment-complete`, `post-script-complete`, `on-assignment-failure`, `on-script-failure`
 
-**Scripts:** `analyze-plan`, `breakdown-epic`, `breakdown-plan`, `create-epics-for-phase`, `create-stories-for-epic`, `design-app-outline`, `implement-by-stories`, `implement-epic`, `implement-story`, `new-project`, `optimize-plan`, `project-setup`, `project-setup-upgraded`, `review-epic-prs`, `sample-minimal`, `setup-project-and-create-app`, `single-workflow`
+**Scripts:** `analyze-plan`, `breakdown-epic`, `breakdown-plan`, `create-epics-for-phase`, `create-stories-for-epic`, `design-app-outline`, `implement-by-stories`, `implement-epic`, `implement-story`, `new-project`, `optimize-plan`, `project-setup`, `project-setup-upgraded`, `review-epic-prs`, `sample-minimal`, `setup-project-and-create-app`, `single-workflow`, `validate-branch-deferral-stdout`, `validate-expert-invocation`
 
 *All at:* `ai-workflow-assignments/dynamic-workflows/<name>.md`
 

ai_instruction_modules/ai-workflow-assignments/dynamic-workflows/validate-branch-deferral-stdout.md

@@ -0,0 +1,69 @@
+# Dynamic Workflow: Validate Branch Deferral (stdout-only)
+
+## Overview
+
+A **stdout-only** dynamic workflow you can run to sanity-check that the "branch selection single-source-of-truth" guidance is consistent.
+
+- This workflow intentionally performs **no assignments** and makes **no code changes**.
+- It only emits log lines (via `- log: "..."`) so you can validate orchestration + DSL parsing, and manually confirm expectations.
+
+## Script
+
+### Inputs
+
+- $ssot_file
+    - path to the canonical branch authority doc
+    - string
+    - optional
+    - default: `.github/copilot-instructions.md`
+
+- $note
+    - optional note to include in logs (e.g., link to PR/issue)
+    - string
+    - optional
+
+### announce
+
+- log: "[validate-branch-deferral-stdout] Starting stdout-only validation"
+- log: "[validate-branch-deferral-stdout] SSOT file: {ssot_file}"
+- log: "[validate-branch-deferral-stdout] Note: {note}"
+
+### checklist
+
+`$entrypoints` = [
+  `AGENTS.md`,
+  `CLAUDE.md`,
+  `GEMINI.md`,
+  `QWEN.md`,
+  `opencode-instructions.md`,
+  `.gemini/GEMINI.md`,
+  `.qwen/QWEN.md`
+]
+
+For each `$file` in `$entrypoints`, you will:
+- log: "[validate-branch-deferral-stdout] CHECK: {file} MUST defer branch selection to {ssot_file} (no hardcoded branch)"
+
+- log: "[validate-branch-deferral-stdout] CHECK: ai_instruction_modules/ai-shared-agent-context.md reinforces SSOT"
+- log: "[validate-branch-deferral-stdout] CHECK: ai_instruction_modules/ai-core-instructions.md points instruction/workflow lookups to agent-instructions-expert"
+
+### suggested-manual-verification
+
+- log: "[validate-branch-deferral-stdout] Manual verification suggestions (run locally):"
+- log: "[validate-branch-deferral-stdout]   - git grep -n \"Active Branch:\\" -- '*.md'"
+- log: "[validate-branch-deferral-stdout]   - git grep -n \"MUST be read from\" -- AGENTS.md CLAUDE.md GEMINI.md QWEN.md opencode-instructions.md .gemini/GEMINI.md .qwen/QWEN.md"
+- log: "[validate-branch-deferral-stdout]   - verify .github/copilot-instructions.md <configuration><branch> is the only branch selector"
+
+### done
+
+- log: "[validate-branch-deferral-stdout] Completed stdout-only validation"
+
+### Events
+
+#### `pre-script-begin`
+- log: "[validate-branch-deferral-stdout] Event: pre-script-begin"
+
+#### `post-script-complete`
+- log: "[validate-branch-deferral-stdout] Event: post-script-complete"
+
+#### `on-script-failure`
+- log: "[validate-branch-deferral-stdout] Event: on-script-failure"

ai_instruction_modules/ai-workflow-assignments/dynamic-workflows/validate-expert-invocation.md

@@ -0,0 +1,41 @@
+# Dynamic Workflow: Validate Expert Invocation
+
+## Overview
+
+Run a purpose-built validation assignment that emits **verifiable evidence** showing:
+1) `agent-instructions-expert` was consulted for instruction/workflow lookups, and
+2) branch selection is sourced from `.github/copilot-instructions.md`.
+
+This workflow is intended to be orchestrated using the `orchestrate-dynamic-workflow` assignment.
+
+## Script
+
+### Inputs
+
+- `$note` (optional)
+  - Free-form note to include in logs (e.g., PR number)
+
+### validate-expert-invocation
+
+- log: "[validate-expert-invocation] Starting validation run"
+
+if `$note` is provided:
+  - log: "[validate-expert-invocation] Note: {note}"
+
+- log: "[validate-expert-invocation] Assigning validation assignment: validate-agent-instructions-expert-usage"
+- assign the agent the `validate-agent-instructions-expert-usage` assignment
+- wait until the agent finishes the task
+- record output as `#validate-expert-invocation.validate-agent-instructions-expert-usage`
+
+- log: "[validate-expert-invocation] Validation assignment complete; inspect run report for PASS/FAIL against evidence criteria"
+
+### Events
+
+#### `pre-script-begin`
+- log: "[validate-expert-invocation] Event: pre-script-begin"
+
+#### `post-script-complete`
+- log: "[validate-expert-invocation] Event: post-script-complete"
+
+#### `on-script-failure`
+- log: "[validate-expert-invocation] Event: on-script-failure"

ai_instruction_modules/ai-workflow-assignments/validate-agent-instructions-expert-usage.md

@@ -0,0 +1,71 @@
+---
+description: Prove (via explicit evidence lines) that instruction/workflow lookups were delegated to agent-instructions-expert and branch came from copilot-instructions
+scope: workflow-assignment
+role: System Orchestrator
+---
+
+<instructions role="assistant" scope="workflow-assignment">
+  <overview>
+    <goal>Produce verifiable evidence that instruction/workflow lookups are being performed via `ai_instruction_modules/agent/agent-instructions-expert.md` and that branch selection is sourced from `.github/copilot-instructions.md`.</goal>
+    <context>
+      This assignment is designed for validation runs. It is intentionally "audit style": the deliverable is evidence text that a reviewer (or automated check) can verify.
+    </context>
+  </overview>
+
+  <prerequisites>
+    <item>Repository contains `.github/copilot-instructions.md` (branch authority).</item>
+    <item>Repository contains `ai_instruction_modules/agent/agent-instructions-expert.md` (lookup proxy).</item>
+  </prerequisites>
+
+  <acceptance_criteria>
+    <criterion>Output includes a "resolution trace" list of files consulted, including `.github/copilot-instructions.md` and `ai_instruction_modules/agent/agent-instructions-expert.md`.</criterion>
+    <criterion>Output includes the exact evidence line: `[evidence] expert_invoked=true`</criterion>
+    <criterion>Output includes the exact evidence line: `[evidence] lookup_source=agent-instructions-expert`</criterion>
+    <criterion>Output includes the exact evidence line: `[evidence] branch_source=.github/copilot-instructions.md`</criterion>
+    <criterion>Output includes the extracted branch value from `.github/copilot-instructions.md` (or a clear explanation why it could not be extracted).</criterion>
+    <criterion>Output includes one concrete example of a resolved canonical URL (raw GitHub URL) constructed using the extracted branch value.</criterion>
+    <criterion>Output explicitly states that no branch value was hardcoded in the validation output.</criterion>
+  </acceptance_criteria>
+
+  <workflow>
+    <step number="1">
+      <title>Resolve branch authority (SSOT)</title>
+      <description>Read `.github/copilot-instructions.md` and extract the configured branch value from `<configuration><branch>`.</description>
+      <actions>
+        <action>Read `.github/copilot-instructions.md` and locate `<configuration><branch>...</branch>`.</action>
+        <action>Record the branch value you found (e.g., `optimization`).</action>
+        <action>If the branch cannot be extracted, explain why (missing file, missing tag, parsing ambiguity) and continue with an explicit "unknown" marker.</action>
+      </actions>
+    </step>
+
+    <step number="2">
+      <title>Perform lookup via agent-instructions-expert</title>
+      <description>Use `ai_instruction_modules/agent/agent-instructions-expert.md` as the sole mechanism to resolve at least one instruction/workflow file and produce canonical raw URLs.</description>
+      <actions>
+        <action>Consult `ai_instruction_modules/agent/agent-instructions-expert.md` for how to resolve canonical URLs and what sources are authoritative.</action>
+        <action>Resolve the canonical raw URL for at least one of the following files: `ai_instruction_modules/ai-workflow-assignments/dynamic-workflows/dynamic-workflow-syntax.md` OR `ai_instruction_modules/ai-core-instructions.md`.</action>
+        <action>Show the URL translation you used (UI → raw) using the extracted branch value (no hardcoding).</action>
+      </actions>
+    </step>
+
+    <step number="3">
+      <title>Emit verifiable evidence</title>
+      <description>Print explicit evidence lines and a resolution trace so reviewers can confirm the new lookup path was used.</description>
+      <actions>
+        <action>Print a resolution trace list of the exact files you consulted.</action>
+        <action>Print the three required evidence lines: `[evidence] expert_invoked=true`, `[evidence] lookup_source=agent-instructions-expert`, `[evidence] branch_source=.github/copilot-instructions.md`.</action>
+        <action>State explicitly: `No branch value was hardcoded; it was derived from .github/copilot-instructions.md.`</action>
+      </actions>
+    </step>
+  </workflow>
+
+  <validation>
+    <step>Confirm all acceptance criteria are satisfied with evidence present in the output.</step>
+    <step>If any criterion is not met, explicitly mark FAIL and state what is missing.</step>
+  </validation>
+
+  <notes>
+    <note>This assignment is intentionally "self-describing". The output is the proof artifact.</note>
+    <note>It does not attempt to detect "old way" programmatically; instead, it proves the "new way" by requiring explicit evidence lines and a resolution trace that includes `agent-instructions-expert`.</note>
+  </notes>
+</instructions>

opencode-instructions.md

@@ -4,7 +4,7 @@ Guidance for OpenCode CLI agent.
 
 ## Configuration
 
-**Active Branch:** `main`
+**Branch:** MUST be read from [`.github/copilot-instructions.md`](.github/copilot-instructions.md) → `<configuration><branch>`. MUST NOT be hardcoded elsewhere.
 
 ## Instructions