agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/trackers/github.sh

@@ -0,0 +1,467 @@
+#!/usr/bin/env bash
+# GitHub Projects adapter.
+#
+# A script rather than instructions in an agent prompt, for the same reason
+# scaffolding is a script: an agent improvising GraphQL produces a different
+# board every run and leaves nothing to review. Every subcommand here is
+# idempotent, so re-running updates rather than duplicating.
+#
+#   discover <project-number>            read the board's real fields
+#   export <milestone-dir> <project-num> create/update epic and sub-issues
+#   status-get <issue-number>            print the board status
+#   status-set <issue-number> <status>   move it — board from tracker.board
+#   comments <issue-number>              the thread, each marked allowed or not
+#   reply <issue> <comment-id> <file>    answer one comment
+#
+# Every mutation used here was verified against the live schema before it was
+# written — addProjectV2ItemById, updateProjectV2ItemFieldValue, addSubIssue.
+set -euo pipefail
+
+die() { printf '  [x] %s\n' "$*" >&2; exit 1; }
+log() { printf '  → %s\n' "$*" >&2; }
+
+command -v gh >/dev/null 2>&1 || die "gh is not installed"
+gh auth status >/dev/null 2>&1 || die "gh is not authenticated — run: gh auth login"
+
+REPO="$(gh repo view --json nameWithOwner --jq .nameWithOwner)"
+OWNER="${REPO%%/*}"
+
+# ── the board ────────────────────────────────────────────────────────────────
+
+# A Projects v2 board can hang off a user or an organisation, and the query
+# differs. Try the viewer first, then the owner as an organisation, rather
+# than asking the caller to know which they have.
+project_query() {
+  local num="$1" scope
+  for scope in "viewer" "organization(login: \"$OWNER\")" "user(login: \"$OWNER\")"; do
+    local out
+    out="$(gh api graphql -f query="
+      { $scope { projectV2(number: $num) {
+          id title
+          fields(first: 50) { nodes {
+            ... on ProjectV2SingleSelectField { id name options { id name } }
+            ... on ProjectV2FieldCommon { id name }
+          } }
+      } } }" 2>/dev/null)" || continue
+    # A scope that does not hold the board answers with a null projectV2
+    # rather than an error, so the exit code proves nothing on its own.
+    printf '%s' "$out" | grep -q '"projectV2":null' && continue
+    printf '%s' "$out"
+    return 0
+  done
+  die "no Projects v2 board number $num on $OWNER"
+}
+
+cmd_discover() {
+  local num="${1:?usage: discover <project-number>}"
+  local json status_opts
+  json="$(project_query "$num")"
+
+  status_opts="$(printf '%s' "$json" \
+    | python3 -c '
+import json,sys
+d = json.load(sys.stdin)["data"]
+p = next(v for v in d.values() if v)["projectV2"]
+f = next((n for n in p["fields"]["nodes"] if n.get("name") == "Status"), None)
+if not f or "options" not in f:
+    sys.exit("the board has no Status single-select field")
+print(p["id"])
+for o in f["options"]:
+    print(o["name"])
+')"
+
+  local board_id; board_id="$(printf '%s' "$status_opts" | head -1)"
+  local names;    names="$(printf '%s' "$status_opts" | tail -n +2)"
+
+  # Printed as the config block to paste, not written in place: config.yml is
+  # merged on upgrade and hand-edited by the user, and a script that rewrites
+  # it silently is a script that loses a comment somebody wrote.
+  printf 'tracker:\n  provider: github\n  board: "%s"\n  states:\n' "$num"
+  # Orchestra's internal states are fixed; only the mapping varies. Matched
+  # case-insensitively against what the board actually calls them, and left
+  # blank when the board has no such column — blank is an honest "you decide",
+  # a guess is an agent moving a task to a column that does not exist.
+  # Alternation, first match wins: a stock board calls the backlog "Todo",
+  # a renamed one "Backlog", and either is the column export lands in.
+  map_state() {
+    local want="$1" match
+    match="$(printf '%s\n' "$names" | grep -ixE "$want" | head -1 || true)"
+    printf '    %s: "%s"\n' "$2" "$match"
+  }
+  map_state "Backlog|To do|Todo"    backlog
+  map_state "Ready"                 ready
+  map_state "In progress"           in_progress
+  map_state "In review"             in_review
+  map_state "Done"                  done
+  map_state "Blocked"               blocked
+  map_state "Tech debt|Tech-debt"   tech_debt
+  printf '\n' >&2
+  log "board id $board_id — columns: $(printf '%s' "$names" | tr '\n' ',' | sed 's/,$//')"
+  printf '%s\n' "$names" | grep -qix "in review" \
+    || log "warning: no 'In review' column — the sync loop has nowhere to move a task"
+}
+
+# ── export ───────────────────────────────────────────────────────────────────
+
+# The issue whose title matches, or empty. This is what makes export
+# idempotent without storing anything: a second run finds the first run's
+# issue instead of opening another. A second title is the one an earlier
+# version of this script gave the same item — `[slug] phase-1` — so a board
+# exported before titles became sentences is updated, not duplicated.
+find_issue() { # title [legacy-title]
+  local num
+  num="$(gh issue list --state all --search "$1 in:title" --json number,title \
+    --jq "[.[] | select(.title == \"$1\")] | .[0].number // empty" 2>/dev/null)"
+  if [ -z "$num" ] && [ -n "${2:-}" ]; then
+    num="$(gh issue list --state all --search "$2 in:title" --json number,title \
+      --jq "[.[] | select(.title == \"$2\")] | .[0].number // empty" 2>/dev/null)"
+    # Found under the old name: rename it, so the next run finds it directly.
+    [ -n "$num" ] && gh issue edit "$num" --title "$1" >/dev/null
+  fi
+  printf '%s' "$num"
+}
+
+# What the board shows. The phase file is the engineer's document — a
+# frontmatter of knobs, a Result section lead fills in later — and none of
+# that belongs in front of a person reading the task. Frontmatter and Result
+# are dropped; everything else stays, because with a provider this body is
+# what lead reads back and hands to the sub-agent, and Scope and Acceptance
+# Criteria have to arrive intact.
+board_body() { # phase-or-milestone-file → path of a temp file
+  local out
+  out="$(mktemp)"
+  python3 - "$1" > "$out" <<'PY'
+import re, sys
+s = open(sys.argv[1]).read()
+if s.startswith("---\n"):
+    end = s.find("\n---\n", 4)
+    if end != -1:
+        s = s[end + 5:]
+s = re.sub(r"\n## Result\n[\s\S]*$", "\n", s)
+sys.stdout.write(s.strip() + "\n")
+PY
+  printf '%s' "$out"
+}
+
+# `title:` from a file's frontmatter, or nothing.
+front_title() {
+  python3 - "$1" <<'PY'
+import re, sys
+s = open(sys.argv[1]).read()
+if not s.startswith("---\n"): sys.exit(0)
+end = s.find("\n---\n", 4)
+m = re.search(r"^title:[ \t]*(.+)$", s[4:end], re.M) if end != -1 else None
+if m: print(m.group(1).split(" #")[0].strip().strip('"').strip("'"))
+PY
+}
+
+# Prints the number, and sets UPSERT_CREATED to 1 when the issue is new. A
+# re-export updates the body and must not touch status: the task may be in
+# progress, and moving it back to the backlog would tell lead a human did.
+upsert_issue() { # title body-file [legacy-title]
+  local title="$1" body="$2" num
+  UPSERT_CREATED=0
+  num="$(find_issue "$title" "${3:-}")"
+  if [ -n "$num" ]; then
+    gh issue edit "$num" --body-file "$body" >/dev/null
+    printf '%s' "$num"
+  else
+    UPSERT_CREATED=1
+    gh issue create --title "$title" --body-file "$body" \
+      | grep -oE '[0-9]+$'
+  fi
+}
+
+issue_node_id() { gh issue view "$1" --json id --jq .id; }
+
+link_sub_issue() { # parent-number child-number
+  local parent child
+  parent="$(issue_node_id "$1")"
+  child="$(issue_node_id "$2")"
+  # Already linked is not an error worth stopping for — export is meant to be
+  # re-runnable, and GitHub rejects a duplicate link rather than ignoring it.
+  gh api graphql -f query='
+    mutation($p: ID!, $c: ID!) {
+      addSubIssue(input: {issueId: $p, subIssueId: $c}) { issue { number } }
+    }' -f p="$parent" -f c="$child" >/dev/null 2>&1 || true
+}
+
+board_add() { # project-number issue-number  → item id
+  local proj_id issue_id
+  proj_id="$(project_query "$1" | python3 -c 'import json,sys; d=json.load(sys.stdin)["data"]; print(next(v for v in d.values() if v)["projectV2"]["id"])')"
+  issue_id="$(issue_node_id "$2")"
+  gh api graphql -f query='
+    mutation($p: ID!, $c: ID!) {
+      addProjectV2ItemById(input: {projectId: $p, contentId: $c}) { item { id } }
+    }' -f p="$proj_id" -f c="$issue_id" --jq '.data.addProjectV2ItemById.item.id'
+}
+
+cmd_export() {
+  local dir="${1:?usage: export <milestone-dir> <project-number>}"
+  local proj="${2:?usage: export <milestone-dir> <project-number>}"
+  [ -d "$dir" ] || die "no milestone directory at $dir"
+  [ -f "$dir/milestone.md" ] || die "$dir has no milestone.md"
+
+  local slug epic
+  slug="$(basename "$dir")"
+  log "exporting $slug to project $proj"
+
+  # The epic is titled by the milestone's heading — "Milestone: M1 — User
+  # auth" becomes "User auth" — and the task by the phase's `title:`. A phase
+  # without one falls back to the old shape, and the PM's reviewer flags it.
+  local epic_title body
+  epic_title="$(grep -m1 -E '^# ' "$dir/milestone.md" | sed -E 's/^# *(Milestone: *)?(M[0-9]+ *[—-] *)?//')"
+  [ -n "$epic_title" ] || epic_title="$slug"
+  body="$(board_body "$dir/milestone.md")"
+  epic="$(upsert_issue "$epic_title" "$body" "[epic] $slug")"
+  rm -f "$body"
+  board_add "$proj" "$epic" >/dev/null
+  log "epic #$epic"
+
+  {
+    printf 'provider: github\n'
+    printf 'board: "%s"\n' "$proj"
+    printf 'epic:\n  number: %s\n  url: "https://github.com/%s/issues/%s"\n' "$epic" "$REPO" "$epic"
+    printf 'tasks:\n'
+  } > "$dir/tracker.yml"
+
+  # A new task lands in the backlog, and the human moves it to ready when
+  # lead may take it. Read from config so the column is the board's own name;
+  # blank means discovery found no such column, and the task is left where
+  # the board puts it rather than moved to a guess.
+  local backlog
+  backlog="$(config_state backlog)"
+  [ -n "$backlog" ] || log "warning: tracker.states.backlog is empty — new tasks keep the board's default column"
+
+  local phase name task
+  for phase in "$dir"/phases/*.md; do
+    [ -e "$phase" ] || break
+    name="$(basename "$phase" .md)"
+    local title
+    title="$(front_title "$phase")"
+    [ -n "$title" ] || { title="[$slug] $name"; log "warning: $name has no title: — using $title"; }
+    body="$(board_body "$phase")"
+    task="$(upsert_issue "$title" "$body" "[$slug] $name")"
+    rm -f "$body"
+    link_sub_issue "$epic" "$task"
+    board_add "$proj" "$task" >/dev/null
+    if [ "$UPSERT_CREATED" = 1 ] && [ -n "$backlog" ]; then
+      cmd_status_set "$task" "$backlog" "$proj"
+    fi
+    printf '  - phase: "%s"\n    number: %s\n    url: "https://github.com/%s/issues/%s"\n' \
+      "$name" "$task" "$REPO" "$task" >> "$dir/tracker.yml"
+    log "task #$task — $name"
+  done
+
+  log "wrote $dir/tracker.yml"
+}
+
+# ── status ───────────────────────────────────────────────────────────────────
+
+cmd_status_get() {
+  local num="${1:?usage: status-get <issue-number>}" out
+  # `repository.issue` answers null for a pull request number rather than
+  # erroring cleanly, and gh then prints the whole GraphQL envelope and exits
+  # 1. Read the output instead of the exit code, so the caller gets a sentence.
+  out="$(gh api graphql -f query='
+    query($owner: String!, $repo: String!, $n: Int!) {
+      repository(owner: $owner, name: $repo) { issue(number: $n) {
+        projectItems(first: 10) { nodes {
+          fieldValueByName(name: "Status") {
+            ... on ProjectV2ItemFieldSingleSelectValue { name }
+          } } } } } }' \
+    -f owner="$OWNER" -f repo="${REPO#*/}" -F n="$num" 2>/dev/null || true)"
+
+  printf '%s' "$out" | grep -q '"issue":null' \
+    && die "#$num is not an issue in $REPO — a pull request number will do this"
+
+  # No output and exit 0 is the honest answer for an issue that is on no
+  # board: it has no status, which is different from a failure to read one.
+  printf '%s' "$out" \
+    | python3 -c '
+import json,sys
+try: d = json.load(sys.stdin)["data"]["repository"]["issue"]["projectItems"]["nodes"]
+except Exception: sys.exit(0)
+for n in d:
+    v = n.get("fieldValueByName") or {}
+    if v.get("name"):
+        print(v["name"]); break
+'
+}
+
+# tracker.board from config.yml.
+#
+# Read here rather than demanded as an argument. github.sh needs the board to
+# resolve a status option and a connector-backed provider does not, so
+# requiring it positionally
+# gave the two adapters different signatures — and the agents call one
+# interface, so lead ran the same command and it worked on one provider only.
+# A third argument still overrides, for a one-off.
+config_board() {
+  local cfg
+  cfg="$(git rev-parse --show-toplevel 2>/dev/null)/.orchestra/config.yml"
+  [ -f "$cfg" ] || return 0
+  python3 - "$cfg" <<'CFG'
+import re, sys
+for b in re.split(r"\n(?=[a-z_]+:)", open(sys.argv[1]).read()):
+    if b.startswith("tracker:"):
+        m = re.search(r"^[ \t]*board:[ \t]*(.*)$", b, re.M)
+        if m:
+            print(m.group(1).strip().strip(chr(34)).strip(chr(39)))
+        break
+CFG
+}
+
+# tracker.states.<name> from config.yml — the board's own column name for one
+# of Orchestra's states, or nothing when discovery left it blank.
+config_state() {
+  local cfg
+  cfg="$(git rev-parse --show-toplevel 2>/dev/null)/.orchestra/config.yml"
+  [ -f "$cfg" ] || return 0
+  python3 - "$cfg" "$1" <<'CFG'
+import re, sys
+for b in re.split(r"\n(?=[a-z_]+:)", open(sys.argv[1]).read()):
+    if b.startswith("tracker:"):
+        m = re.search(r"^[ \t]*" + re.escape(sys.argv[2]) + r":[ \t]*(.*)$", b, re.M)
+        if m:
+            print(m.group(1).split("#")[0].strip().strip(chr(34)).strip(chr(39)))
+        break
+CFG
+}
+
+cmd_status_set() {
+  local num="${1:?usage: status-set <issue-number> <status> [project-number]}"
+  local want="${2:?usage: status-set <issue-number> <status> [project-number]}"
+  local proj="${3:-$(config_board)}"
+  [ -n "$proj" ] || die "no board — pass the project number, or set tracker.board in .orchestra/config.yml"
+
+  local json proj_id field_id opt_id item_id
+  json="$(project_query "$proj")"
+  proj_id="$(printf '%s' "$json" | python3 -c 'import json,sys; d=json.load(sys.stdin)["data"]; print(next(v for v in d.values() if v)["projectV2"]["id"])')"
+  # Into a variable first, and the exit code checked. `read <<< "$(...)"`
+  # succeeds even when the substitution died, so a board with no such column
+  # printed the right message and then fired the mutation with an empty field
+  # id — "could not resolve a node with the global id of ''".
+  local resolved
+  resolved="$(printf '%s' "$json" | python3 -c "
+import json,sys
+d = json.load(sys.stdin)['data']
+p = next(v for v in d.values() if v)['projectV2']
+f = next((n for n in p['fields']['nodes'] if n.get('name') == 'Status'), None)
+if not f: sys.exit('the board has no Status field')
+o = next((o for o in f['options'] if o['name'].lower() == '''$want'''.lower()), None)
+if not o: sys.exit('the board has no column named \"$want\" — it has: ' + ', '.join(x['name'] for x in f['options']))
+print(f['id'], o['id'])
+")" || exit 1
+  read -r field_id opt_id <<< "$resolved"
+
+  item_id="$(gh api graphql -f query='
+    query($owner: String!, $repo: String!, $n: Int!) {
+      repository(owner: $owner, name: $repo) { issue(number: $n) {
+        projectItems(first: 10) { nodes { id project { id } } } } } }' \
+    -f owner="$OWNER" -f repo="${REPO#*/}" -F n="$num" \
+    --jq ".data.repository.issue.projectItems.nodes[] | select(.project.id == \"$proj_id\") | .id")"
+  [ -n "$item_id" ] || item_id="$(board_add "$proj" "$num")"
+
+  gh api graphql -f query='
+    mutation($p: ID!, $i: ID!, $f: ID!, $o: String!) {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: $p, itemId: $i, fieldId: $f,
+        value: {singleSelectOptionId: $o}
+      }) { projectV2Item { id } } }' \
+    -f p="$proj_id" -f i="$item_id" -f f="$field_id" -f o="$opt_id" >/dev/null
+  log "#$num → $want"
+}
+
+# ── comments ─────────────────────────────────────────────────────────────────
+
+# tracker.actors from config.yml, one login per line.
+#
+# Read here rather than left to the agent's judgement. The allowlist is what
+# stops a board comment from being an instruction channel, and a rule enforced
+# by a prompt is a rule that holds until the prompt is summarised.
+allowlist() {
+  local cfg
+  cfg="$(git rev-parse --show-toplevel 2>/dev/null)/.orchestra/config.yml"
+  [ -f "$cfg" ] || return 0
+  python3 - "$cfg" <<'PY'
+import re, sys
+block = re.split(r"\n(?=[a-z_]+:)", open(sys.argv[1]).read())
+for b in block:
+    if not b.startswith("tracker:"):
+        continue
+    # [ \t]* and not \s*: \s matches a newline, so a greedy \s* after the
+    # colon swallowed the first item of a block list into the inline capture
+    # and the allowlist silently lost its first entry.
+    m = re.search(r"^[ \t]*actors:[ \t]*(.*)$", b, re.M)
+    if not m:
+        break
+    inline = m.group(1).strip()
+    if inline.startswith("["):
+        for name in re.findall(r'"([^"]+)"|\'([^\']+)\'', inline):
+            print(name[0] or name[1])
+    else:
+        # lstrip the newline the match ends on: without it the first element
+        # is an empty string, which is not a list item, and a block-style
+        # actors: parsed as nobody while the inline form worked.
+        for line in b[m.end():].lstrip("\n").split("\n"):
+            item = re.match(r'^\s+-\s*["\']?([^"\'\s]+)', line)
+            if not item:
+                break
+            print(item.group(1))
+PY
+}
+
+cmd_comments() {
+  local num="${1:?usage: comments <issue-number>}" allowed
+  allowed="$(allowlist)"
+  # Every comment is reported, allowed or not — one so it can be acted on, the
+  # other so the user is told somebody else is writing on their board. Silently
+  # dropping it would hide exactly the event worth noticing.
+  gh api "repos/$REPO/issues/$num/comments" --paginate 2>/dev/null \
+    | ALLOWED="$allowed" python3 -c '
+import json, os, sys
+allowed = {l.strip() for l in os.environ["ALLOWED"].splitlines() if l.strip()}
+for c in json.load(sys.stdin):
+    login = (c.get("user") or {}).get("login", "")
+    print(json.dumps({
+        "id": c["id"],
+        "author": login,
+        "allowed": login in allowed,
+        "created_at": c["created_at"],
+        "updated_at": c["updated_at"],
+        "body": c["body"],
+    }))
+'
+}
+
+cmd_reply() {
+  local num="${1:?usage: reply <issue-number> <comment-id> <body-file>}"
+  local cid="${2:?usage: reply <issue-number> <comment-id> <body-file>}"
+  local file="${3:?usage: reply <issue-number> <comment-id> <body-file>}"
+  [ -f "$file" ] || die "no body file at $file"
+
+  local author
+  author="$(gh api "repos/$REPO/issues/comments/$cid" --jq '.user.login' 2>/dev/null || true)"
+  [ -n "$author" ] || die "no comment $cid on $REPO"
+  allowlist | grep -qx "$author" \
+    || die "comment $cid is from @$author, who is not in tracker.actors — reporting, not acting"
+
+  # The marker that makes the loop idempotent with no local state: the reply
+  # names the comment it answers, so a second run sees the work was done. An
+  # edited comment is caught by comparing its updated_at to this reply's time.
+  local tmp; tmp="$(mktemp)"
+  { printf '> in reply to comment %s by @%s\n\n' "$cid" "$author"; cat "$file"; } > "$tmp"
+  gh issue comment "$num" --body-file "$tmp"
+  rm -f "$tmp"
+}
+
+case "${1:-}" in
+  discover)   shift; cmd_discover "$@" ;;
+  export)     shift; cmd_export "$@" ;;
+  status-get) shift; cmd_status_get "$@" ;;
+  status-set) shift; cmd_status_set "$@" ;;
+  comments)   shift; cmd_comments "$@" ;;
+  reply)      shift; cmd_reply "$@" ;;
+  *) die "usage: github.sh {discover|export|status-get|status-set|comments|reply} ..." ;;
+esac

package/template/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+<!-- orchestra -->
+## Orchestra — AI Team Orchestration System
+
+This project uses Orchestra for multi-agent coordination via `.orchestra/` and `.claude/`.
+
+**FIRST RESPONSE — check the project before asking anything.**
+
+If `.orchestra/milestones/` holds no milestone directory — a `.gitkeep` is
+not a milestone — **and** there is no app yet, meaning no `apps/` and no root
+`package.json`, then this is a fresh repo. Say so in one line
+and point at `/orchestra:setup`. Do not offer a role: there is nothing for a
+PM to plan into and nothing for a lead to build, and asking which hat to wear
+before the project exists is the wrong first question.
+
+Otherwise, unless the user explicitly names a role:
+
+Call `AskUserQuestion` with:
+- header: "Role"
+- question: "Which role will you take for this session? (pick one)"
+- multiSelect: false
+- options:
+  1. Orchestrator — Maintain and evolve Orchestra system files, roles, and rules
+  2. Product Manager — Write PRDs, create milestones with phases, orchestrate pipeline
+  3. Discussion — Just brainstorm, no role needed
+
+If user skips or starts giving instructions directly — work with them normally.
+Sub-agents spawned by lead skip role selection — they already have a role assigned in their prompt.
+Do NOT greet. Do NOT explain. The role selection IS your greeting.
+
+**AFTER ROLE SELECTED:**
+
+1. Read `.orchestra/roles/{role-id}.md` for identity and ownership
+2. Read `.orchestra/config.yml` for pipeline settings
+3. Check `.orchestra/milestones/` for active work
+4. If work exists → announce and start. If not → report and wait.
+
+Role IDs: orchestrator, product-manager
+
+**ROLE ACTIVATION:** Only via `/orchestra:{role}` commands. Never switch on free text.
+
+**`/orchestra:start`** → read `.claude/agents/lead.md`, run in **separate terminal** from PM.
+
+### Rules
+
+- Two-terminal model: PM plans in one terminal, lead executes in another
+- Each role writes only to its ownership scope (defined in role file)
+- Rules (`.claude/rules/*.orchestra.md`) auto-loaded, except those with `paths:` frontmatter, which load with their files and are read where named. Skills loaded per phase.
+- **PROTECTED:** Non-Orchestrator roles NEVER modify `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.orchestra/stacks/`, `.orchestra/trackers/`, `.orchestra/scripts/`, `.claude/agents/`, `.claude/hooks/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, or `docs/`.
+
+<!-- /orchestra -->

package/template/agents/architect.md

@@ -0,0 +1,83 @@
+---
+name: architect
+description: "Writes the technical design (rfc.md) for a milestone before implementation begins. Called by lead during the design stage of the full pipeline."
+model: opus
+effort: xhigh
+---
+
+# Architect — Technical Design
+
+You turn a milestone into a technical design other agents can execute
+without guessing. You write exactly one artifact: `rfc.md` in the milestone
+directory. You write no code.
+
+## Hard Rules
+
+1. **Decide.** An RFC that says "we could use X or Y" has not done its job —
+   the phase agent will pick one at random and the phases will disagree with
+   each other. Choose, and write down why in one sentence.
+2. **No unresolved choices leave this document.** If you genuinely cannot
+   decide because information is missing, say what is missing and stop.
+   That is a blocker, not a design.
+3. **Do not expand scope.** Design what the milestone asks for. If you find
+   the milestone is missing something structural, report it — do not quietly
+   add phases.
+4. **Verify current versions.** Never write a version or an API shape from
+   memory. Check the registry or the docs.
+
+## Depth
+
+`.claude/skills/architecture/SKILL.md` — choosing the deployment shape,
+drawing boundaries that survive, data ownership and consistency, the four
+controls every outbound call needs, and what to write down as deliberately
+not built. Read it before deciding structure, not after.
+
+## Read first
+
+- `prd.md` — what and why
+- `milestone.md` — acceptance criteria, complexity, **KPIs**
+- `grooming.md` — decisions already made, and what was deliberately cut
+- `phases/*.md` — the units of work you are designing for
+- the app's `CLAUDE.md` and `.claude/` — the conventions this app already
+  follows. A design that fights the app's own conventions is wrong even if
+  it is technically sound.
+
+## rfc.md
+
+```markdown
+# RFC: M{n} — {name}
+
+## Approach
+Two or three sentences. What we are building, structurally.
+
+## Decisions
+| Decision | Choice | Why |
+|---|---|---|
+Every choice that a phase agent would otherwise have to make.
+
+## Data & Contracts
+Schemas, types, API shapes. The exact names other phases will import.
+
+## Boundaries
+What each phase owns. No two phases write the same file.
+
+## Observability
+Which errors are reported, which events fire, and how this milestone's KPI
+is actually read. Required — see `.claude/rules/analytics-kpi.orchestra.md`.
+
+## Risks
+What could make this wrong, and the cheapest way to find out early.
+
+## Out of scope
+What we are deliberately not doing, so nobody adds it back.
+```
+
+## Before returning
+
+- [ ] every phase could be executed from this document alone
+- [ ] no "X or Y" survives anywhere
+- [ ] contracts name real types and real paths
+- [ ] the KPI has a stated read path
+- [ ] versions and APIs were checked, not recalled
+
+Return a two-line summary and the path to `rfc.md`. Nothing else.

package/template/agents/engineer-high.md

@@ -0,0 +1,17 @@
+---
+name: engineer-high
+description: "A phase sub-agent at effort high. Lead picks this type from the phase's effort; the identity, phase and rules arrive in the prompt lead composes. Never launched by hand."
+model: inherit
+effort: high
+---
+
+# Engineer — effort `high`
+
+This file fixes one thing: how hard you think. Everything else — who you
+are, what the phase asks, the rules that apply — is in the prompt lead
+composed for you. Read it as your identity and follow it.
+
+The model is the session's, which is `pipeline.model` in
+`.orchestra/config.yml`; lead passes it on the launch. The effort is the
+phase's, resolved through `pipeline.effort` or written directly on the
+phase.

package/template/agents/engineer-low.md

@@ -0,0 +1,17 @@
+---
+name: engineer-low
+description: "A phase sub-agent at effort low. Lead picks this type from the phase's effort; the identity, phase and rules arrive in the prompt lead composes. Never launched by hand."
+model: inherit
+effort: low
+---
+
+# Engineer — effort `low`
+
+This file fixes one thing: how hard you think. Everything else — who you
+are, what the phase asks, the rules that apply — is in the prompt lead
+composed for you. Read it as your identity and follow it.
+
+The model is the session's, which is `pipeline.model` in
+`.orchestra/config.yml`; lead passes it on the launch. The effort is the
+phase's, resolved through `pipeline.effort` or written directly on the
+phase.

package/template/agents/engineer-max.md

@@ -0,0 +1,17 @@
+---
+name: engineer-max
+description: "A phase sub-agent at effort max. Lead picks this type from the phase's effort; the identity, phase and rules arrive in the prompt lead composes. Never launched by hand."
+model: inherit
+effort: max
+---
+
+# Engineer — effort `max`
+
+This file fixes one thing: how hard you think. Everything else — who you
+are, what the phase asks, the rules that apply — is in the prompt lead
+composed for you. Read it as your identity and follow it.
+
+The model is the session's, which is `pipeline.model` in
+`.orchestra/config.yml`; lead passes it on the launch. The effort is the
+phase's, resolved through `pipeline.effort` or written directly on the
+phase.

package/template/agents/engineer-medium.md

@@ -0,0 +1,17 @@
+---
+name: engineer-medium
+description: "A phase sub-agent at effort medium. Lead picks this type from the phase's effort; the identity, phase and rules arrive in the prompt lead composes. Never launched by hand."
+model: inherit
+effort: medium
+---
+
+# Engineer — effort `medium`
+
+This file fixes one thing: how hard you think. Everything else — who you
+are, what the phase asks, the rules that apply — is in the prompt lead
+composed for you. Read it as your identity and follow it.
+
+The model is the session's, which is `pipeline.model` in
+`.orchestra/config.yml`; lead passes it on the launch. The effort is the
+phase's, resolved through `pipeline.effort` or written directly on the
+phase.