pi-dev-team 0.2.0

package/skills/upgrade/scripts/enable_autoupdate.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Report or enable marketplace auto-update for the dev-team plugin.
+
+Single source of truth for the ``extraKnownMarketplaces.<market>.autoUpdate``
+flag — the same flag the ``/plugin`` UI toggles (there is no dedicated
+``claude plugin`` CLI subcommand for it). With it on, the CLI re-pulls the
+marketplace catalog and upgrades the plugin at launch, which is what keeps a
+Claude Code web session current despite its reused filesystem snapshot pinning
+the first-installed version.
+
+Two callers share this one implementation, so the flag logic lives in exactly
+one place:
+
+* the ``/upgrade`` skill (``SKILL.md`` step 2) — runs ``--check`` to report
+  status, asks the user for consent, then runs ``--enable`` only on "yes";
+* the cloud bootstrap (``.claude/cloud-setup.sh`` and
+  ``.claude/install-dev-team.sh``) — runs ``--enable`` directly, no consent,
+  because pasting the Setup script / setting ``DEV_TEAM_CLOUD_INSTALL=1`` is
+  itself the opt-in for an ephemeral cloud VM.
+
+Modes:
+  --check    Print ``enabled`` / ``disabled`` / ``unknown`` and exit (read-only).
+  --enable   Set the flag to true, idempotently (the default if no mode given).
+
+Idempotent and fail-open: ``--enable`` never exits non-zero, so it can never
+break a Setup script or block session start. Honors ``CLAUDE_CONFIG_DIR``.
+Stdlib only, (ADR 0014 / 0015).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+PLUGIN = "dev-team"
+
+
+def config_dir() -> str:
+    """The Claude Code config dir — ``CLAUDE_CONFIG_DIR`` if set, else ~/.claude."""
+    return os.environ.get("CLAUDE_CONFIG_DIR") or os.path.join(
+        os.path.expanduser("~"), ".claude"
+    )
+
+
+def load(path: str):
+    """Parse a JSON file, or return None if it is missing or malformed."""
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def resolve_market(cfg: str) -> str | None:
+    """The marketplace id the plugin is installed from (the ``@<market>`` half
+    of its ``installed_plugins.json`` key), or None if it is not installed."""
+    installed = (
+        load(os.path.join(cfg, "plugins", "installed_plugins.json")) or {}
+    ).get("plugins", {})
+    return next(
+        (
+            pid.split("@", 1)[1]
+            for pid in installed
+            if pid.split("@", 1)[0] == PLUGIN and "@" in pid
+        ),
+        None,
+    )
+
+
+def settings_candidates(cfg: str) -> list[str]:
+    """Settings files to consult, project-scoped first (mirrors the CLI/UI
+    precedence), falling back to the config-dir user settings."""
+    cwd = os.getcwd()
+    return [
+        os.path.join(cwd, ".claude", "settings.json"),
+        os.path.join(cwd, ".claude", "settings.local.json"),
+        os.path.join(cfg, "settings.json"),
+    ]
+
+
+def check(cfg: str) -> str:
+    """Return ``enabled`` / ``disabled`` / ``unknown`` for the auto-update flag."""
+    market = resolve_market(cfg)
+    if not market:
+        return "unknown"
+    for path in settings_candidates(cfg):
+        data = load(path)
+        if data and market in (data.get("extraKnownMarketplaces") or {}):
+            return "enabled" if data["extraKnownMarketplaces"][market].get(
+                "autoUpdate"
+            ) is True else "disabled"
+    return "disabled"
+
+
+def _target(cfg: str, market: str) -> tuple[str, dict]:
+    """Pick the settings file to write, seeding a fresh config-dir entry from the
+    marketplace registry when no existing file already declares the market."""
+    for path in settings_candidates(cfg):
+        data = load(path)
+        if data and market in (data.get("extraKnownMarketplaces") or {}):
+            return path, data
+    path = os.path.join(cfg, "settings.json")
+    data = load(path) or {}
+    reg = load(os.path.join(cfg, "plugins", "known_marketplaces.json")) or {}
+    entry = reg.get(market)
+    ekm = data.setdefault("extraKnownMarketplaces", {})
+    ekm[market] = {"source": entry["source"]} if entry else {}
+    return path, data
+
+
+def enable(cfg: str) -> str:
+    """Set the flag to true idempotently. Returns a one-line status message."""
+    market = resolve_market(cfg)
+    if not market:
+        return f"'{PLUGIN}' not installed under {cfg}; nothing to do"
+    path, data = _target(cfg, market)
+    mk = data.setdefault("extraKnownMarketplaces", {}).setdefault(market, {})
+    if mk.get("autoUpdate") is True:
+        return f"already enabled for '{market}' ({path})"
+    mk["autoUpdate"] = True
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+    return f"enabled for '{market}' in {path}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--check", action="store_true", help="Report status only.")
+    group.add_argument("--enable", action="store_true", help="Enable (default).")
+    args = parser.parse_args(argv)
+    cfg = config_dir()
+    if args.check:
+        print(check(cfg))
+        return 0
+    # Default action is --enable; fail-open so a bootstrap never breaks.
+    try:
+        print(enable(cfg))
+    except Exception as exc:  # noqa: BLE001 - never fail the calling setup/hook
+        print(f"non-fatal error: {exc}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/version/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: version
+description: >-
+  Report the installed version of the pi-dev-team package and the upstream
+  dev-team release it was synced from.
+user-invocable: true
+allowed-tools: Bash
+---
+
+# Version
+
+Role: worker. Purely mechanical lookup.
+
+You have been invoked with the `/version` command. Arguments: none.
+
+Run and report the single output line verbatim:
+
+```bash
+node -e 'const p=require(process.env.CLAUDE_PLUGIN_ROOT+"/package.json");const u=require(process.env.CLAUDE_PLUGIN_ROOT+"/UPSTREAM.json");console.log(`${p.name} v${p.version} (upstream dev-team v${u.version} @ ${String(u.commit).slice(0,10)})`)'
+```
+
+If `CLAUDE_PLUGIN_ROOT` is unset, report exactly:
+`pi-dev-team extension is not loaded in this session.`
+
+Do not add commentary beyond the single result line.

package/sync/sync_upstream.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""Sync upstream bdfinst/agentic-dev-team `plugins/dev-team` into this pi package.
+
+Usage:
+  python3 sync/sync_upstream.py --upstream /path/to/agentic-dev-team [--check]
+
+What it does (idempotent, stdlib only):
+  1. Replaces the managed directories (agents, skills, hooks, scripts, knowledge,
+     templates, tools, docs/upstream) with fresh copies from upstream.
+  2. Drops skills that only make sense inside Claude Code (DROPPED_SKILLS).
+  3. Copies pi-specific replacements from overrides/ over the result.
+  4. Normalises SKILL.md frontmatter for pi (description <= 1024 chars).
+  5. Applies the small, explicit text patch set (PATCHES). Every patch must
+     match at least once, so upstream drift is caught instead of silently
+     skipped.
+  6. Writes UPSTREAM.json (commit, version, what was dropped/overridden/patched).
+
+Everything not listed here (extensions/, bin/, sync/, overrides/, test/,
+PORTING.md, README.md, package.json) is owned by the port and never touched.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+PKG = Path(__file__).resolve().parent.parent
+PLUGIN_SUBDIR = Path("plugins/dev-team")
+
+MANAGED_DIRS = ["agents", "skills", "hooks", "scripts", "knowledge", "templates", "tools"]
+UPSTREAM_DOCS_DEST = Path("docs/upstream")
+
+# Skills that test, audit or drive Claude Code itself. See PORTING.md section 4.
+DROPPED_SKILLS = [
+    "agent-audit",
+    "agent-eval",
+    "claude-setup-review",
+    "harness-e2e-check",
+    "long-eval",
+    "orchestration-benchmark",
+    "session-review",
+]
+
+IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc", ".pytest_cache", ".mypy_cache", ".ruff_cache")
+
+DESCRIPTION_LIMIT = 1024
+
+# (glob relative to package root, regex, replacement, description)
+PATCHES: list[tuple[str, str, str, str]] = [
+    (
+        "skills/plan/SKILL.md",
+        r"or stdin is not a usable TTY \(`test -t 0` is false — the headless/CI/automation case\)",
+        "or `DEV_TEAM_INTERACTIVE` is not `1` (pi sets it only when a human UI is attached; "
+        "a tool shell never has a TTY, so `test -t 0` must not be used — the headless/CI/automation case)",
+        "interactivity: tool shells have no TTY in pi",
+    ),
+    (
+        "skills/build/SKILL.md",
+        r"or stdin is not a usable TTY \(`test -t 0` is false — the headless/CI/automation case\)",
+        "or `DEV_TEAM_INTERACTIVE` is not `1` (pi sets it only when a human UI is attached; "
+        "a tool shell never has a TTY, so `test -t 0` must not be used — the headless/CI/automation case)",
+        "interactivity: tool shells have no TTY in pi",
+    ),
+    (
+        "skills/review-agent/SKILL.md",
+        r"Read `\.claude/agents/<name>\.md`\. If the file doesn't exist, list available\s+review agents from `\.claude/agents/`",
+        "Read `.claude/agents/<name>.md` (project override) or else `${CLAUDE_PLUGIN_ROOT}/agents/<name>.md`. "
+        "If neither exists, list available\nreview agents from `${CLAUDE_PLUGIN_ROOT}/agents/`",
+        "agent definitions live in the package, not the project",
+    ),
+    (
+        "skills/help/SKILL.md",
+        r"1\. Use Glob to find every `skills/\*/SKILL\.md` file\.",
+        "1. Use `find` to list every `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md` file, plus project skills in "
+        "`.pi/skills/*/SKILL.md` and `.claude/skills/*/SKILL.md`.",
+        "skills live in the package root",
+    ),
+    (
+        "skills/triage/SKILL.md",
+        r'Use the Agent tool with `subagent_type: "Explore"`',
+        'Use the `dev_team_subagent` tool with `agent: "Explore"`',
+        "Claude's built-in Explore agent is provided by the port",
+    ),
+]
+
+
+def run(cmd: list[str], cwd: Path) -> str:
+    try:
+        return subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, check=False).stdout.strip()
+    except OSError:
+        return ""
+
+
+def split_frontmatter(text: str) -> tuple[list[str], str] | None:
+    if not text.startswith("---"):
+        return None
+    lines = text.split("\n")
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            return lines[1:i], "\n".join(lines[i + 1 :])
+    return None
+
+
+def fm_blocks(fm_lines: list[str]) -> list[tuple[str | None, list[str]]]:
+    """Group frontmatter into top-level key blocks (key line + indented continuation)."""
+    blocks: list[tuple[str | None, list[str]]] = []
+    for line in fm_lines:
+        m = re.match(r"^([A-Za-z0-9_-]+):", line)
+        if m and not line.startswith((" ", "\t")):
+            blocks.append((m.group(1), [line]))
+        elif blocks:
+            blocks[-1][1].append(line)
+        else:
+            blocks.append((None, [line]))
+    return blocks
+
+
+def block_value(lines: list[str]) -> str:
+    first = lines[0].split(":", 1)[1].strip()
+    rest = [l.strip() for l in lines[1:]]
+    if first in (">", "|", ">-", "|-", ""):
+        return " ".join(r for r in rest if r)
+    val = " ".join([first] + [r for r in rest if r])
+    if len(val) >= 2 and val[0] == val[-1] and val[0] in "\"'":
+        val = val[1:-1]
+    return val
+
+
+def trim_description(desc: str) -> str:
+    if len(desc) <= DESCRIPTION_LIMIT:
+        return desc
+    cut = desc[: DESCRIPTION_LIMIT - 1]
+    # prefer ending at a sentence boundary
+    dot = cut.rfind(". ")
+    if dot > DESCRIPTION_LIMIT * 0.6:
+        cut = cut[: dot + 1]
+    return cut.rstrip() + ("" if cut.endswith(".") else "…")
+
+
+def normalise_skill(path: Path) -> bool:
+    text = path.read_text(encoding="utf-8")
+    parts = split_frontmatter(text)
+    if not parts:
+        return False
+    fm_lines, body = parts
+    changed = False
+    out: list[str] = []
+    for key, lines in fm_blocks(fm_lines):
+        if key == "description":
+            desc = block_value(lines)
+            trimmed = trim_description(desc)
+            if trimmed != desc:
+                out.append("description: " + json.dumps(trimmed, ensure_ascii=False))
+                changed = True
+                continue
+        out.extend(lines)
+    if changed:
+        path.write_text("---\n" + "\n".join(out) + "\n---\n" + body, encoding="utf-8")
+    return changed
+
+
+NOTE_MARKER = "<!-- pi-port-notes -->"
+
+
+def insert_note(skill_md: Path, note: str) -> None:
+    """Insert a pi port note block after the first H1 (or after frontmatter)."""
+    text = skill_md.read_text(encoding="utf-8")
+    if NOTE_MARKER in text:
+        return
+    block = f"\n{NOTE_MARKER}\n{note.strip()}\n{NOTE_MARKER}\n"
+    m = re.search(r"^# .*$", text, flags=re.M)
+    if m:
+        text = text[: m.end()] + "\n" + block + text[m.end() :]
+    else:
+        parts = split_frontmatter(text)
+        text = text + block if not parts else text.replace("\n---\n", "\n---\n" + block, 1)
+    skill_md.write_text(text, encoding="utf-8")
+
+
+def copy_tree(src: Path, dst: Path) -> None:
+    if dst.exists():
+        shutil.rmtree(dst)
+    shutil.copytree(src, dst, ignore=IGNORE, symlinks=True)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--upstream", required=True, help="checkout of bdfinst/agentic-dev-team")
+    args = ap.parse_args()
+
+    upstream = Path(args.upstream).resolve()
+    plugin = upstream / PLUGIN_SUBDIR
+    if not (plugin / "agents").is_dir():
+        print(f"error: {plugin} does not look like plugins/dev-team", file=sys.stderr)
+        return 2
+
+    for name in MANAGED_DIRS:
+        src = plugin / name
+        if src.is_dir():
+            copy_tree(src, PKG / name)
+    if (plugin / "docs").is_dir():
+        copy_tree(plugin / "docs", PKG / UPSTREAM_DOCS_DEST)
+    for fname, dest in (("CHANGELOG.md", "docs/upstream/CHANGELOG.md"), ("README.md", "docs/upstream/README.md")):
+        if (plugin / fname).is_file():
+            shutil.copy2(plugin / fname, PKG / dest)
+
+    # hooks/lib/plugin_version.py reads <root>/.claude-plugin/plugin.json for the version stamped on metrics rows.
+    if (plugin / ".claude-plugin" / "plugin.json").is_file():
+        (PKG / ".claude-plugin").mkdir(exist_ok=True)
+        shutil.copy2(plugin / ".claude-plugin" / "plugin.json", PKG / ".claude-plugin" / "plugin.json")
+
+    dropped = []
+    for skill in DROPPED_SKILLS:
+        target = PKG / "skills" / skill
+        if target.exists():
+            shutil.rmtree(target)
+            dropped.append(skill)
+
+    overridden: list[str] = []
+    overrides = PKG / "overrides"
+    if overrides.is_dir():
+        for src in sorted(overrides.rglob("*")):
+            if src.is_file() and "__pycache__" not in src.parts and src.relative_to(overrides).parts[0] != "notes":
+                rel = src.relative_to(overrides)
+                dst = PKG / rel
+                dst.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src, dst)
+                overridden.append(str(rel))
+
+    noted: list[str] = []
+    for note in sorted((overrides / "notes").glob("*.md")) if (overrides / "notes").is_dir() else []:
+        skill_md = PKG / "skills" / note.stem / "SKILL.md"
+        if not skill_md.is_file():
+            print(f"warning: note for missing skill {note.stem}", file=sys.stderr)
+            continue
+        insert_note(skill_md, note.read_text(encoding="utf-8"))
+        noted.append(note.stem)
+
+    normalised = [
+        str(p.relative_to(PKG)) for p in sorted((PKG / "skills").glob("*/SKILL.md")) if normalise_skill(p)
+    ]
+
+    patched: list[dict[str, object]] = []
+    failures: list[str] = []
+    for pattern, regex, repl, why in PATCHES:
+        files = sorted(PKG.glob(pattern))
+        hits = 0
+        for f in files:
+            text = f.read_text(encoding="utf-8")
+            new, n = re.subn(regex, lambda _m: repl, text)
+            if n:
+                f.write_text(new, encoding="utf-8")
+                hits += n
+        if hits == 0:
+            failures.append(f"{pattern}: /{regex[:60]}.../ ({why})")
+        patched.append({"file": pattern, "reason": why, "hits": hits})
+
+    version = ""
+    manifest = plugin / ".claude-plugin" / "plugin.json"
+    if manifest.is_file():
+        version = json.loads(manifest.read_text(encoding="utf-8")).get("version", "")
+    info = {
+        "repository": "https://github.com/bdfinst/agentic-dev-team",
+        "plugin": "dev-team",
+        "version": version,
+        "commit": run(["git", "rev-parse", "HEAD"], upstream),
+        "commitDate": run(["git", "log", "-1", "--format=%cI"], upstream),
+        "droppedSkills": dropped,
+        "overridden": overridden,
+        "notes": noted,
+        "normalisedFrontmatter": normalised,
+        "patches": patched,
+    }
+    (PKG / "UPSTREAM.json").write_text(json.dumps(info, indent=2) + "\n", encoding="utf-8")
+
+    print(f"synced dev-team {version} ({info['commit'][:10]})")
+    print(f"  dropped {len(dropped)} skills, {len(overridden)} override files, {len(normalised)} frontmatter fixes")
+    if failures:
+        print("PATCHES THAT NO LONGER MATCH (upstream changed; review and update PATCHES):", file=sys.stderr)
+        for f in failures:
+            print("  - " + f, file=sys.stderr)
+        return 1
+    print(f"  {sum(int(p['hits']) for p in patched)} patch hits, all patches matched")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/ACCEPTED-RISKS.md.tmpl

@@ -0,0 +1,46 @@
+---
+# ACCEPTED-RISKS — project-local policy for suppressing reviewed findings.
+#
+# Each rule must carry a specific rationale, an owner, and an expiry date.
+# Consumed by /code-review, /review-agent, and security-review.
+# Schema reference: plugins/dev-team/knowledge/accepted-risks-schema.md
+#
+# Delete this example rule and add your own. If you don't yet have any
+# accepted risks, leave rules as an empty list: `rules: []`.
+rules:
+  - id: example-placeholder
+    rule_id: semgrep.generic.placeholder-example
+    files:
+      - "examples/**"
+    rationale: >
+      This is a placeholder rule demonstrating the shape of a real entry. Replace
+      it with rules that cite the SPECIFIC business or architectural reason the
+      finding is accepted — not generic disclaimers. If in doubt, delete this
+      rule and start with an empty list.
+    expires: 2026-07-20
+    owner: unassigned
+    scope: finding
+    broad: false
+---
+
+# Accepted Risks
+
+This file is a project policy, not a todo list. Every rule is a deliberate
+acceptance with a date when it MUST be re-reviewed.
+
+## How to add a rule
+
+1. Read `plugins/dev-team/knowledge/accepted-risks-schema.md` (lives in
+   the plugin) — especially the rationale and expiry requirements.
+2. Add an entry under `rules:` in the frontmatter above.
+3. Commit with a message explaining the acceptance decision.
+
+## How to remove a rule
+
+Deleting a rule is a real decision. The commit message must state why the risk
+is no longer accepted: fixed upstream, scoped out, moved to a runbook, etc.
+
+## Broad rules
+
+Rules with `broad: true` (wildcard `rule_id` or multi-file globs) get flagged
+every run. Keep these narrow; prefer two scoped rules to one broad one.

package/templates/agents/agent-template.md

@@ -0,0 +1,151 @@
+---
+# REQUIRED — unique identifier
+# Format: lowercase letters, digits, and hyphens only (e.g. code-reviewer, db-reader)
+# Must match the filename convention; used by hooks as agent_type
+name: your-agent-name
+
+# REQUIRED — tells Claude when to delegate to this agent
+# Write a clear, specific description. Include "Use proactively" to encourage automatic delegation.
+description: >-
+  One-sentence description of what this agent does and when to use it.
+  Add "Use proactively when X" to encourage automatic delegation.
+
+# OPTIONAL — tools this agent can use
+# If omitted, the agent inherits ALL tools from the main conversation.
+# Use this as an allowlist to restrict what the agent can do.
+#
+# Common tools: Read, Grep, Glob, Bash, Edit, Write, Agent, Skill
+# Tool restrictions: Agent(worker, researcher) limits which subagents can be spawned
+# Bash restrictions: Bash(npx *) limits Bash to matching commands only
+#
+# Note: To preload skill content at startup, use the `skills` field below
+# instead of listing Skill here. Listing Skill here allows runtime invocation
+# but does not inject skill content into context automatically.
+tools: Read, Grep, Glob
+
+# OPTIONAL — tools to deny (removed from inherited or specified list)
+# Use when you want to inherit most tools but block a few specific ones.
+# disallowedTools: Write, Edit
+
+# OPTIONAL — model to use for this agent's dispatch
+# An alias (haiku | sonnet | opus | fable), a full model ID, or inherit.
+# Resolved natively by the harness before dispatch (ADR 0026) — there is no
+# plugin-side PreToolUse hook, routing map, or ladder file in this path.
+# Do not pin a dated snapshot ID here; use the alias.
+# inherit: use the same model as the main conversation (default if omitted)
+#
+# Routing guidance:
+#   haiku  — high-volume, structured extraction, simple classification
+#   sonnet — balanced capability and speed; most agents
+#   opus   — frontier reasoning, security analysis, architectural judgment
+model: sonnet
+
+# OPTIONAL — reasoning effort for this agent's model calls
+# Values: low | medium | high | xhigh | max (available levels depend on model)
+# ADR 0026 sets every agent to `high` uniformly as the safe default; a
+# follow-up calibration pass may tune this per agent later.
+effort: high
+
+# OPTIONAL — permission mode
+# WARNING: Ignored for plugin agents (silently has no effect).
+# Only works for project agents (.claude/agents/) or user agents (~/.claude/agents/).
+# Values: default | acceptEdits | auto | dontAsk | bypassPermissions | plan
+# permissionMode: default
+
+# OPTIONAL — maximum agentic turns before the agent stops
+# maxTurns: 10
+
+# OPTIONAL — skills to preload into this agent's context at startup
+# The full content of each skill is injected before the agent runs.
+# This is different from listing Skill in tools (which allows runtime invocation).
+# Use skill names as they appear in the skills registry.
+# skills:
+#   - api-conventions
+#   - error-handling-patterns
+
+# OPTIONAL — MCP servers available to this agent
+# WARNING: Ignored for plugin agents (silently has no effect).
+# Only works for project agents (.claude/agents/) or user agents (~/.claude/agents/).
+# mcpServers:
+#   - playwright:
+#       type: stdio
+#       command: npx
+#       args: ["-y", "@playwright/mcp@latest"]
+
+# OPTIONAL — lifecycle hooks scoped to this agent
+# WARNING: Ignored for plugin agents (silently has no effect).
+# Only works for project agents (.claude/agents/) or user agents (~/.claude/agents/).
+# hooks:
+#   PreToolUse:
+#     - matcher: "Bash"
+#       hooks:
+#         - type: command
+#           command: "./scripts/validate-command.sh"
+
+# OPTIONAL — persistent memory directory that survives across conversations
+# Values: user | project | local
+#   user:    ~/.claude/agent-memory/<name>/    (all projects)
+#   project: .claude/agent-memory/<name>/      (this project, check in to VCS)
+#   local:   .claude/agent-memory-local/<name>/ (this project, do NOT check in)
+# memory: project
+
+# OPTIONAL — always run this agent as a background task (non-blocking)
+# Default: false (agent runs in foreground, blocking the main conversation)
+# background: false
+
+# OPTIONAL — effort level for this agent's model calls
+# Overrides the session effort level while this agent is active.
+# Values: low | medium | high | xhigh | max (available levels depend on model)
+# effort: medium
+
+# OPTIONAL — run agent in an isolated git worktree
+# Set to "worktree" to give the agent a temporary copy of the repository.
+# The worktree is cleaned up automatically if the agent makes no changes.
+# Values: worktree
+# isolation: worktree
+
+# OPTIONAL — display color in the task list and transcript
+# Values: red | blue | green | yellow | purple | orange | pink | cyan
+# color: blue
+
+# OPTIONAL — auto-submitted first turn when this agent runs as the main session
+# (via --agent flag or `agent` setting in settings.json)
+# Commands and skills in this prompt are processed.
+# initialPrompt: "Load the project context and summarize the current state."
+---
+
+# Agent Name
+
+One-sentence description of what this agent is for and what distinguishes it.
+
+## Responsibilities
+
+- Primary responsibility
+- Secondary responsibility
+- What it explicitly does NOT do (scope boundary)
+
+## Process
+
+Step-by-step description of how this agent approaches its task.
+
+1. First step
+2. Second step
+3. Third step
+
+## Output Format
+
+Describe the expected output format. For review agents:
+
+```json
+{"status": "pass|warn|fail|skip", "issues": [{"severity": "error|warning|suggestion", "confidence": "high|medium|none", "file": "", "line": 0, "message": "", "suggestedFix": ""}], "summary": ""}
+```
+
+## Skip
+
+Return skip status when:
+
+- Condition that makes this agent inapplicable
+
+## Ignore
+
+What this agent explicitly does not check (handled by other agents or out of scope).