agentirc-cli 9.6.1__tar.gz → 9.7.0__tar.gz

agentirc_cli-9.7.0/.claude/skills/assign-to-workforce/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: assign-to-workforce
+description: >
+  Fan out a converged devague plan's dependency waves to parallel agents in
+  isolated git worktrees, one agent per task per wave, with TDD-gated merges
+  by the main agent. Human gates: the exported spec, the implementation split
+  plan (task map + per-task agent/model proposal + go/no-go), and the final PR.
+  The devague CLI stays deterministic and non-orchestrating (#20) — it only
+  *describes* the graph via `devague plan waves`; the operator (main agent)
+  performs the fan-out. Use when the user says "assign to workforce",
+  "fan out the plan", "parallel subagents", or after /spec-to-plan exports a
+  plan. Authored and maintained in agentculture/devague (origin = devague);
+  guildmaster pulls this skill from here and broadcasts it to the AgentCulture
+  mesh — it is NOT vendored from guildmaster like the other skills here.
+type: command
+---
+
+# assign-to-workforce — fan out a converged plan's waves to parallel agents
+
+The skill is named **`assign-to-workforce`**; the product/CLI it reads is the
+**`devague plan waves`** command. (The prior leg — turning a spec into a plan —
+is the sibling **`/spec-to-plan`** skill.)
+
+`assign-to-workforce` takes a **converged devague plan** and fans out its
+dependency waves to parallel agents (subagents, teammate agents, or generalist
+agents) — one agent per task per wave — each working in an **isolated git
+worktree**. The main agent merges each completed worktree gated by TDD. The
+human owns exactly three gates: the exported spec, the implementation split
+plan, and the final PR.
+
+The devague CLI is **never orchestrated by devague itself** — `devague plan
+waves` describes the dependency graph (#20); it does not spawn agents, manage
+worktrees, mark tasks done, or pick a backend. The fan-out is the *operator's*
+job — this skill and the main agent perform it.
+
+## How to run
+
+The entry point is `scripts/assign-to-workforce.sh`. Invoke it from the
+repository whose plan you are implementing (plans persist under `.devague/`
+in the current directory):
+
+```bash
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan [--plan <slug>]
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh waves    [--plan <slug>] [--json]
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh help
+```
+
+It resolves the CLI portably — an installed `devague` on `PATH` (the normal
+case), falling back to `uv run devague` when you are inside the devague
+checkout, else an install hint. The `split-plan` subcommand reads
+`devague plan waves --json` and renders the human-facing implementation split
+plan: task map, proposed per-task agent + model assignment, and the go/no-go
+question. The `waves` subcommand forwards to `devague plan waves` verbatim.
+
+### Usage
+
+| Subcommand | What it does |
+|------------|--------------|
+| `split-plan [--plan S]` | Read `devague plan waves` and print the implementation split plan — task map with per-task agent + model proposal — ready for human go/no-go review. |
+| `waves [--plan S] [--json]` | Forward to `devague plan waves [--json]`. Read-only; lists wave batches. On a converged plan exits 0 listing the waves. |
+| `help` | Print usage. |
+
+## The full flow
+
+The flow has three human gates and one automated TDD merge loop.
+
+### Human gate 1 — the exported spec
+
+The plan is seeded from a converged frame (`devague plan new --frame <slug>`).
+The human reviewed and approved the spec when it was exported by the `/think`
+skill. No re-approval needed here — the spec gate is already closed.
+
+### Human gate 2 — the implementation split plan
+
+Before any task is assigned, the main agent presents the **implementation split
+plan** for human go/no-go. This is the only gate the human owns at the
+implementation stage (per task, the TDD gate is the main agent's).
+
+The split plan contains:
+
+1. **Task map** — every task id, its one-line summary, acceptance criteria, and
+   the wave it belongs to (from `devague plan waves`).
+2. **Per-task agent + model proposal** — for each task: the proposed agent type
+   (subagent / teammate / generalist), the proposed model (e.g. a cheaper/faster
+   model for a well-scoped task), and the scope justification (why this task is
+   safe to delegate).
+3. **Go/no-go question** — explicit human decision: "Approve this split and
+   assign the plan to the workforce, or edit it first?"
+
+The human may edit any row (agent type, model, scope) before approving. The
+plan is model-agnostic — devague does not pick a backend (#20).
+
+Run `split-plan` to print the proposed table:
+
+```bash
+bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh split-plan
+```
+
+Do not proceed to fan-out until the human approves the split plan.
+
+### Fan-out — one agent per task per wave in isolated worktrees
+
+Once the human approves, the main agent fans out each wave in order:
+
+1. **Create an isolated git worktree** for each task in the current wave:
+
+   ```bash
+   git worktree add ../worktrees/agent-<task-id> -b agent/<task-id>
+   ```
+
+2. **Spawn a task agent** inside that worktree (using the approved model from
+   the split plan), with:
+   - The task id, summary, and acceptance criteria as its brief.
+   - Instruction to work **test-first** (TDD): write the failing test(s) that
+     match the acceptance criteria before implementing.
+   - Instruction to commit its work to the worktree branch.
+
+3. **Same-wave tasks run in parallel** (within-wave tasks have no
+   inter-task dependency; the dependency graph guarantees this). Same-file
+   overlap surfaces as a merge conflict at reconcile time, not a live race —
+   isolated worktrees prevent clobbering.
+
+4. **Wait for all tasks in the wave to complete** before starting the next wave.
+
+### TDD-gated merge — main agent, no human per task
+
+For each completed task worktree, the main agent:
+
+1. **Runs the task's tests before merge** (on the main branch): baseline must
+   pass (or the relevant tests must be absent — the task adds them).
+2. **Merges the worktree branch** into the main branch:
+
+   ```bash
+   git merge --no-ff agent/<task-id>
+   ```
+
+3. **Runs the task's tests after merge**: they must pass. If they do not, the
+   merge is reverted and the task agent is given the failure output to fix.
+4. **Removes the worktree** once the merge is accepted:
+
+   ```bash
+   git worktree remove ../worktrees/agent-<task-id>
+   ```
+
+The human does **not** review individual task merges. Per-task acceptance is
+the main agent's responsibility — the TDD gate (tests pass before AND after
+merge) plus the task's acceptance criteria. This mirrors the non-authoritative
+working state pattern of the Human Review Loop (#17): per-task merge records
+are uncommitted working state; the authoritative human gate is the final PR.
+
+Advance to the next wave only after all tasks in the current wave are merged
+and their tests pass.
+
+### Human gate 3 — the final PR
+
+Once all waves are merged and the full test suite passes, the main agent opens
+a PR via the repo's PR workflow (e.g. the `cicd` skill's `agex pr open`, the
+`pr-review` skill, or `gh pr create`). The human reviews and merges. This
+is the last and only remaining human gate.
+
+## Hard rules (do not violate)
+
+These protect the human-gate contract and the TDD guarantee.
+
+- **Present the split plan before any fan-out.** Never spawn a task agent
+  without prior human approval of the implementation split plan (gate 2). The
+  split plan is the human's only implementation-stage decision.
+- **One worktree per task.** Never run two tasks in the same worktree — file
+  contention is managed by isolation, not by trust in the dependency graph.
+  The dependency graph guarantees *logical* independence within a wave, not
+  *file* disjointness. Conflicts surface at merge time.
+- **Tests before AND after merge — no exceptions.** The TDD gate must pass on
+  both sides. A merge that makes tests pass only after (not before) means the
+  baseline was already broken — fix the baseline first.
+- **Human does not gate per-task merges.** The TDD contract replaces the
+  human here. Do not pause for human approval between wave tasks.
+- **devague CLI is not orchestrated.** `devague plan waves` is read-only
+  scheduling metadata (#20). Never run `devague plan` commands inside a task
+  worktree to "mark a task done" or modify plan state from a subagent.
+- **Three gates only.** The human's gates are: (1) the exported spec, (2) the
+  implementation split plan, (3) the final PR. No silent fourth gate.
+- **No LLM calls in the devague CLI.** The CLI is deterministic. This skill
+  adds orchestration convention, not CLI behavior.
+
+## Output contract
+
+The `split-plan` subcommand prints to **stdout** and exits 0 when a converged
+plan is found. On error (no plan, cyclic graph) it exits non-zero with a
+`hint:` line on stderr. The `waves` subcommand forwards the CLI's own output
+contract (stdout, `--json` for structured output, exit 0 on success).
+
+## Worked example
+
+Picking up after `/spec-to-plan` exported a plan for the frame `my-feature`:
+
+```bash
+a() { bash .claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh "$@"; }
+
+# 1. Inspect the waves
+a waves
+
+# 2. Present the implementation split plan for human review
+a split-plan
+
+# --- HUMAN: review the table, edit agent/model assignments if needed,
+#     then say "approved" to proceed ---
+
+# 3. Fan out wave 1 (t1, t2, t3 are independent — run in parallel)
+git worktree add ../worktrees/agent-t1 -b agent/t1
+git worktree add ../worktrees/agent-t2 -b agent/t2
+git worktree add ../worktrees/agent-t3 -b agent/t3
+# ... spawn task agents in each worktree, await completion ...
+
+# 4. TDD-gated merge for each wave-1 task (no human per task)
+git merge --no-ff agent/t1   # tests pass before + after
+git worktree remove ../worktrees/agent-t1
+git merge --no-ff agent/t2
+git worktree remove ../worktrees/agent-t2
+git merge --no-ff agent/t3
+git worktree remove ../worktrees/agent-t3
+
+# 5. Advance to wave 2 (t4 depends on t1–t3 being merged)
+git worktree add ../worktrees/agent-t4 -b agent/t4
+# ... spawn, await, merge with TDD gate, remove worktree ...
+
+# 6. Open the final PR (human gate 3) via your repo's PR workflow —
+#    e.g. the cicd skill (`agex pr open`), the pr-review skill, or `gh pr create`.
+```
+
+The exported plan-md from `devague plan export` is the standing brief for
+each task agent — its task id, summary, acceptance criteria, and the targets
+it covers are already in that file.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, where
+the devague agent maintains it alongside the tools it operates (dogfooding),
+next to its siblings `/think` and `/spec-to-plan`. It is the *third* skill in
+that outbound family, covering the implementation leg after a plan converges.
+The flow runs the *opposite* direction of the vendored guildmaster skills:
+guildmaster pulls this **from** devague and broadcasts it to the rest of the
+AgentCulture mesh. The `cite, don't import` policy still holds: downstream repos copy it,
+they don't symlink or depend on it. See `docs/skill-sources.md`.

agentirc_cli-9.7.0/.claude/skills/assign-to-workforce/scripts/assign-to-workforce.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# assign-to-workforce.sh — fan out devague plan waves to parallel agents.
+#
+# The skill is named `assign-to-workforce`; it reads `devague plan waves`
+# (scheduling metadata produced by the /spec-to-plan skill) and renders the
+# implementation split plan: task map + per-task agent/model proposal + a
+# go/no-go prompt for the human. The actual fan-out (worktree creation,
+# spawning, TDD-gated merges) is performed by the operator/main agent once
+# the human approves the split plan.
+#
+# The devague CLI is non-orchestrating (#20): `devague plan waves` describes
+# the dependency graph; it does not spawn agents, manage worktrees, or pick
+# a backend. This wrapper is the operator-facing helper.
+#
+# Origin: authored and maintained in agentculture/devague. guildmaster pulls this
+# skill from here and broadcasts it to the rest of the AgentCulture mesh, so
+# it is written to run anywhere — portable bash, no devague-checkout assumptions.
+#
+# Plans persist under .devague/ in the current directory, so run from the repo
+# you are implementing.
+
+set -euo pipefail
+
+# ── resolve the devague CLI (mesh-first, then local-dev fallback) ───────────
+DEVAGUE=()
+resolve_devague() {
+    if command -v devague >/dev/null 2>&1; then
+        DEVAGUE=(devague)            # installed tool — the normal mesh case
+        return 0
+    fi
+    # Local-dev fallback: inside the devague checkout, run via uv.
+    local dir="$PWD"
+    while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+        if [ -f "$dir/pyproject.toml" ] \
+            && grep -q '^name = "devague"' "$dir/pyproject.toml" 2>/dev/null; then
+            if command -v uv >/dev/null 2>&1; then
+                DEVAGUE=(uv run devague)
+                return 0
+            fi
+            break
+        fi
+        dir=$(dirname "$dir")
+    done
+    cat >&2 <<'EOF'
+error: devague CLI not found.
+hint: install it with `uv tool install devague` (or `pipx install devague`),
+      or run from inside the devague checkout with `uv` available.
+      https://github.com/agentculture/devague
+EOF
+    return 1
+}
+
+usage() {
+    cat <<'EOF'
+assign-to-workforce.sh — fan out devague plan waves to parallel agents.
+
+Usage:
+  assign-to-workforce.sh split-plan [--plan <slug>]   print the implementation split plan
+  assign-to-workforce.sh waves      [--plan <slug>] [--json]   list dependency waves
+  assign-to-workforce.sh help                         this help
+
+Commands:
+  split-plan   Read `devague plan waves --json` and render the human-facing
+               implementation split plan: task map + per-task agent/model
+               proposal + go/no-go. Present this to the human before any
+               fan-out; do not proceed without approval.
+  waves        Forward `devague plan waves` (and any extra flags) verbatim.
+               On a converged plan exits 0 and lists the dependency waves.
+
+Plans persist under .devague/ in the current directory — run from the repo
+you are implementing. Results go to stdout, diagnostics to stderr.
+
+Human gates (three only):
+  1. The exported spec (already closed by the /think leg).
+  2. This implementation split plan (go/no-go to assign to workforce).
+  3. The final PR (opened by the main agent via the repo's PR workflow,
+     e.g. `cicd` / `agex pr open`, `pr-review`, or `gh pr create`).
+
+The devague CLI is non-orchestrating (#20): `devague plan waves` describes
+the graph; the operator performs the fan-out. One worktree per task; TDD
+gates every merge (tests pass before AND after merge); no human per task.
+EOF
+}
+
+# ── split-plan: render the implementation split plan for human review ────────
+cmd_split_plan() {
+    local extra_args=()
+    # Forward any --plan flag so waves targets the right plan.
+    while [ $# -gt 0 ]; do
+        extra_args+=("$1")
+        shift
+    done
+
+    local waves_json tmp_err waves_rc old_exit_trap
+    # Clean up the temp file on any exit path — including a signal after its
+    # creation — WITHOUT permanently changing the script's process-global EXIT
+    # handling. Capture any prior EXIT trap BEFORE mktemp (that capture forks a
+    # subshell, so doing it first keeps it out of the untracked-file window),
+    # then install our cleanup trap on the line immediately after mktemp, and
+    # restore the prior trap once the file is safely gone (#30; PR #31 review;
+    # devague#32).
+    old_exit_trap="$(trap -p EXIT)"
+    tmp_err="$(mktemp)"
+    trap 'rm -f "$tmp_err"' EXIT
+    set +e
+    waves_json="$("${DEVAGUE[@]}" plan waves --json "${extra_args[@]}" 2>"$tmp_err")"
+    waves_rc=$?
+    set -e
+    local waves_err
+    waves_err="$(cat "$tmp_err")"
+    rm -f "$tmp_err"
+    trap - EXIT
+    eval "${old_exit_trap}"  # empty string is a no-op; re-installs a prior trap if any
+
+    if [ "$waves_rc" -ne 0 ]; then
+        printf '%s\n' "$waves_err" >&2
+        return "$waves_rc"
+    fi
+
+    DEVAGUE_WAVES_JSON="$waves_json" python3 - <<'PY'
+import json
+import os
+import sys
+
+raw = os.environ.get("DEVAGUE_WAVES_JSON", "").strip()
+if not raw:
+    print("error: no waves output from devague plan waves", file=sys.stderr)
+    print("hint: ensure a converged plan exists (devague plan converge)", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    data = json.loads(raw)
+except json.JSONDecodeError as exc:
+    print(f"error: could not parse waves JSON: {exc}", file=sys.stderr)
+    sys.exit(1)
+
+plan_slug = data.get("plan", "(unknown)")
+waves = data.get("waves") or []
+
+print(f"Implementation split plan — plan: {plan_slug}")
+print()
+print("Dependency waves (from `devague plan waves`):")
+for i, wave in enumerate(waves, 1):
+    tasks = ", ".join(wave)
+    print(f"  Wave {i}: [{tasks}]")
+
+print()
+print("Task assignments (proposed — edit before approving):")
+print()
+
+headers = ("Task", "Wave", "Summary", "Agent type", "Model", "Scope note")
+rows = []
+for i, wave in enumerate(waves, 1):
+    for task_id in wave:
+        rows.append((
+            task_id,
+            str(i),
+            "(see plan export for summary + acceptance criteria)",
+            "subagent",
+            "cheaper/faster",
+            "TDD-scoped task; isolated worktree; tests gate merge",
+        ))
+
+col_widths = [max(len(h), max((len(r[j]) for r in rows), default=0))
+              for j, h in enumerate(headers)]
+
+def row_str(cells):
+    return "| " + " | ".join(c.ljust(w) for c, w in zip(cells, col_widths)) + " |"
+
+sep = "| " + " | ".join("-" * w for w in col_widths) + " |"
+print(row_str(headers))
+print(sep)
+for row in rows:
+    print(row_str(row))
+
+print()
+print("Go/no-go: review the table above, edit agent type / model / scope as needed,")
+print("then confirm: \"Approved — assign to workforce\" or \"Edit first\".")
+print()
+print("Once approved, fan out wave by wave:")
+print("  1. Create one git worktree per task in the wave.")
+print("  2. Spawn a task agent per worktree (brief = task summary + acceptance criteria).")
+print("  3. Await all tasks in the wave; then TDD-gate each merge (tests before + after).")
+print("  4. Advance to the next wave.")
+print("  5. Open the final PR (human gate 3) after all waves merge and tests pass.")
+PY
+}
+
+main() {
+    case "${1:-help}" in
+        help | -h | --help)
+            usage
+            return 0
+            ;;
+        split-plan)
+            shift
+            resolve_devague
+            cmd_split_plan "$@"
+            ;;
+        waves)
+            shift
+            resolve_devague
+            exec "${DEVAGUE[@]}" plan waves "$@"
+            ;;
+        *)
+            printf 'error: unknown subcommand: %s\n' "$1" >&2
+            printf 'hint: run `assign-to-workforce.sh help` for usage\n' >&2
+            return 1
+            ;;
+    esac
+}
+
+main "$@"

agentirc_cli-9.7.0/.claude/skills/cicd/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: cicd
+description: >
+  agentirc's CI/CD lane, layered on `agex pr`. Delegates lint / open /
+  read / reply / delta to agex; adds two extensions — `status`
+  (SonarCloud quality gate + hotspots + unresolved-thread tally) and
+  `await` (read --wait + status with non-zero exit on Sonar ERROR or
+  unresolved threads). Use when: creating PRs in agentirc, handling
+  review feedback, polling CI status, or the user says "create PR",
+  "review comments", "address feedback", "resolve threads". Renamed
+  from `pr-review` in steward 0.7.0; rebased on agex in 0.12.0.
+---
+
+# CI/CD — agentirc edition
+
+`agex pr` (in `agentculture/agex-cli`) is the upstream for the
+five core PR-lifecycle verbs — `lint`, `open`, `read`, `reply`,
+`delta`. The upstream (steward) used to vendor parallel scripts for each;
+in 0.12.0 those vendored copies were dropped in favor of delegating to
+`agex`. What's left in this skill is **the gating layer on top of agex**:
+
+- `status` — SonarCloud quality gate, OPEN issues, hotspots, deploy
+  preview URL, unresolved-inline-thread tally.
+- `await` — composes `agex pr read --wait` with `status` and gates on
+  Sonar `ERROR` / unresolved threads. The single command to run after
+  pushing a fix when you want "wake me when this PR is triage-able."
+
+Those two are the unique surface today. The `await` combo verb
+landed natively in agex
+([agex-cli#41](https://github.com/agentculture/agex-cli/issues/41), now
+closed); the gate extras that aren't yet native — SonarCloud hotspots,
+deploy-preview URL, an explicit resolved/unresolved thread tally — are
+tracked upstream in
+[agex-cli#52](https://github.com/agentculture/agex-cli/issues/52) and
+migrate out of this skill once they land.
+
+The workflow is encapsulated in `scripts/workflow.sh` — follow that
+(or call `agex pr` directly).
+
+> **Vendored from `../steward/.claude/skills/cicd/` per
+> `docs/steward/onboarding.md`.** Re-sync explicitly when steward updates
+> upstream — there is no auto-sync.
+
+## Prerequisites
+
+Hard requirements: `agex` (>=0.1), `gh` (GitHub CLI), `jq`, `bash`,
+`python3` (stdlib only), `curl` (used by `pr-status.sh`).
+
+Install agex once:
+
+```bash
+uv tool install agex-cli   # or: pip install --user agex-cli
+```
+
+Soft requirement: `PyYAML` is needed **only for suffix mode** of the
+sibling `agent-config` skill, where it parses Culture's server
+manifest. Every `cicd` script works without it; suffix mode prints a
+clear install hint when invoked without it.
+
+Per-machine paths (sibling-project layout) live in
+`.claude/skills.local.yaml`; see the committed `.example` for the
+schema. `agex pr delta` reads the same file.
+
+## How to run
+
+`scripts/workflow.sh` is the entry point. Subcommands:
+
+| Command | What it does |
+|---------|--------------|
+| `workflow.sh lint` | `agex pr lint --exit-on-violation` — portability + alignment-trigger check. |
+| `workflow.sh open [gh-flags]` | `agex pr open --delayed-read`. Creates the PR, then polls 180s for an initial briefing. `--title TITLE` required; body via `--body-file PATH` or stdin. |
+| `workflow.sh read [PR] [--wait N]` | `agex pr read`. One-shot briefing (CI checks, SonarCloud gate + new issues, all comments, next-step footer). Pass `--wait N` to poll up to N seconds for required reviewers. |
+| `workflow.sh reply <PR>` | `agex pr reply <PR>` — batch JSONL replies (stdin) + thread resolve. agex auto-signs from `culture.yaml`. |
+| `workflow.sh delta` | `agex pr delta` — sibling alignment dump. |
+| `workflow.sh status <PR>` | **agentirc extension.** `pr-status.sh` — Sonar gate, OPEN issues, hotspots, unresolved-thread breakdown, deploy preview URL. Authoritative gate for `await`. |
+| `workflow.sh await <PR>` | **agentirc extension.** `agex pr read --wait` then `status`. Exits non-zero on Sonar ERROR or unresolved threads. Tunables: `STEWARD_PR_AWAIT_WAIT` (default 1800s passed to `--wait`), `STEWARD_PR_AWAIT_SECONDS` (legacy fixed pre-sleep, deprecated). |
+| `workflow.sh help` | Print the list. |
+
+You can also call `agex pr <verb>` directly — `workflow.sh` is a
+typing-saver around the same verbs. The agentirc `status` and `await`
+extensions only have shell entry points.
+
+The vendored single-comment helper `pr-reply.sh` (plus its
+`_resolve-nick.sh` dependency) is still shipped — useful for one-off
+single-comment replies that don't merit a full batch JSONL run. It is not
+called by `workflow.sh` anymore. The vendored `portability-lint.sh`
+is also still shipped — agentirc's CI lint job (`.github/workflows/tests.yml`)
+runs it directly. `portability-lint.sh` catches two recurring bug classes
+for agentirc PRs (which touch the bootstrap spec, `CLAUDE.md`, vendored
+skills, and the IRCd server core):
+
+- **Path leaks** — committing absolute home-directory paths that work only
+  on the author's machine, breaking CI and other contributors.
+- **Per-user config dependencies** — referencing dotfiles under the user's
+  home dir in repo guidance, breaking reproducibility.
+
+Both helpers are scheduled for follow-up migration to agex.
+
+## Long waits (background polling)
+
+`agex pr read --wait N` polls in-session for up to N seconds. The
+Anthropic prompt cache has a 5-minute TTL; sleeping past it burns
+context every cache miss. Two ways to drive the wait:
+
+- **Synchronous** — `workflow.sh await <PR>` after `gh pr create` /
+  `workflow.sh open`. Fine when readiness is expected within ~5
+  minutes.
+- **Asynchronous** — for longer waits, run `agex pr read --wait NNN`
+  inside a background subagent (Agent tool, `run_in_background: true`)
+  so the main session only pays the cache cost when readiness fires.
+  The subagent's only job is to invoke `agex pr read --wait` and echo
+  its headline back. The parent triages with `workflow.sh await`
+  when the notification arrives. The user can interrupt with
+  TaskStop.
+
+This pattern was originally borrowed from sibling repo
+[`agentculture/cfafi`](https://github.com/agentculture/cfafi)'s `poll`
+skill. The async guidance is also filed upstream
+([agex-cli#41](https://github.com/agentculture/agex-cli/issues/41)).
+
+## Conventions
+
+`agex pr` emits a **"Next step:"** footer at the end of every command
+that names the right next verb (the same chain `agex learn cicd`
+documents) — follow that rather than memorizing an order. `workflow.sh
+help` mirrors the verb table when you need the agentirc-layer
+extensions (`status`, `await`) on top.
+
+Branch naming: `fix/<desc>`, `feat/<desc>`, `docs/<desc>`,
+`skill/<name>`. PR / comment signature: `- <nick> (Claude)`, where
+`<nick>` is resolved by `agex` from the agent's own `culture.yaml`
+(first agent's `suffix`), falling back to the git-repo basename. For
+agentirc (no `culture.yaml` present), `_resolve-nick.sh` falls back to
+the repo basename — `agentirc`. agex auto-appends the signature on
+`pr open` and `pr reply` only when the body isn't already signed.
+
+## Finishing a branch
+
+When implementation on a branch is complete and tests pass, go straight
+to `workflow.sh open` (push the branch + open the PR). Do **not** stop to
+present a *merge / PR / keep / discard* menu and wait for a choice — in
+AgentCulture the standing default is **always "push and create a Pull
+Request."** This overrides the Superpowers `finishing-a-development-branch`
+skill's interactive menu, which otherwise pauses the flow at the moment
+work is ready to integrate. Merge-locally, keep-as-is, and discard happen
+only when the user explicitly asks for one of them.
+
+## Triage rules
+
+For every comment, decide **FIX** or **PUSHBACK** with reasoning.
+
+Default to **FIX** for: portability complaints (always valid for
+agentirc — recurring bug class for PRs touching the bootstrap spec,
+`CLAUDE.md`, vendored skills, or the IRCd server core), test or doc
+requests, style nits aligned with workspace conventions.
+
+Default to **PUSHBACK** for: architecture opinions that conflict with
+the workspace or repo `CLAUDE.md` invariants; note that the all-backends
+rule does NOT apply inside agentirc (agentirc has no backends — that rule
+lives in culture); greenfield false-positives (e.g. "add tests" before
+there's any source — defer to a later PR, don't refuse).
+
+### Alignment-delta rule
+
+If the PR touches `CLAUDE.md`, `culture.yaml`, or anything under
+`.claude/skills/`, run `workflow.sh delta` **before** declaring FIX or
+PUSHBACK on each comment. Note any sibling that needs a follow-up PR
+and mention it in your reply.
+
+## Greenfield-aware steps
+
+The lint and the workflow script are always-on. Stack-specific steps
+are conditional and currently no-op (greenfield repo):
+
+```bash
+[ -d tests ] && [ -f pyproject.toml ] && uv run pytest tests/ -x -q
+[ -f pyproject.toml ] && bump_version_per_project_convention   # see project README
+[ -f .markdownlint-cli2.yaml ] && markdownlint-cli2 "$(git diff --name-only --cached '*.md')"
+```
+
+Revisit each line as the corresponding stack element actually lands.
+A `pr lint --extra=tests,version,markdown` ask is filed upstream
+([agex-cli#41](https://github.com/agentculture/agex-cli/issues/41)).
+
+## Reply etiquette
+
+Every comment must get a reply — no silent fixes. `agex pr reply`
+includes thread-resolve by default. Reference the review-comment IDs
+in the fix-up commit message.
+
+The `status` extension queries SonarCloud directly (it predates the
+upstream Sonar integration in `agex pr read`). Both surfaces are
+trustworthy — `agex pr read` for display in the briefing, `status` for
+the gate. agentirc isn't yet a registered mesh agent, so the
+post-merge IRC ping that Culture's `pr-review` includes is still
+skipped — that returns when agentirc joins the mesh.