opencode-codeops 1.7.1 → 1.8.0

package/scripts/install_agents.py

@@ -3,17 +3,27 @@
 install_agents.py — CodeOps for OpenCode
 Generates OpenCode agent Markdown files from codeops/codeops.json routing config.
 
+The generator serves two kinds of roles:
+
+- the twelve catalog roles, generated from templates in `agent-templates/`; and
+- project specialists, generated from a project brief in `codeops/specialists/`
+  plus one of the two generic specialist templates (`--custom <role>`).
+
 Usage:
   python3 install_agents.py --project <path> --roles ROLE[,ROLE...]
+  python3 install_agents.py --project <path> --custom ROLE
   python3 install_agents.py --project <path> --check
   python3 install_agents.py --project <path> --dry-run --roles ROLE[,ROLE...]
 """
 
+from __future__ import annotations
+
 import argparse
 import json
 import os
 import re
 import sys
+import unicodedata
 from pathlib import Path
 from typing import Optional
 
@@ -52,6 +62,8 @@ TEMPLATE_PERMISSIONS: dict[str, dict[str, str]] = {
     "financial-integrity-auditor": {"read": "allow", "edit": "deny",  "bash": "deny"},
     "concurrency-auditor":       {"read": "allow", "edit": "deny",  "bash": "deny"},
     "semantics-reviewer":        {"read": "allow", "edit": "deny",  "bash": "deny"},
+    "domain-specialist-reviewer": {"read": "allow", "grep": "allow", "glob": "allow", "edit": "deny",  "bash": "allow"},
+    "domain-specialist-executor": {"read": "allow", "grep": "allow", "glob": "allow", "edit": "allow", "bash": "allow"},
 }
 
 # effort -> temperature mapping
@@ -70,6 +82,318 @@ SANDBOX_PERMISSIONS: dict[str, dict[str, str]] = {
 
 CODEOPS_MARKER = "# Generated by CodeOps install_agents.py"
 
+# ---------------------------------------------------------------------------
+# Custom specialist roles
+#
+# A specialist is defined by a project brief (`codeops/specialists/<role>.md`)
+# and generated from one of two generic templates. Everything below is
+# validated before any file is touched: a rejected brief leaves the project
+# byte-for-byte unchanged.
+# ---------------------------------------------------------------------------
+
+# Brief `kind` -> generic template; the only two supported specialist shapes.
+CUSTOM_TEMPLATES: dict[str, str] = {
+    "reviewer": "domain-specialist-reviewer",
+    "executor": "domain-specialist-executor",
+}
+
+# OpenCode's built-in agent names; a specialist may never shadow one.
+BUILTIN_AGENT_NAMES = frozenset(
+    {"plan", "build", "general", "explore", "scout", "compaction", "title", "summary"}
+)
+
+# Windows device names; creating such a file breaks checkouts on that platform.
+DOS_DEVICE_NAMES = frozenset(
+    {"con", "nul", "aux", "prn"}
+    | {f"com{number}" for number in range(1, 10)}
+    | {f"lpt{number}" for number in range(1, 10)}
+)
+
+# Role slugs are short, portable, and lowercase so they map safely to both a
+# filename and an OpenCode agent name.
+ROLE_PATTERN = re.compile(r"^[a-z][a-z0-9-]{1,40}$")
+
+# Provider passthrough values for the generated `reasoningEffort`; a routing
+# override outside this list is rejected rather than forwarded.
+REASONING_VALUES = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+
+# Maximum length of each single-line brief field after sanitization.
+BRIEF_TEXT_LIMITS: dict[str, int] = {
+    "description": 200,
+    "capability": 200,
+    "scope": 200,
+    "evidence": 500,
+    "required-for": 200,
+}
+
+# The brief Markdown body may not exceed this many bytes.
+MAX_BRIEF_BODY_BYTES = 16384
+
+# Managed AGENTS.md index block. The markers are the whole contract: the sync
+# replaces only what sits between them and removes the block when no specialist
+# briefs remain.
+AGENTS_START = "<!-- CODEOPS-SPECIALISTS:START -->"
+AGENTS_END = "<!-- CODEOPS-SPECIALISTS:END -->"
+
+# Soft budget: beyond this many entries the block ends with an overflow
+# pointer instead of growing without bound.
+AGENTS_ENTRY_BUDGET = 15
+
+# Generated specialist agents carry this template-name prefix in their
+# ownership header; removal refuses anything else.
+CUSTOM_TEMPLATE_PREFIX = "domain-specialist-"
+
+# Every frontmatter key a brief may carry; anything else is an error.
+BRIEF_KNOWN_KEYS = (
+    "schema",
+    "role",
+    "kind",
+    "description",
+    "capability",
+    "scope",
+    "evidence",
+    "effort",
+    "reasoning",
+    "hidden",
+    "required-for",
+)
+
+# Frontmatter keys a brief must define.
+BRIEF_REQUIRED_KEYS = ("role", "kind", "description")
+
+# Invisible Unicode categories removed from prompt-bound text. Hostile or
+# accidental control characters must not reach an agent file or AGENTS.md.
+STRIPPED_CATEGORIES = frozenset({"Cc", "Cf"})
+
+# Zero-width joiner: category `Cf`, but stripping it breaks emoji sequences,
+# so it is the one invisible character that survives sanitization.
+PRESERVED_INVISIBLE = "\u200d"
+
+
+class BriefError(ValueError):
+    """Raised when a specialist brief is missing, malformed, or unsafe.
+
+    The message is user-facing: it names the field, line, or rule that failed
+    so the author can fix the brief without reading the installer source.
+    """
+
+
+def is_visible(character: str) -> bool:
+    """Return True when a character may stay in prompt-bound text.
+
+    Control (`Cc`) and format (`Cf`) characters are invisible or reorder text,
+    so they are removed — except the zero-width joiner, which is part of
+    legitimate emoji sequences.
+
+    Args:
+        character: A single character.
+
+    Returns:
+        True when the character is safe to keep.
+    """
+    if character == PRESERVED_INVISIBLE:
+        return True
+    return unicodedata.category(character) not in STRIPPED_CATEGORIES
+
+
+def sanitize_prompt_text(value: str, limit: int) -> str:
+    """Sanitize one single-line brief value before it reaches a prompt.
+
+    The result is stable under repeated sanitization (a fixed point): invisible
+    characters are removed, then the whitespace-collapse and HTML comment
+    marker removal pass repeats until the value stops changing, and finally the
+    value is trimmed and length-capped. Removing markers can stitch a new
+    marker together (and can leave double spaces behind), which is why the
+    whole pass repeats until nothing changes.
+
+    Args:
+        value: Raw field value from the brief.
+        limit: Maximum length of the sanitized value.
+
+    Returns:
+        The sanitized, length-capped value.
+
+    Raises:
+        BriefError: If any marker sequence is still present after the fixed
+            point is reached (defensive; a correct loop cannot leave one).
+    """
+    cleaned = "".join(character for character in value if is_visible(character))
+    previous = None
+    while previous != cleaned:
+        previous = cleaned
+        cleaned = re.sub(r"\s+", " ", cleaned)
+        cleaned = cleaned.replace("<!--", "").replace("-->", "")
+    if "<!--" in cleaned or "-->" in cleaned:
+        raise BriefError("value still contains a comment marker after sanitization")
+    return cleaned.strip()[:limit]
+
+
+def sanitize_brief_body(body: str) -> str:
+    """Sanitize a brief body while preserving its Markdown structure.
+
+    Invisible characters are removed (newlines and tabs survive), so headings,
+    lists, and code blocks keep their shape. The body is otherwise emitted
+    as authored.
+
+    Args:
+        body: Raw Markdown body from the brief.
+
+    Returns:
+        The body with invisible characters removed.
+    """
+    return "".join(
+        character
+        for character in body
+        if character in "\n\t" or is_visible(character)
+    )
+
+
+def validate_role_name(role: str) -> None:
+    """Validate a specialist role slug against every naming rule.
+
+    Args:
+        role: Proposed role name.
+
+    Raises:
+        BriefError: If the name is malformed, reserved, or platform-hostile.
+    """
+    if not ROLE_PATTERN.fullmatch(role):
+        raise BriefError(
+            f"invalid role name {role!r}: must match {ROLE_PATTERN.pattern}"
+        )
+    if role in ROLE_TO_TEMPLATE:
+        raise BriefError(f"role {role!r} is a CodeOps catalog role and cannot be a specialist")
+    if role in BUILTIN_AGENT_NAMES:
+        raise BriefError(f"role {role!r} is an OpenCode built-in agent name and cannot be a specialist")
+    if role in DOS_DEVICE_NAMES:
+        raise BriefError(f"role {role!r} is a reserved device name and cannot be a specialist")
+    if role.endswith(".") or role.endswith(" "):
+        raise BriefError(f"role {role!r} may not end with a dot or a space")
+
+
+def parse_brief(path: Path, role: str) -> dict:
+    """Parse and validate a specialist brief.
+
+    The brief format is intentionally small: a `---` frontmatter block of flat
+    `key: value` lines, followed by a Markdown body. Unknown keys, duplicate
+    keys, missing required fields, and values outside their documented ranges
+    are all errors — the caller reports them and writes nothing.
+
+    Args:
+        path: Path to the brief file.
+        role: Role expected from the filename (without `.md`).
+
+    Returns:
+        A dictionary of validated fields plus `body` (sanitized Markdown) and
+        `body_bytes` (the raw body size in bytes, returned for callers and
+        error reporting).
+
+    Raises:
+        BriefError: If the briefing is unreadable or violates any rule.
+    """
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        raise BriefError(f"cannot read brief {path}: {exc}") from exc
+    if size > MAX_BRIEF_BODY_BYTES + 65536:
+        raise BriefError(
+            f"brief file is too large: {size} bytes (the body maximum is "
+            f"{MAX_BRIEF_BODY_BYTES} bytes)"
+        )
+    try:
+        text = path.read_text(encoding="utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise BriefError(f"brief is not valid UTF-8: {path}") from exc
+    except OSError as exc:
+        raise BriefError(f"cannot read brief {path}: {exc}") from exc
+
+    lines = text.split("\n")
+    if not lines or lines[0].strip() != "---":
+        raise BriefError("brief must start with a --- frontmatter line")
+    closing = None
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            closing = index
+            break
+    if closing is None:
+        raise BriefError("brief frontmatter is not closed with a --- line")
+
+    fields: dict[str, str] = {}
+    for index in range(1, closing):
+        line = lines[index]
+        if not line.strip():
+            continue
+        key, separator, value = line.partition(":")
+        key = key.strip()
+        if not separator or not re.fullmatch(r"[A-Za-z][A-Za-z0-9-]*", key):
+            raise BriefError(f"malformed frontmatter line {index + 1}")
+        if key not in BRIEF_KNOWN_KEYS:
+            raise BriefError(
+                f"unknown frontmatter key {key!r} at line {index + 1}; "
+                f"known keys: {', '.join(BRIEF_KNOWN_KEYS)}"
+            )
+        if key in fields:
+            raise BriefError(f"duplicate frontmatter key {key!r} at line {index + 1}")
+        fields[key] = value.strip()
+
+    for key in BRIEF_REQUIRED_KEYS:
+        if not fields.get(key):
+            raise BriefError(f"missing required frontmatter field {key!r}")
+
+    schema = fields.get("schema", "1")
+    if schema != "1":
+        raise BriefError(f"unsupported brief schema {schema!r}; this installer supports schema 1")
+
+    if fields["role"] != role:
+        raise BriefError(
+            f"frontmatter role {fields['role']!r} does not match the filename {role!r}"
+        )
+    validate_role_name(role)
+
+    kind = fields["kind"]
+    if kind not in CUSTOM_TEMPLATES:
+        raise BriefError(
+            f"unsupported kind {kind!r}; supported kinds: {', '.join(sorted(CUSTOM_TEMPLATES))}"
+        )
+
+    hidden = fields.get("hidden", "false")
+    if hidden not in ("true", "false"):
+        raise BriefError(f"hidden must be 'true' or 'false', got {hidden!r}")
+
+    effort = fields.get("effort")
+    if effort is not None and effort not in EFFORT_TO_TEMPERATURE:
+        raise BriefError(
+            f"unsupported effort {effort!r}; supported values: {', '.join(sorted(EFFORT_TO_TEMPERATURE))}"
+        )
+
+    reasoning = fields.get("reasoning")
+    if reasoning is not None and reasoning not in REASONING_VALUES:
+        raise BriefError(
+            f"unsupported reasoning {reasoning!r}; supported values: {', '.join(REASONING_VALUES)}"
+        )
+
+    validated: dict[str, object] = {
+        "kind": kind,
+        "hidden": hidden == "true",
+        "effort": effort,
+        "reasoning": reasoning,
+    }
+    for key, limit in BRIEF_TEXT_LIMITS.items():
+        raw = fields.get(key)
+        validated[key] = sanitize_prompt_text(raw, limit) if raw is not None else None
+    if not validated["description"]:
+        raise BriefError("description is empty after sanitization")
+
+    body = "\n".join(lines[closing + 1:]).lstrip("\n")
+    body_bytes = len(body.encode("utf-8"))
+    if body_bytes > MAX_BRIEF_BODY_BYTES:
+        raise BriefError(
+            f"brief body is {body_bytes} bytes; the maximum is {MAX_BRIEF_BODY_BYTES} bytes"
+        )
+    validated["body"] = sanitize_brief_body(body)
+    validated["body_bytes"] = body_bytes
+    return validated
+
 
 def find_plugin_root() -> Optional[Path]:
     """Locate the opencode-codeops package root via CODEOPS_PLUGIN_ROOT or this script's location."""
@@ -180,20 +504,637 @@ def generate_agent_file(
 
 
 def is_codeops_generated(path: Path) -> bool:
-    """Return True if the file was generated by this script (has the CodeOps marker)."""
-    if not path.exists():
+    """Return True if the file was generated by this script (has the CodeOps marker).
+
+    Unreadable or non-UTF-8 files are treated as not generated, so a corrupt
+    file is reported as a state instead of crashing the caller.
+
+    Args:
+        path: Candidate generated agent file.
+
+    Returns:
+        True when the first line carries the CodeOps ownership marker.
+    """
+    if not path.is_file():
+        return False
+    try:
+        first_line = path.read_text(encoding="utf-8").split("\n", 1)[0]
+    except (OSError, UnicodeDecodeError):
         return False
-    first_line = path.read_text(encoding="utf-8").split("\n", 1)[0]
     return first_line.strip() == CODEOPS_MARKER
 
 
+def generate_custom_agent(plugin_root: Path, role: str, brief: dict, role_config: dict) -> str:
+    """Generate the full content of a specialist agent file.
+
+    The generated file embeds two things: the generic template contract chosen
+    by the brief's `kind`, and the project brief body. Text that can contain
+    arbitrary characters (the description and a routing model pin) is written
+    as a JSON-escaped double-quoted YAML scalar, so YAML indicator characters
+    cannot break parsing or inject frontmatter keys. Enum-bound values
+    (`reasoning`, `effort`) are validated first and then emitted plain.
+
+    Resolution order (most specific wins):
+      - reasoning: routing policy -> brief -> `max`
+      - effort/temperature: routing policy -> brief -> `high`
+      - model: routing policy only (no hardcoded model)
+      - permissions: template default, tightened by a routing sandbox override,
+        with reviewer `edit` forced to `deny`.
+
+    Args:
+        plugin_root: Package root containing `agent-templates/`.
+        role: Validated specialist role name.
+        brief: Parsed brief returned by `parse_brief`.
+        role_config: Routing policy for this role (may be empty).
+
+    Returns:
+        The complete agent Markdown file content.
+    """
+    template_name = CUSTOM_TEMPLATES[brief["kind"]]
+
+    effort = role_config.get("effort") or brief.get("effort") or "high"
+    if effort not in EFFORT_TO_TEMPERATURE:
+        raise BriefError(
+            f"unsupported routing effort {effort!r}; supported values: "
+            f"{', '.join(sorted(EFFORT_TO_TEMPERATURE))}"
+        )
+    temperature = EFFORT_TO_TEMPERATURE[effort]
+
+    reasoning = role_config.get("reasoning") or brief.get("reasoning") or "max"
+    if reasoning not in REASONING_VALUES:
+        raise BriefError(
+            f"unsupported routing reasoning {reasoning!r}; supported values: "
+            f"{', '.join(REASONING_VALUES)}"
+        )
+
+    model = role_config.get("model") or None
+
+    permissions = dict(TEMPLATE_PERMISSIONS[template_name])
+    sandbox = role_config.get("sandbox")
+    if sandbox:
+        if sandbox not in SANDBOX_PERMISSIONS:
+            raise BriefError(
+                f"unsupported routing sandbox {sandbox!r}; supported values: "
+                f"{', '.join(sorted(SANDBOX_PERMISSIONS))}"
+            )
+        permissions.update(SANDBOX_PERMISSIONS[sandbox])
+    if brief["kind"] == "reviewer":
+        permissions["edit"] = "deny"
+
+    lines = [
+        CODEOPS_MARKER,
+        f"# Role: {role} | Template: {template_name}",
+        "# Do not edit this file manually — regenerate with: install_agents.py",
+        "---",
+        f"description: {json.dumps(brief['description'])}",
+        "mode: subagent",
+    ]
+    if model:
+        lines.append(f"model: {json.dumps(model)}")
+    lines.append(f"temperature: {temperature}")
+    lines.append(f"hidden: {'true' if brief['hidden'] else 'false'}")
+    lines.append(f"reasoningEffort: {reasoning}")
+    lines.append("permission:")
+    for key, value in permissions.items():
+        lines.append(f"  {key}: {value}")
+    lines.append("---")
+    frontmatter = "\n".join(lines) + "\n"
+
+    contract = load_template_body(plugin_root, template_name).strip()
+    body = str(brief["body"]).strip("\n")
+    return f"{frontmatter}\n{contract}\n\n---\n\n{body}\n"
+
+
+def write_generated_file(path: Path, content: str) -> None:
+    """Write generated content with a hardened open.
+
+    The target is opened with `O_NOFOLLOW` where the platform supports it, so a
+    symlink swapped in after the caller's checks cannot redirect the write.
+    This is a plain write (truncate and write), not an atomic replace.
+
+    Args:
+        path: Destination file.
+        content: Full file content.
+
+    Raises:
+        BriefError: If the file cannot be opened or written.
+    """
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags, 0o644)
+    except OSError as exc:
+        raise BriefError(f"cannot write {path}: {exc}") from exc
+    with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+        handle.write(content)
+
+
+def dominant_newline(content: str) -> str:
+    """Return the dominant line ending of a text file's content.
+
+    Args:
+        content: File content read without newline translation.
+
+    Returns:
+        `"\\r\\n"` when CRLF pairs outnumber lone LF characters, else `"\\n"`.
+    """
+    crlf = content.count("\r\n")
+    lone_lf = content.count("\n") - crlf
+    return "\r\n" if crlf > lone_lf else "\n"
+
+
+def read_with_newlines(path: Path) -> str:
+    """Read a text file without newline translation.
+
+    Python's default text mode rewrites CRLF to LF on read; the AGENTS.md sync
+    must see the file exactly as it is so it can preserve the dominant line
+    ending. This reads with `newline=""` so no translation happens.
+
+    Args:
+        path: File to read.
+
+    Returns:
+        The file content with its original line endings.
+
+    Raises:
+        OSError: If the file cannot be read.
+        UnicodeDecodeError: If the file is not valid UTF-8.
+    """
+    with path.open("r", encoding="utf-8", newline="") as handle:
+        return handle.read()
+
+
+def collect_briefs(project: Path) -> tuple[dict, list]:
+    """Collect and validate every specialist brief in a project.
+
+    Args:
+        project: Resolved project root.
+
+    Returns:
+        A tuple `(briefs, errors)`. `briefs` maps role -> parsed brief; each
+        entry in `errors` is a ready-to-print `INVALID: <role> — <reason>`
+        line. A symlinked specialists directory is reported as one error and
+        yields no briefs.
+    """
+    brief_dir = project / "codeops" / "specialists"
+    briefs: dict[str, dict] = {}
+    errors: list[str] = []
+    if brief_dir.is_symlink():
+        return briefs, ["INVALID: specialists — refusing to read through a symlinked directory"]
+    if not brief_dir.is_dir():
+        return briefs, errors
+    for path in sorted(brief_dir.glob("*.md")):
+        role = path.stem
+        if path.is_symlink():
+            errors.append(f"INVALID: {role} — brief is a symlink")
+            continue
+        try:
+            briefs[role] = parse_brief(path, role)
+        except BriefError as exc:
+            errors.append(f"INVALID: {role} — {exc}")
+    return briefs, errors
+
+
+def generated_custom_template(path: Path) -> Optional[str]:
+    """Return the template name recorded in a generated agent's header.
+
+    Args:
+        path: Candidate generated agent file.
+
+    Returns:
+        The template name (for example `domain-specialist-reviewer`) when the
+        file carries the CodeOps ownership marker and role header, otherwise
+        `None`.
+    """
+    if not is_codeops_generated(path):
+        return None
+    try:
+        lines = path.read_text(encoding="utf-8").split("\n", 3)[:3]
+    except (OSError, UnicodeDecodeError):
+        return None
+    for line in lines:
+        match = re.fullmatch(r"# Role: .+ \| Template: (.+)", line)
+        if match:
+            return match.group(1)
+    return None
+
+
+def render_agents_block(briefs: dict, newline: str) -> str:
+    """Render the managed AGENTS.md block for a set of briefs.
+
+    Args:
+        briefs: Role -> parsed brief mapping.
+        newline: Line ending to use (`\\n` or `\\r\\n`).
+
+    Returns:
+        The block text without a trailing newline.
+    """
+    lines = [
+        AGENTS_START,
+        "Specialist agents (routing: `codeops/codeops.json`; briefs: `codeops/specialists/`):",
+    ]
+    roles = sorted(briefs)
+    for role in roles[:AGENTS_ENTRY_BUDGET]:
+        entry = f'- `{role}` — "{briefs[role]["description"]}"'
+        required_for = briefs[role].get("required-for")
+        if required_for:
+            entry += f" (Required for: {required_for})"
+        lines.append(entry)
+    if len(roles) > AGENTS_ENTRY_BUDGET:
+        lines.append(f"- …and {len(roles) - AGENTS_ENTRY_BUDGET} more; see codeops/specialists/")
+    lines.append(AGENTS_END)
+    return newline.join(lines)
+
+
+def classify_agents_block(content: str) -> tuple[str, int, int]:
+    """Classify the marker layout of an AGENTS.md file.
+
+    Args:
+        content: Current AGENTS.md content (empty string when absent).
+
+    Returns:
+        `("absent", -1, -1)` when no markers exist, or
+        `("present", start, end)` when exactly one ordered pair exists.
+
+    Raises:
+        BriefError: For one marker, duplicate markers, or reversed order.
+    """
+    starts = content.count(AGENTS_START)
+    ends = content.count(AGENTS_END)
+    if starts == 0 and ends == 0:
+        return "absent", -1, -1
+    if starts == 1 and ends == 1:
+        start = content.find(AGENTS_START)
+        end = content.find(AGENTS_END)
+        if start < end:
+            return "present", start, end
+    raise BriefError("AGENTS.md contains malformed specialist markers")
+
+
+def compute_agents_md(project: Path, briefs: dict) -> tuple:
+    """Compute the post-change AGENTS.md content for a set of briefs.
+
+    Args:
+        project: Resolved project root.
+        briefs: Briefs that should be listed after the operation.
+
+    Returns:
+        A tuple `(path, new_content, error)`. `new_content` is `None` when no
+        change is needed; `error` is a message when the current file cannot be
+        updated safely.
+
+    Raises:
+        BriefError: If the file is unreadable or not a regular file.
+    """
+    path = project / "AGENTS.md"
+    if path.is_symlink():
+        return path, None, "refusing to write through a symlinked AGENTS.md"
+    exists = path.exists()
+    if exists and not path.is_file():
+        return path, None, "AGENTS.md is not a regular file"
+    if not exists:
+        content = ""
+    else:
+        try:
+            content = read_with_newlines(path)
+        except UnicodeDecodeError:
+            return path, None, "AGENTS.md is not valid UTF-8"
+        except OSError as exc:
+            return path, None, f"cannot read AGENTS.md: {exc}"
+
+    newline = dominant_newline(content)
+    try:
+        state, start, end = classify_agents_block(content)
+    except BriefError as exc:
+        return path, None, str(exc)
+    block = render_agents_block(briefs, newline)
+
+    if state == "present":
+        if not briefs:
+            remove_start = start
+            remove_end = end + len(AGENTS_END)
+            if content[:remove_start].endswith(newline + newline):
+                remove_start -= len(newline)
+            if content[remove_end:].startswith(newline):
+                remove_end += len(newline)
+            return path, content[:remove_start] + content[remove_end:], None
+        return path, content[:start] + block + content[end + len(AGENTS_END):], None
+
+    if not briefs:
+        return path, None, None
+    if not exists or content == "":
+        return path, block + newline, None
+    base = content
+    if not base.endswith(("\n", "\r")):
+        base += newline
+    separator = "" if base.endswith(newline + newline) else newline
+    return path, base + separator + block + newline, None
+
+
+def run_sync_agents_md(project: Path, dry_run: bool) -> int:
+    """Render and apply the managed specialist block in AGENTS.md.
+
+    Args:
+        project: Resolved project root.
+        dry_run: When True, report the intended change and write nothing.
+
+    Returns:
+        Process exit code (0 on success, 1 when a brief or the file is invalid).
+    """
+    try:
+        briefs, errors = collect_briefs(project)
+        if errors:
+            for error in errors:
+                print(error)
+            return 1
+        path, new_content, error = compute_agents_md(project, briefs)
+        if error:
+            raise BriefError(error)
+        if new_content is None:
+            print("AGENTS.md: no specialist block to change")
+            return 0
+        if dry_run:
+            print(f"  [dry-run] would update: {path} ({len(briefs)} specialist(s))")
+            return 0
+        if path.exists() and not os.access(path, os.W_OK):
+            raise BriefError(f"AGENTS.md is not writable: {path}")
+        write_generated_file(path, new_content)
+        print(f"  updated: {path.name} ({len(briefs)} specialist(s))")
+        return 0
+    except BriefError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def run_check(project: Path, plugin_root: Path, roles: list, routing_roles: dict) -> int:
+    """Report catalog, custom, orphan, and AGENTS.md states.
+
+    Args:
+        project: Resolved project root.
+        plugin_root: Package root containing `agent-templates/`.
+        roles: Catalog roles requested for the default check.
+        routing_roles: Parsed `routing.roles` policy from `codeops.json`.
+
+    Returns:
+        Process exit code: 1 when any issue is reported, otherwise 0 with a
+        `OK: N default, M custom` summary.
+    """
+    agents_dir = project / ".opencode" / "agents"
+    issues: list[str] = []
+    for role in roles:
+        out_path = agents_dir / f"{role}.md"
+        if not out_path.exists():
+            issues.append(f"MISSING: {out_path}")
+        elif not is_codeops_generated(out_path):
+            issues.append(f"HAND-AUTHORED (skip): {out_path}")
+
+    briefs, errors = collect_briefs(project)
+    issues.extend(errors)
+    for role, brief in sorted(briefs.items()):
+        out_path = agents_dir / f"{role}.md"
+        if out_path.is_symlink() or (out_path.exists() and not out_path.is_file()):
+            issues.append(f"HAND-AUTHORED: {role} (not managed)")
+            continue
+        if not out_path.exists():
+            issues.append(f"MISSING: {role}")
+            continue
+        if not is_codeops_generated(out_path):
+            issues.append(f"HAND-AUTHORED: {role} (not managed)")
+            continue
+        try:
+            expected = generate_custom_agent(plugin_root, role, brief, routing_roles.get(role, {}))
+        except BriefError as exc:
+            issues.append(f"INVALID: {role} — {exc}")
+            continue
+        try:
+            current = out_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            issues.append(f"STALE: {role}")
+            continue
+        if current != expected:
+            issues.append(f"STALE: {role}")
+
+    if agents_dir.is_dir():
+        for file in sorted(agents_dir.glob("*.md")):
+            template = generated_custom_template(file)
+            if not template or not template.startswith(CUSTOM_TEMPLATE_PREFIX):
+                continue
+            if file.stem in briefs:
+                continue
+            if (project / "codeops" / "specialists" / f"{file.stem}.md").is_file():
+                # The brief exists but failed validation; INVALID was reported.
+                continue
+            issues.append(f"ORPHAN: {file.stem}")
+
+    if briefs:
+        agents_path = project / "AGENTS.md"
+        if agents_path.is_symlink() or (agents_path.exists() and not agents_path.is_file()):
+            issues.append("AGENTS.md STALE")
+        elif not agents_path.exists():
+            issues.append("AGENTS.md MISSING (file)")
+        else:
+            try:
+                content = read_with_newlines(agents_path)
+                state, _, _ = classify_agents_block(content)
+            except (OSError, UnicodeDecodeError, BriefError):
+                issues.append("AGENTS.md STALE")
+            else:
+                newline = dominant_newline(content)
+                if state == "absent":
+                    issues.append("AGENTS.md MISSING (block)")
+                elif render_agents_block(briefs, newline) not in content:
+                    issues.append("AGENTS.md STALE")
+
+    if issues:
+        print("Agent check found issues:")
+        for issue in issues:
+            print(f"  {issue}")
+        return 1
+    print(f"OK: {len(roles)} default, {len(briefs)} custom")
+    return 0
+
+
+def run_remove_custom(project: Path, role: str, yes: bool, dry_run: bool) -> int:
+    """Remove a generated specialist agent and its brief after confirmation.
+
+    Args:
+        project: Resolved project root.
+        role: Role requested with `--remove-custom`.
+        yes: Confirms the deletion.
+        dry_run: When True, report the intended deletions and change nothing.
+
+    Returns:
+        Process exit code (0 on success, 1 on any refusal).
+    """
+    try:
+        validate_role_name(role)
+        project_root = project.resolve()
+        opencode_dir = project / ".opencode"
+        if opencode_dir.is_symlink():
+            raise BriefError(f"refusing to remove through a symlinked directory: {opencode_dir}")
+        agents_dir = opencode_dir / "agents"
+        if agents_dir.is_symlink():
+            raise BriefError(f"refusing to remove through a symlinked directory: {agents_dir}")
+        if project_root not in agents_dir.resolve().parents:
+            raise BriefError(f"agent directory escapes the project root: {agents_dir}")
+        specialists_dir = project / "codeops" / "specialists"
+        if specialists_dir.is_symlink():
+            raise BriefError(f"refusing to remove through a symlinked directory: {specialists_dir}")
+        if project_root not in specialists_dir.resolve().parents:
+            raise BriefError(f"specialists directory escapes the project root: {specialists_dir}")
+        agent_path = agents_dir / f"{role}.md"
+        brief_path = specialists_dir / f"{role}.md"
+        if brief_path.is_symlink():
+            raise BriefError(f"refusing to remove through a symlinked brief: {brief_path}")
+
+        agent_is_link = agent_path.is_symlink()
+        agent_exists = agent_path.exists() or agent_is_link
+        brief_exists = brief_path.is_file()
+        if agent_exists and not agent_is_link:
+            if not agent_path.is_file():
+                raise BriefError(f"refusing to remove a non-regular file: {agent_path}")
+            template = generated_custom_template(agent_path)
+            if not template or not template.startswith(CUSTOM_TEMPLATE_PREFIX):
+                raise BriefError(f"refusing to remove {role!r}: not a generated specialist agent")
+        if not agent_exists and not brief_exists:
+            raise BriefError(f"nothing to remove for role {role!r}")
+
+        briefs, errors = collect_briefs(project)
+        if errors:
+            for error in errors:
+                print(error)
+            return 1
+        remaining = {name: brief for name, brief in briefs.items() if name != role}
+        agents_path, new_content, error = compute_agents_md(project, remaining)
+        if error:
+            raise BriefError(error)
+        if agents_path.exists() and not os.access(agents_path, os.W_OK):
+            raise BriefError(f"AGENTS.md is not writable: {agents_path}")
+
+        if not yes or dry_run:
+            if agent_exists:
+                print(f"Would delete: {agent_path}")
+            else:
+                print(f"MISSING: {role} (no generated agent)")
+            if brief_exists:
+                print(f"Would delete: {brief_path}")
+            else:
+                print(f"ORPHAN: {role} (generated agent without a brief)")
+            print("Pass --yes to delete (dry-run always wins).")
+            return 0
+
+        if agent_is_link:
+            os.unlink(agent_path)
+        elif agent_exists:
+            agent_path.unlink()
+        if brief_exists:
+            brief_path.unlink()
+        if new_content is not None:
+            write_generated_file(agents_path, new_content)
+        print(f"Removed: {role}")
+        return 0
+    except BriefError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+def run_custom(
+    project: Path,
+    plugin_root: Path,
+    role: str,
+    routing_roles: dict,
+    dry_run: bool,
+) -> int:
+    """Generate one specialist agent from its brief, or report why it cannot.
+
+    Every check happens before the first write: naming, brief resolution
+    (symlinks refused), brief validation, and target path safety (symlinked
+    directories or files, paths escaping the project root, non-regular files,
+    and hand-authored files are all refused). The final write opens the target
+    with `O_NOFOLLOW` so a last-moment symlink swap cannot redirect it. A
+    failure reports on stderr and returns 1 with the project unchanged.
+
+    Args:
+        project: Resolved project root.
+        plugin_root: Package root containing `agent-templates/`.
+        role: Role requested with `--custom`.
+        routing_roles: Parsed `routing.roles` policy from `codeops.json`.
+        dry_run: When True, report the intended write and change nothing.
+
+    Returns:
+        Process exit code (0 on success, 1 on any validation failure).
+    """
+    try:
+        validate_role_name(role)
+        project_root = project.resolve()
+        brief_dir = project / "codeops" / "specialists"
+        if brief_dir.is_symlink():
+            raise BriefError(f"refusing to read through a symlinked directory: {brief_dir}")
+        brief_path = brief_dir / f"{role}.md"
+        if brief_path.is_symlink():
+            raise BriefError(f"refusing to read through a symlinked brief: {brief_path}")
+        if not brief_path.is_file():
+            raise BriefError(f"brief not found: {brief_path}")
+        if project_root not in brief_path.resolve().parents:
+            raise BriefError(f"brief path escapes the project root: {brief_path}")
+        brief = parse_brief(brief_path, role)
+
+        opencode_dir = project / ".opencode"
+        if opencode_dir.is_symlink():
+            raise BriefError(f"refusing to write through a symlinked directory: {opencode_dir}")
+        agents_dir = opencode_dir / "agents"
+        if agents_dir.is_symlink():
+            raise BriefError(f"refusing to write through a symlinked directory: {agents_dir}")
+        if project_root not in agents_dir.resolve().parents:
+            raise BriefError(f"agent directory escapes the project root: {agents_dir}")
+        out_path = agents_dir / f"{role}.md"
+        if out_path.is_symlink():
+            raise BriefError(f"refusing to write through a symlinked file: {out_path}")
+        if out_path.exists() and not out_path.is_file():
+            raise BriefError(f"refusing to write to a non-regular file: {out_path}")
+        if out_path.is_file() and not is_codeops_generated(out_path):
+            raise BriefError(
+                f"refusing to overwrite hand-authored file: {out_path} "
+                "(rename or remove it manually first)"
+            )
+
+        content = generate_custom_agent(plugin_root, role, brief, routing_roles.get(role, {}))
+        if dry_run:
+            print(f"  [dry-run] would write: {out_path}")
+            print(f"    kind={brief['kind']}, reasoning={routing_roles.get(role, {}).get('reasoning', brief.get('reasoning') or 'max')}")
+            return 0
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        write_generated_file(out_path, content)
+        print(f"  wrote: {out_path.name}")
+        return 0
+    except BriefError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="Generate OpenCode agent files from CodeOps routing config."
     )
     parser.add_argument("--project", required=True, help="Path to the project root")
     parser.add_argument("--roles", help="Comma-separated list of roles to install (default: all)")
-    parser.add_argument("--check", action="store_true", help="Check for missing or stale agents without writing")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument(
+        "--custom",
+        metavar="ROLE",
+        help="Generate one project specialist agent from codeops/specialists/ROLE.md",
+    )
+    mode.add_argument(
+        "--remove-custom",
+        metavar="ROLE",
+        help="Delete a generated specialist agent and its brief (needs --yes)",
+    )
+    mode.add_argument(
+        "--sync-agents-md",
+        action="store_true",
+        help="Render or update the managed specialist block in AGENTS.md",
+    )
+    mode.add_argument("--check", action="store_true", help="Check for missing or stale agents without writing")
+    parser.add_argument("--yes", action="store_true", help="Confirm destructive --remove-custom deletions")
     parser.add_argument("--dry-run", action="store_true", help="Show what would be written without writing")
     args = parser.parse_args()
 
@@ -231,25 +1172,16 @@ def main() -> int:
         )
         return 1
 
-    agents_dir = project / ".opencode" / "agents"
-
+    if args.custom:
+        return run_custom(project, plugin_root, args.custom, routing_roles, args.dry_run)
+    if args.remove_custom:
+        return run_remove_custom(project, args.remove_custom, args.yes, args.dry_run)
+    if args.sync_agents_md:
+        return run_sync_agents_md(project, args.dry_run)
     if args.check:
-        # Check mode: report missing or stale files
-        issues = []
-        for role in roles:
-            out_path = agents_dir / f"{role}.md"
-            if not out_path.exists():
-                issues.append(f"MISSING: {out_path}")
-            elif not is_codeops_generated(out_path):
-                issues.append(f"HAND-AUTHORED (skip): {out_path}")
-        if issues:
-            print("Agent check found issues:")
-            for i in issues:
-                print(f"  {i}")
-            return 1
-        else:
-            print(f"OK: all {len(roles)} CodeOps agent files present.")
-            return 0
+        return run_check(project, plugin_root, roles, routing_roles)
+
+    agents_dir = project / ".opencode" / "agents"
 
     # Generate and write (or dry-run)
     if not args.dry_run: