Experiment: add area playbooks to fix-bug agent

src/bcbench/agent/claude/agent.py

@@ -17,7 +17,7 @@
 from bcbench.dataset import BaseDatasetEntry
 from bcbench.exceptions import AgentError, AgentTimeoutError
 from bcbench.logger import get_logger
-from bcbench.operations import setup_agent_skills, setup_custom_agent, setup_instructions_from_config
+from bcbench.operations import setup_agent_playbooks, setup_agent_skills, setup_custom_agent, setup_instructions_from_config
 from bcbench.types import AgentHarness, AgentMetrics, AgentRuntimeConfig, EvaluationCategory, ExperimentConfiguration, PluginConfig
 
 logger = get_logger(__name__)
@@ -65,6 +65,7 @@ def run_claude_code(
     instructions_enabled: bool = setup_instructions_from_config(claude_config, entry, repo_path, harness=AgentHarness.CLAUDE)
     skills_enabled: bool = setup_agent_skills(claude_config, entry, repo_path, harness=AgentHarness.CLAUDE)
     custom_agent: str | None = setup_custom_agent(claude_config, entry, repo_path, harness=AgentHarness.CLAUDE)
+    playbooks = setup_agent_playbooks(claude_config, entry, repo_path, harness=AgentHarness.CLAUDE, custom_agent=custom_agent)
     plugins: list[tuple[PluginConfig, Path]] = resolve_config_plugins(claude_config, allow_copilot_manifest=False)
 
     config = ExperimentConfiguration(
@@ -73,6 +74,10 @@ def run_claude_code(
         custom_instructions=instructions_enabled,
         skills_enabled=skills_enabled,
         custom_agent=custom_agent,
+        playbooks_enabled=playbooks.enabled,
+        playbook_mode=playbooks.mode,
+        playbook_revision=playbooks.revision,
+        playbook_id=playbooks.playbook_id,
         plugins=[plugin.record for plugin, _ in plugins] or None,
     )
 

src/bcbench/agent/copilot/agent.py

@@ -18,7 +18,7 @@
 from bcbench.dataset import BaseDatasetEntry
 from bcbench.exceptions import AgentError, AgentTimeoutError
 from bcbench.logger import get_logger
-from bcbench.operations import setup_agent_skills, setup_custom_agent, setup_instructions_from_config
+from bcbench.operations import setup_agent_playbooks, setup_agent_skills, setup_custom_agent, setup_instructions_from_config
 from bcbench.types import AgentHarness, AgentMetrics, AgentRuntimeConfig, EvaluationCategory, ExperimentConfiguration, PluginConfig
 
 logger = get_logger(__name__)
@@ -62,6 +62,7 @@ def run_copilot_agent(
     instructions_enabled: bool = setup_instructions_from_config(copilot_config, entry, repo_path, harness=AgentHarness.COPILOT)
     skills_enabled: bool = setup_agent_skills(copilot_config, entry, repo_path, harness=AgentHarness.COPILOT)
     custom_agent: str | None = setup_custom_agent(copilot_config, entry, repo_path, harness=AgentHarness.COPILOT)
+    playbooks = setup_agent_playbooks(copilot_config, entry, repo_path, harness=AgentHarness.COPILOT, custom_agent=custom_agent)
     plugins: list[tuple[PluginConfig, Path]] = resolve_config_plugins(copilot_config, allow_copilot_manifest=True)
 
     config = ExperimentConfiguration(
@@ -70,6 +71,10 @@ def run_copilot_agent(
         custom_instructions=instructions_enabled,
         skills_enabled=skills_enabled,
         custom_agent=custom_agent,
+        playbooks_enabled=playbooks.enabled,
+        playbook_mode=playbooks.mode,
+        playbook_revision=playbooks.revision,
+        playbook_id=playbooks.playbook_id,
         plugins=[plugin.record for plugin, _ in plugins] or None,
     )
 

src/bcbench/agent/shared/__init__.py

@@ -6,12 +6,20 @@
 from bcbench.agent.shared.mcp_gateway import start_bc_mcp_gateway
 from bcbench.agent.shared.plugin import resolve_config_plugins
 from bcbench.agent.shared.prompt import build_prompt
+from bcbench.playbooks import PlaybookDefinition, PlaybookManifest, PlaybookSetup, load_playbook_manifest, playbook_revision, resolve_playbook_for_area, resolve_playbook_for_paths
 
 __all__ = [
+    "PlaybookDefinition",
+    "PlaybookManifest",
+    "PlaybookSetup",
     "agent_subprocess_env",
     "build_al_lsp_plugin",
     "build_mcp_config",
     "build_prompt",
+    "load_playbook_manifest",
+    "playbook_revision",
     "resolve_config_plugins",
+    "resolve_playbook_for_area",
+    "resolve_playbook_for_paths",
     "start_bc_mcp_gateway",
 ]

src/bcbench/agent/shared/config.yaml

@@ -153,6 +153,13 @@ agents:
   enabled: true
   name: fix-bug
 
+# Controls area-specific playbooks inside the selected custom agent.
+# discover lets the agent select from confirmed source paths during investigation.
+# selected lets the harness select from dataset metadata.area before investigation.
+playbooks:
+  enabled: true
+  mode: discover
+
 # controls loading agent plugins for the run, only enabled entries are validated and loaded.
 # Each plugin gets its own entry, and is passed to the CLI via `--plugin-dir` (session-scoped).
 #   name:     plugin name; also how it is recorded on the result as "<name>@<revision|local>"

src/bcbench/agent/shared/instructions/microsoft-BCApps/agents/fix-bug.agent.md

@@ -13,6 +13,13 @@ the change, implement it, and validate it with the AL tools when they are availa
 does not fetch work items, does not create branches, does not commit, and does not open pull
 requests. Its only output is the change in the working tree plus a short report.
 
+## Execution model
+
+Execute the workflow directly in this agent. Do not use the Agent tool. Do not delegate any part of
+the task to a subagent. Do not start background work. This is an unattended, non-interactive
+run: returning ends the session immediately, so all investigation, edits, and validation must finish
+before the final response.
+
 ## Step 1: Locate the support files and read the rules
 
 Set `AGENT_ROOT` from the harness running this agent:
@@ -27,6 +34,10 @@ does not exist, stop and report the missing path.
 Read `AGENT_ROOT/rules.md` before acting. It defines the hard constraints, how to use the AL tools,
 and how to fail.
 
+If `AGENT_ROOT/playbooks/selected.yaml` exists, read it and then read the playbook named by its
+`file` field before extracting the task. Read no other area playbook. If the marker names a missing
+file, stop and report that the agent package is incomplete.
+
 ## Step 2: Extract the task
 
 From the user prompt, identify the issue description, the repository path, and any reproduction
@@ -44,3 +55,5 @@ Read `AGENT_ROOT/workflow.md` and execute every step of it.
 | `AGENT_ROOT/rules.md` | Always, before acting |
 | `AGENT_ROOT/workflow.md` | Always, as Step 3 |
 | `AGENT_ROOT/troubleshooting.md` | When a build, publish, or test call behaves in a way the workflow does not cover |
+| `AGENT_ROOT/playbooks/manifest.yaml` | During discover-mode routing |
+| `AGENT_ROOT/playbooks/selected.yaml` | When present; identifies the selected-mode playbook |