claude-dev-env 1.95.0 → 2.0.0

package/skills/CLAUDE.md

@@ -23,9 +23,11 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 
 **Planning and implementation**
 - `anthropic-plan` — creates a source-grounded plan packet before any code changes
-- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; Grok: max-tier Claude via CLI Claude-chain)
-- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; Grok Claude CLI chain, no Agent-tool advisor spawn)
-- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; Grok max-tier Claude via CLI Claude-chain, fail closed when unreachable) and consults it for a second opinion before a big decision, at completion, when stuck, or when reconsidering the approach
+- `orchestrator` — turns the session into the orchestrator: it spawns executor subagents to do the code edits and test runs; hard decisions go to a shared advisor (Claude warm `session-advisor` via SendMessage; a third-party host: max-tier Claude via CLI Claude-chain)
+- `orchestrator-refresh` — sub-skill fired by the `/orchestrator` loop to re-assert the host-matched shared-advisor discipline mid-run (Claude SendMessage; a third-party host's Claude CLI chain, no Agent-tool advisor spawn)
+- `team-advisor` — binds one advisor at the strongest reachable tier (Claude warm agent; a third-party host: max-tier Claude via CLI Claude-chain, fail closed when unreachable) and consults it for a second opinion before a big decision, at completion, when stuck, or when reconsidering the approach
+- `grokify` — builds a paste-ready Grok Build handoff with a Claude advisor charter
+- `grok-spawn` — orchestrator playbook for fleets of headless grok CLI workers (preflight, batch spec, `spawn_grok_batch.py`)
 
 **PR review and convergence**
 - `autoconverge` — autonomous single-run workflow that drives a PR to ready

package/skills/_shared/pr-loop/scripts/build_audit_prompt.py

@@ -2,12 +2,13 @@
 
 Builds <context> and <scope> from CLI args; <bug_categories>,
 <rubric_reference>, and <constraints> come from the shared constants in
-skills_pr_loop_constants; <comment_posting> and <output_format> are built
-inline. <pr_description> carries the PR body text read from --pr-body-file,
-and stays empty when that argument is absent or the file cannot be read.
+skills_pr_loop_constants; <comment_posting> and <output_format> follow
+``--flavor`` (agent or headless). <pr_description> carries the PR body
+text read from --pr-body-file, and stays empty when that argument is
+absent or the file cannot be read.
 
 Usage:
-  python scripts/build_audit_prompt.py --owner jl-cmd --repo claude-dev-env --pr-number 422 --loop 1 --head-ref feat/branch --base-ref main --worktree-path <PATH> --run-temp-dir <PATH>
+  python scripts/build_audit_prompt.py --owner jl-cmd --repo claude-dev-env --pr-number 422 --loop 1 --head-ref feat/branch --base-ref main --worktree-path <PATH> --run-temp-dir <PATH> [--flavor agent|headless]
 """
 
 from __future__ import annotations
@@ -21,10 +22,18 @@ _self_dir = Path(__file__).resolve().parent
 if str(_self_dir) not in sys.path:
     sys.path.insert(0, str(_self_dir))
 
+from _path_resolver import outcome_xml_path
 from _xml_utils import emit_pretty_xml
 from skills_pr_loop_constants.path_resolver_constants import (
     ALL_AUDIT_CATEGORY_ENTRIES,
     ALL_AUDIT_CONSTRAINT_TEXTS,
+    ALL_AUDIT_PROMPT_FLAVORS,
+    AUDIT_COMMENT_POSTING_AGENT_TEXT,
+    AUDIT_COMMENT_POSTING_HEADLESS_TEXT,
+    AUDIT_OUTPUT_FORMAT_AGENT_TEXT,
+    AUDIT_OUTPUT_FORMAT_HEADLESS_TEMPLATE,
+    AUDIT_PROMPT_FLAVOR_AGENT,
+    AUDIT_PROMPT_FLAVOR_HEADLESS,
     AUDIT_RUBRIC_REFERENCE_TEXT,
 )
 
@@ -61,6 +70,46 @@ def _append_pr_description(root: Element, pr_body_text: str | None) -> None:
         pr_description.text = pr_body_text
 
 
+def _comment_posting_text(flavor: str) -> str:
+    """Return the <comment_posting> body for the given prompt flavor.
+
+    Args:
+        flavor: ``agent`` or ``headless`` prompt flavor.
+
+    Returns:
+        Comment-posting instruction text for that flavor.
+    """
+    if flavor == AUDIT_PROMPT_FLAVOR_HEADLESS:
+        return AUDIT_COMMENT_POSTING_HEADLESS_TEXT
+    return AUDIT_COMMENT_POSTING_AGENT_TEXT
+
+
+def _format_instruction_text(
+    *,
+    flavor: str,
+    worktree_path: Path,
+    pr_number: int,
+    loop: int,
+) -> str:
+    """Return the <output_format> body for the given prompt flavor.
+
+    Args:
+        flavor: ``agent`` or ``headless`` prompt flavor.
+        worktree_path: Path to the git worktree.
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+
+    Returns:
+        Format-instruction text for that flavor.
+    """
+    if flavor == AUDIT_PROMPT_FLAVOR_HEADLESS:
+        outcome_path = outcome_xml_path(worktree_path, pr_number, loop)
+        return AUDIT_OUTPUT_FORMAT_HEADLESS_TEMPLATE.format(
+            outcome_path=outcome_path.as_posix(),
+        )
+    return AUDIT_OUTPUT_FORMAT_AGENT_TEXT
+
+
 def build_audit_prompt_xml(
     *,
     owner: str,
@@ -72,6 +121,7 @@ def build_audit_prompt_xml(
     worktree_path: Path,
     run_temp_dir: Path,
     pr_body_text: str | None = None,
+    flavor: str = AUDIT_PROMPT_FLAVOR_AGENT,
 ) -> Element:
     """Build the complete AUDIT spawn prompt XML.
 
@@ -85,6 +135,8 @@ def build_audit_prompt_xml(
         worktree_path: Path to the git worktree.
         run_temp_dir: Path to the run temp directory.
         pr_body_text: PR description body text, or None when unavailable.
+        flavor: Prompt flavor — ``agent`` (MCP posting) or ``headless``
+            (outcome file, lead-owned posting).
 
     Returns:
         Root <spawn_prompt> element.
@@ -122,16 +174,14 @@ def build_audit_prompt_xml(
         SubElement(constraints, "constraint").text = each_constraint
 
     comment_posting = SubElement(root, "comment_posting")
-    comment_posting.text = (
-        "Post findings as inline review comments on the PR via "
-        "the GitHub MCP add_comment_to_pending_review tool. "
-        "Group related findings into a single pending review."
-    )
+    comment_posting.text = _comment_posting_text(flavor)
 
-    output_format = SubElement(root, "output_format")
-    output_format.text = (
-        "Emit findings as JSON array of objects with keys: "
-        "severity (P0/P1/P2), file, line, category, message, suggestion."
+    format_section = SubElement(root, "output_format")
+    format_section.text = _format_instruction_text(
+        flavor=flavor,
+        worktree_path=worktree_path,
+        pr_number=pr_number,
+        loop=loop,
     )
 
     return root
@@ -148,6 +198,7 @@ def emit_audit_prompt(
     worktree_path: Path,
     run_temp_dir: Path,
     pr_body_text: str | None = None,
+    flavor: str = AUDIT_PROMPT_FLAVOR_AGENT,
 ) -> str:
     """Build and serialize the AUDIT spawn prompt to a pretty-printed XML string.
 
@@ -161,6 +212,7 @@ def emit_audit_prompt(
         worktree_path: Path to the git worktree.
         run_temp_dir: Path to the run temp directory.
         pr_body_text: PR description body text, or None when unavailable.
+        flavor: Prompt flavor — ``agent`` or ``headless``.
 
     Returns:
         Pretty-printed XML string.
@@ -175,6 +227,7 @@ def emit_audit_prompt(
         worktree_path=worktree_path,
         run_temp_dir=run_temp_dir,
         pr_body_text=pr_body_text,
+        flavor=flavor,
     )
     return emit_pretty_xml(root)
 
@@ -198,6 +251,11 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
     parser.add_argument("--worktree-path", type=Path, required=True)
     parser.add_argument("--run-temp-dir", type=Path, required=True)
     parser.add_argument("--pr-body-file", type=Path, default=None)
+    parser.add_argument(
+        "--flavor",
+        choices=sorted(ALL_AUDIT_PROMPT_FLAVORS),
+        default=AUDIT_PROMPT_FLAVOR_AGENT,
+    )
     return parser.parse_args(all_argv)
 
 
@@ -221,6 +279,7 @@ def main(all_arguments: list[str]) -> int:
         worktree_path=arguments.worktree_path,
         run_temp_dir=arguments.run_temp_dir,
         pr_body_text=read_pr_body_text(arguments.pr_body_file),
+        flavor=arguments.flavor,
     )
     sys.stdout.write(xml_output)
     return 0

package/skills/_shared/pr-loop/scripts/build_fix_prompt.py

@@ -1,10 +1,11 @@
 """Emit the complete FIX spawn prompt XML to stdout.
 
 Populates <bug> entries from findings JSON, plus <execution> checklist
-and <constraints>.
+and <constraints>. <comment_posting> and <output_format> follow
+``--flavor`` (agent or headless).
 
 Usage:
-  python scripts/build_fix_prompt.py --owner jl-cmd --repo claude-dev-env --pr-number 422 --loop 1 --head-ref feat/branch --base-ref main --worktree-path <PATH> --findings-json <PATH>
+  python scripts/build_fix_prompt.py --owner jl-cmd --repo claude-dev-env --pr-number 422 --loop 1 --head-ref feat/branch --base-ref main --worktree-path <PATH> --findings-json <PATH> [--flavor agent|headless]
 """
 
 from __future__ import annotations
@@ -20,13 +21,92 @@ if str(_self_dir) not in sys.path:
     sys.path.insert(0, str(_self_dir))
 
 from _cli_utils import require_file
+from _path_resolver import fix_outcome_xml_path
 from _xml_utils import emit_pretty_xml
 from skills_pr_loop_constants.path_resolver_constants import (
     ALL_FIX_CONSTRAINT_TEXTS,
+    ALL_FIX_CONSTRAINT_TEXTS_HEADLESS,
     ALL_FIX_EXECUTION_STEPS,
+    ALL_FIX_EXECUTION_STEPS_HEADLESS,
+    ALL_FIX_PROMPT_FLAVORS,
+    FINDINGS_JSON_MUST_BE_LIST_MESSAGE,
+    FIX_COMMENT_POSTING_AGENT_TEXT,
+    FIX_COMMENT_POSTING_HEADLESS_TEXT,
+    FIX_OUTPUT_FORMAT_AGENT_TEXT,
+    FIX_OUTPUT_FORMAT_HEADLESS_TEMPLATE,
+    FIX_PROMPT_FLAVOR_AGENT,
+    FIX_PROMPT_FLAVOR_HEADLESS,
 )
 
 
+def _comment_posting_text(flavor: str) -> str:
+    """Return the <comment_posting> body for the given prompt flavor.
+
+    Args:
+        flavor: ``agent`` or ``headless`` prompt flavor.
+
+    Returns:
+        Comment-posting instruction text for that flavor.
+    """
+    if flavor == FIX_PROMPT_FLAVOR_HEADLESS:
+        return FIX_COMMENT_POSTING_HEADLESS_TEXT
+    return FIX_COMMENT_POSTING_AGENT_TEXT
+
+
+def _format_instruction_text(
+    *,
+    flavor: str,
+    worktree_path: Path,
+    pr_number: int,
+    loop: int,
+) -> str:
+    """Return the <output_format> body for the given prompt flavor.
+
+    Args:
+        flavor: ``agent`` or ``headless`` prompt flavor.
+        worktree_path: Path to the git worktree.
+        pr_number: Pull request number.
+        loop: Loop iteration number.
+
+    Returns:
+        Format-instruction text for that flavor.
+    """
+    if flavor == FIX_PROMPT_FLAVOR_HEADLESS:
+        outcome_path = fix_outcome_xml_path(worktree_path, pr_number, loop)
+        return FIX_OUTPUT_FORMAT_HEADLESS_TEMPLATE.format(
+            outcome_path=outcome_path.as_posix(),
+        )
+    return FIX_OUTPUT_FORMAT_AGENT_TEXT
+
+
+def _all_execution_steps(flavor: str) -> list[str]:
+    """Return the execution checklist for the given prompt flavor.
+
+    Args:
+        flavor: ``agent`` or ``headless`` prompt flavor.
+
+    Returns:
+        Ordered execution step texts for that flavor.
+    """
+    if flavor == FIX_PROMPT_FLAVOR_HEADLESS:
+        return list(ALL_FIX_EXECUTION_STEPS_HEADLESS)
+    return list(ALL_FIX_EXECUTION_STEPS)
+
+
+def _all_constraint_texts(flavor: str) -> list[str]:
+    """Return the constraint texts for the given prompt flavor.
+
+    Args:
+        flavor: ``agent`` or ``headless`` prompt flavor.
+
+    Returns:
+        Ordered constraint texts for that flavor.
+    """
+    if flavor == FIX_PROMPT_FLAVOR_HEADLESS:
+        return list(ALL_FIX_CONSTRAINT_TEXTS_HEADLESS)
+    return list(ALL_FIX_CONSTRAINT_TEXTS)
+
+
 def build_fix_prompt_xml(
     *,
     owner: str,
@@ -37,6 +117,7 @@ def build_fix_prompt_xml(
     base_ref: str,
     worktree_path: Path,
     findings_json_path: Path,
+    flavor: str = FIX_PROMPT_FLAVOR_AGENT,
 ) -> Element:
     """Build the complete FIX spawn prompt XML.
 
@@ -49,11 +130,18 @@ def build_fix_prompt_xml(
         base_ref: Base branch ref.
         worktree_path: Path to the git worktree.
         findings_json_path: Path to the findings JSON file.
+        flavor: Prompt flavor — ``agent`` (in-agent commit/post) or
+            ``headless`` (outcome file, lead-owned commit/post).
 
     Returns:
         Root <spawn_prompt> element.
     """
     findings_data = json.loads(findings_json_path.read_text(encoding="utf-8"))
+    if not isinstance(findings_data, list):
+        findings_type_name = type(findings_data).__name__
+        raise TypeError(
+            FINDINGS_JSON_MUST_BE_LIST_MESSAGE % findings_type_name
+        )
 
     root = Element("spawn_prompt", {"role": "fix", "loop": str(loop)})
 
@@ -66,24 +154,34 @@ def build_fix_prompt_xml(
     SubElement(context, "worktree_path").text = worktree_path.as_posix()
 
     bugs_elem = SubElement(root, "bugs")
-    if isinstance(findings_data, list):
-        for each_finding in findings_data:
-            if isinstance(each_finding, dict):
-                bug = SubElement(bugs_elem, "bug")
-                for each_key, each_field_detail in each_finding.items():
-                    child = SubElement(bug, each_key)
-                    child.text = (
-                        str(each_field_detail) if each_field_detail is not None else ""
-                    )
+    for each_finding in findings_data:
+        if isinstance(each_finding, dict):
+            bug = SubElement(bugs_elem, "bug")
+            for each_key, each_field_detail in each_finding.items():
+                child = SubElement(bug, each_key)
+                child.text = (
+                    str(each_field_detail) if each_field_detail is not None else ""
+                )
 
     execution = SubElement(root, "execution")
-    for each_step in ALL_FIX_EXECUTION_STEPS:
+    for each_step in _all_execution_steps(flavor):
         SubElement(execution, "step").text = each_step
 
     constraints = SubElement(root, "constraints")
-    for each_constraint in ALL_FIX_CONSTRAINT_TEXTS:
+    for each_constraint in _all_constraint_texts(flavor):
         SubElement(constraints, "constraint").text = each_constraint
 
+    comment_posting = SubElement(root, "comment_posting")
+    comment_posting.text = _comment_posting_text(flavor)
+
+    format_section = SubElement(root, "output_format")
+    format_section.text = _format_instruction_text(
+        flavor=flavor,
+        worktree_path=worktree_path,
+        pr_number=pr_number,
+        loop=loop,
+    )
+
     return root
 
 
@@ -97,6 +195,7 @@ def emit_fix_prompt(
     base_ref: str,
     worktree_path: Path,
     findings_json_path: Path,
+    flavor: str = FIX_PROMPT_FLAVOR_AGENT,
 ) -> str:
     """Build and serialize the FIX spawn prompt to a pretty-printed XML string.
 
@@ -109,6 +208,7 @@ def emit_fix_prompt(
         base_ref: Base branch ref.
         worktree_path: Path to the git worktree.
         findings_json_path: Path to the findings JSON file.
+        flavor: Prompt flavor — ``agent`` or ``headless``.
 
     Returns:
         Pretty-printed XML string.
@@ -122,6 +222,7 @@ def emit_fix_prompt(
         base_ref=base_ref,
         worktree_path=worktree_path,
         findings_json_path=findings_json_path,
+        flavor=flavor,
     )
     return emit_pretty_xml(root)
 
@@ -144,6 +245,11 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
     parser.add_argument("--base-ref", required=True)
     parser.add_argument("--worktree-path", type=Path, required=True)
     parser.add_argument("--findings-json", type=Path, required=True)
+    parser.add_argument(
+        "--flavor",
+        choices=sorted(ALL_FIX_PROMPT_FLAVORS),
+        default=FIX_PROMPT_FLAVOR_AGENT,
+    )
     return parser.parse_args(all_argv)
 
 
@@ -173,8 +279,9 @@ def main(all_arguments: list[str]) -> int:
             base_ref=getattr(arguments, "base_ref"),
             worktree_path=getattr(arguments, "worktree_path"),
             findings_json_path=findings_path,
+            flavor=arguments.flavor,
         )
-    except (json.JSONDecodeError, OSError) as exc:
+    except (json.JSONDecodeError, OSError, TypeError) as exc:
         print(f"emit_fix_prompt failed: {exc}", file=sys.stderr)
         return 1
     sys.stdout.write(xml_output)

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py

@@ -56,6 +56,34 @@ AUDIT_RUBRIC_REFERENCE_TEXT = (
     "Read the rubric files before auditing."
 )
 
+AUDIT_PROMPT_FLAVOR_AGENT = "agent"
+AUDIT_PROMPT_FLAVOR_HEADLESS = "headless"
+ALL_AUDIT_PROMPT_FLAVORS = frozenset({
+    AUDIT_PROMPT_FLAVOR_AGENT,
+    AUDIT_PROMPT_FLAVOR_HEADLESS,
+})
+
+AUDIT_COMMENT_POSTING_AGENT_TEXT = (
+    "Post findings as inline review comments on the PR via "
+    "the GitHub MCP add_comment_to_pending_review tool. "
+    "Group related findings into a single pending review."
+)
+AUDIT_COMMENT_POSTING_HEADLESS_TEXT = (
+    "Do not post reviews or comments. Use gh only when you must read "
+    "PR metadata. Write findings into the outcome XML named in "
+    "<output_format>. The lead session posts the review with "
+    "post_audit_thread.py after the worker exits."
+)
+AUDIT_OUTPUT_FORMAT_AGENT_TEXT = (
+    "Emit findings as JSON array of objects with keys: "
+    "severity (P0/P1/P2), file, line, category, message, suggestion."
+)
+AUDIT_OUTPUT_FORMAT_HEADLESS_TEMPLATE = (
+    "Write the complete audit outcome XML to {outcome_path}. "
+    "Leave review_url empty when the lead posts after you exit. "
+    "Do not use TaskCreate, MCP tools, or Artifact tools."
+)
+
 ALL_FIX_EXECUTION_STEPS = [
     "Read the finding and verify it against the current file at file:line.",
     "Write a failing test that reproduces the bug.",
@@ -66,6 +94,14 @@ ALL_FIX_EXECUTION_STEPS = [
     "Post an inline reply on the finding thread confirming the fix.",
 ]
 
+ALL_FIX_EXECUTION_STEPS_HEADLESS = [
+    "Read the finding and verify it against the current file at file:line.",
+    "Write a failing test that reproduces the bug.",
+    "Implement the smallest change that resolves the finding.",
+    "Run the full test suite — confirm the new test and all existing tests pass.",
+    "Leave the working tree dirty with your edits. Do not stage, commit, or push.",
+]
+
 ALL_FIX_CONSTRAINT_TEXTS = [
     "Work exclusively within the worktree directory.",
     "Change only the lines directly related to each finding.",
@@ -77,8 +113,50 @@ ALL_FIX_CONSTRAINT_TEXTS = [
     "forward slashes (e.g. C:/Users/...), even on Windows.",
 ]
 
+ALL_FIX_CONSTRAINT_TEXTS_HEADLESS = [
+    "Work exclusively within the worktree directory.",
+    "Change only the lines directly related to each finding.",
+    "Every fix must have a corresponding test.",
+    "Remove deprecated code directly and update all call sites.",
+    "Handle each error case with a named exception type.",
+    "Do not stage, commit, or push. The lead owns git write operations.",
+    "Do not use TaskCreate, MCP tools, or Artifact tools.",
+    "Double-quote every path in shell commands and write paths with "
+    "forward slashes (e.g. C:/Users/...), even on Windows.",
+]
+
+FIX_PROMPT_FLAVOR_AGENT = "agent"
+FIX_PROMPT_FLAVOR_HEADLESS = "headless"
+ALL_FIX_PROMPT_FLAVORS = frozenset({
+    FIX_PROMPT_FLAVOR_AGENT,
+    FIX_PROMPT_FLAVOR_HEADLESS,
+})
+
+FIX_COMMENT_POSTING_AGENT_TEXT = (
+    "After commit, post one reply per finding thread via the GitHub MCP "
+    "add_reply_to_pull_request_comment tool, then resolve the thread."
+)
+FIX_COMMENT_POSTING_HEADLESS_TEXT = (
+    "Do not post replies or resolve threads. Use gh only when you must read "
+    "PR metadata. Write per-finding outcomes into the outcome XML named in "
+    "<output_format>. The lead session posts replies after the worker exits."
+)
+FIX_OUTPUT_FORMAT_AGENT_TEXT = (
+    "After posting replies, write the complete fix outcome XML "
+    "(schema in PROMPTS.md)."
+)
+FIX_OUTPUT_FORMAT_HEADLESS_TEMPLATE = (
+    "Write the complete fix outcome XML to {outcome_path}. "
+    "Leave commit_sha empty when the lead commits after you exit. "
+    "Do not use TaskCreate, MCP tools, or Artifact tools."
+)
+
 ALL_PYTHON_ONEXC_VERSION = (3, 12)
 
+FINDINGS_JSON_MUST_BE_LIST_MESSAGE = (
+    "findings-json root must be a JSON array of finding objects, got %s"
+)
+
 ALL_FINDING_BODY_ELEMENT_KEYS: tuple[str, ...] = (
     "title",
     "excerpt",

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -9,12 +9,21 @@ from pathlib import Path
 from types import ModuleType
 from xml.etree.ElementTree import Element
 
+import pytest
+
 _SCRIPTS_DIR = Path(__file__).resolve().parent
 if str(_SCRIPTS_DIR) not in sys.path:
     sys.path.insert(0, str(_SCRIPTS_DIR))
 
 from skills_pr_loop_constants.path_resolver_constants import (
     ALL_AUDIT_CATEGORY_ENTRIES,
+    AUDIT_COMMENT_POSTING_AGENT_TEXT,
+    AUDIT_COMMENT_POSTING_HEADLESS_TEXT,
+    AUDIT_OUTPUT_FORMAT_AGENT_TEXT,
+    AUDIT_OUTPUT_FORMAT_HEADLESS_TEMPLATE,
+    AUDIT_PROMPT_FLAVOR_AGENT,
+    AUDIT_PROMPT_FLAVOR_HEADLESS,
+    OUTCOME_XML_TEMPLATE,
 )
 
 _CATEGORY_RUBRICS_DIR = _SCRIPTS_DIR.parents[3] / "audit-rubrics" / "category_rubrics"
@@ -257,3 +266,115 @@ def test_parse_arguments_reads_pr_body_file_path() -> None:
         "--pr-body-file", "/tmp/body.md",
     ])
     assert arguments.pr_body_file == Path("/tmp/body.md")
+
+
+def test_parse_arguments_defaults_flavor_to_agent() -> None:
+    arguments = build_audit_prompt.parse_arguments([
+        "--owner", "jl-cmd",
+        "--repo", "claude-dev-env",
+        "--pr-number", "422",
+        "--loop", "1",
+        "--head-ref", "feat/branch",
+        "--base-ref", "main",
+        "--worktree-path", "/tmp/wt",
+        "--run-temp-dir", "/tmp/rt",
+    ])
+    assert arguments.flavor == AUDIT_PROMPT_FLAVOR_AGENT
+
+
+def test_parse_arguments_reads_headless_flavor() -> None:
+    arguments = build_audit_prompt.parse_arguments([
+        "--owner", "jl-cmd",
+        "--repo", "claude-dev-env",
+        "--pr-number", "422",
+        "--loop", "1",
+        "--head-ref", "feat/branch",
+        "--base-ref", "main",
+        "--worktree-path", "/tmp/wt",
+        "--run-temp-dir", "/tmp/rt",
+        "--flavor", AUDIT_PROMPT_FLAVOR_HEADLESS,
+    ])
+    assert arguments.flavor == AUDIT_PROMPT_FLAVOR_HEADLESS
+
+
+def test_agent_flavor_comment_posting_names_mcp_tool() -> None:
+    root = build_audit_prompt.build_audit_prompt_xml(
+        owner="jl-cmd",
+        repo="claude-dev-env",
+        pr_number=422,
+        loop=1,
+        head_ref="feat/branch",
+        base_ref="main",
+        worktree_path=Path("/tmp/bugteam-pr-422/worktree"),
+        run_temp_dir=Path("/tmp/bugteam-pr-422"),
+        flavor=AUDIT_PROMPT_FLAVOR_AGENT,
+    )
+    comment_posting = root.find("comment_posting")
+    assert comment_posting is not None
+    assert comment_posting.text == AUDIT_COMMENT_POSTING_AGENT_TEXT
+    output_format = root.find("output_format")
+    assert output_format is not None
+    assert output_format.text == AUDIT_OUTPUT_FORMAT_AGENT_TEXT
+
+
+def test_headless_flavor_writes_outcome_path_and_forbids_mcp() -> None:
+    worktree_path = Path("/tmp/bugteam-pr-422/worktree")
+    pr_number = 422
+    loop = 3
+    root = build_audit_prompt.build_audit_prompt_xml(
+        owner="jl-cmd",
+        repo="claude-dev-env",
+        pr_number=pr_number,
+        loop=loop,
+        head_ref="feat/branch",
+        base_ref="main",
+        worktree_path=worktree_path,
+        run_temp_dir=Path("/tmp/bugteam-pr-422"),
+        flavor=AUDIT_PROMPT_FLAVOR_HEADLESS,
+    )
+    comment_posting = root.find("comment_posting")
+    assert comment_posting is not None
+    assert comment_posting.text == AUDIT_COMMENT_POSTING_HEADLESS_TEXT
+    assert "MCP" not in (comment_posting.text or "")
+    assert "TaskCreate" not in (comment_posting.text or "")
+    assert "gh" in (comment_posting.text or "")
+    assert "post_audit_thread.py" in (comment_posting.text or "")
+
+    expected_outcome_path = (
+        worktree_path / OUTCOME_XML_TEMPLATE.format(number=pr_number, loop=loop)
+    ).as_posix()
+    output_format = root.find("output_format")
+    assert output_format is not None
+    assert output_format.text == AUDIT_OUTPUT_FORMAT_HEADLESS_TEMPLATE.format(
+        outcome_path=expected_outcome_path,
+    )
+    assert expected_outcome_path in (output_format.text or "")
+    assert "TaskCreate" in (output_format.text or "")
+    assert "MCP" in (output_format.text or "")
+
+
+def test_main_headless_flavor_emits_outcome_path_on_stdout(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    worktree_path = "/tmp/bugteam-pr-99/worktree"
+    exit_code = build_audit_prompt.main([
+        "--owner", "jl-cmd",
+        "--repo", "claude-dev-env",
+        "--pr-number", "99",
+        "--loop", "2",
+        "--head-ref", "feat/branch",
+        "--base-ref", "main",
+        "--worktree-path", worktree_path,
+        "--run-temp-dir", "/tmp/bugteam-pr-99",
+        "--flavor", AUDIT_PROMPT_FLAVOR_HEADLESS,
+    ])
+    assert exit_code == 0
+    captured = capsys.readouterr()
+    expected_outcome = (
+        Path(worktree_path)
+        / OUTCOME_XML_TEMPLATE.format(number=99, loop=2)
+    ).as_posix()
+    assert expected_outcome in captured.out
+    assert "post_audit_thread.py" in captured.out
+    assert "Do not post reviews" in captured.out
+    assert "add_comment_to_pending_review" not in captured.out