[AAASM-3942] ✨ (skills): Add reusable org-level skill files

.claude/skills/choose-repo.md

@@ -0,0 +1,52 @@
+# Skill: choose-repo
+
+**When to use:** you know *what* needs to change but not *which* org repo it
+belongs in. Get this right before branching — cross-repo confusion is the
+most common source of wasted PRs in this org.
+
+## Decision tree
+
+Start from the task, not the repo you happen to be sitting in:
+
+1. **Does a JIRA ticket exist?** Check its Component field
+   (`customfield_10041`) first — it is a 1:1 mapping to the GitHub repo
+   (`ai-agent-assembly/<repo>`) and is authoritative. Don't second-guess it
+   from the ticket title; if it looks wrong, ask rather than silently
+   re-routing (see `feedback_repo_routing` class of mistakes: don't trust a
+   title-based guess over the Component field, and don't trust the Component
+   field blindly either if the described work clearly doesn't match it —
+   flag the mismatch).
+2. **No ticket, or ticket has no Component set** — use the work itself:
+
+   | Task looks like... | Repo |
+   |---|---|
+   | Gateway, policy engine, eBPF, proxy, FFI, CLI (`aasm`), dashboard, or any shared `aa-*` crate | `agent-assembly` |
+   | Python-specific SDK shim/packaging/docs | `python-sdk` |
+   | Node/TypeScript-specific SDK shim/packaging/docs | `node-sdk` |
+   | Go-specific SDK shim/packaging/docs | `go-sdk` |
+   | Public docs site content | `agent-assembly-docs` |
+   | Internal/private docs site content | `inner-document` |
+   | Cloud control plane (FastAPI/React/persistence) | `agent-assembly-cloud` |
+   | Enterprise-only Rust extensions | `agent-assembly-enterprise` |
+   | Runnable demo/sample code | `agent-assembly-examples` |
+   | Cross-repo or private e2e test suites | `agent-assembly-integration-tests` / `agent-assembly-private-e2e` |
+   | Homebrew formula/tap | `homebrew-agent-assembly` |
+   | Org community-health files, reusable CI workflow templates, org-level AI baseline (`CLAUDE.md`/`AGENTS.md`/`.claude/`) | `.github` (this repo) or `.github-private` |
+   | Protocol/spec content | `agent-assembly` monorepo — **not** `agent-assembly-spec` (archived; see project policy in `CLAUDE.md`) |
+
+3. **Task spans more than one repo** (e.g. an API changes in
+   `agent-assembly` and a consumer must follow in `python-sdk`) — this is
+   cross-repo work. Don't split it into unrelated single-repo tickets without
+   coordination; that's what `cross-repo-coordinator` (a global skill, not
+   org-specific) is for.
+4. **Still ambiguous** — read the repo map table in `CLAUDE.md` /
+   `AGENTS.md` (`## Repo map`) for the one-line role of every repo, or ask
+   rather than guessing.
+
+## Do not
+
+- Do not assume the repo you're currently checked out in is the right one
+  just because that's where the session started.
+- Do not put spec work in `agent-assembly-spec` — it's archived by policy.
+- Do not propose Helm/Terraform/self-hosted infra tickets for any repo —
+  out of scope product-wide (see `CLAUDE.md` project policy).

.claude/skills/contribution-guide.md

@@ -0,0 +1,51 @@
+# Skill: contribution-guide
+
+**When to use:** you've completed `task-intake` and `setup-dev-env` and are
+ready to implement and land a change in any `ai-agent-assembly` repo.
+
+## Flow
+
+1. **Worktree.** Develop the ticket in a dedicated git worktree branched off
+   the latest default branch (or off a dependency's branch, if stacked — see
+   `task-intake`), so the main checkout stays clean and multiple tickets can
+   be worked concurrently. Remove the worktree after the PR merges.
+2. **Implement.** Change only what the ticket describes. Read the target
+   repo's `.claude/CLAUDE.md` for architecture constraints before touching
+   unfamiliar code. Before touching anything that handles secrets,
+   credentials, user input, or shells out to external commands, re-read
+   `.claude/rules/01-security.md` — it's the one rule worth checking per
+   ticket, not just once at onboarding.
+3. **Commit atomically.** One logical unit per commit — one new file, one
+   function, one property change. Format:
+   ```
+   <emoji> (<scope>): <imperative summary>
+   ```
+   (gitmoji.dev conventions; see `CLAUDE.md` for the emoji table). Each
+   commit should be independently understandable and the repo should build
+   at every commit (bisectable). Never bundle a feature with a refactor of
+   surrounding code, and never bundle new code with its own tests in the
+   same commit — tests are their own commit.
+4. **Push to the canonical remote** — confirmed in `setup-dev-env`, not
+   assumed to be `origin`.
+5. **Open a PR using the repo's PR template** (`.github/PULL_REQUEST_TEMPLATE.md`
+   in that repo, or the org default in this repo). Title format:
+   ```
+   [<ticket>] <emoji> (<scope>): <summary>
+   ```
+   Base branch is always the repo's default branch (`master` or `main` —
+   confirmed in `setup-dev-env`), never another feature branch, even for
+   stacked work — note the stacking dependency in the PR body instead
+   (e.g. "Depends on #NN, not yet merged").
+6. **Request review.** At least one approval from the required team is
+   needed before merge (Pioneer team, per `CLAUDE.md`).
+7. **Never merge directly.** All changes land through PR review — this
+   applies even for trivial changes and even when you have push access to
+   the default branch.
+
+## Do not
+
+- Do not force-push during active review.
+- Do not skip pre-commit hooks (`--no-verify`) without explicit confirmation.
+- Do not open a PR against another feature branch as the base — always
+  target the default branch, and call out stacking in the description.
+- Do not merge your own PR, even if CI is green and the change looks small.

.claude/skills/issue-classification.md

@@ -0,0 +1,49 @@
+# Skill: issue-classification
+
+**When to use:** triaging a new issue or ticket before it gets a repo, an
+Epic, or a Subtask assigned — figure out what kind of work it actually is
+first.
+
+## 1. Bug, feature, docs, or environment/tooling blocker?
+
+Mirror the distinction this org already draws in `CLAUDE.md`'s CI-reality
+note: not every red signal is a product bug.
+
+| Signal | Classification | Action |
+|---|---|---|
+| Code produces wrong output, crashes, or violates a documented contract | **Product bug** | File as a Bug-type ticket against the owning repo. |
+| CI/infra fails for a reason unrelated to the code under test (e.g. GitHub Actions billing-block, a flaky external dependency, a missing local toolchain) | **Environment/tooling blocker** | Do not file as a product bug. Confirm via job annotations or reproduction; note it as infra and validate locally instead of treating it as a code defect. |
+| New capability requested that doesn't exist yet | **Feature** | File as a Story (or Subtask if small and unambiguous) with acceptance criteria. |
+| Content is missing, wrong, or unclear in docs/README/spec | **Docs** | File as a docs-type ticket against the repo that owns that content (see `choose-repo` — usually `agent-assembly-docs`/`inner-document`, or the monorepo for the Protocol Specification). |
+
+If unsure whether something is a genuine product bug versus an environment
+artifact, reproduce it locally before filing — don't file from CI logs alone.
+
+## 2. Which repo/component?
+
+Use the `choose-repo` skill. Set the ticket's Component field
+(`customfield_10041`) to the owning repo — this is a 1:1 mapping and other
+skills/agents rely on it being accurate.
+
+## 3. Epic or standalone?
+
+- **Needs an Epic** when the work is part of a larger initiative already
+  tracked (check for an existing Epic in the same problem space before
+  creating a new one), or when it will require multiple Stories/Subtasks
+  across more than one PR.
+- **Standalone** (a single Story or even a single Subtask with no parent
+  Epic) when the fix is small, self-contained, and unlikely to spawn related
+  follow-up work — e.g. a single-file bugfix or a doc correction.
+- When several related bugs surface from the same root cause (e.g. the same
+  class of bug found in multiple repos during a sweep), consider grouping
+  them under one Epic rather than filing fully independent tickets — makes
+  the pattern visible instead of scattered.
+
+## Do not
+
+- Do not file an environment/infra failure as a product bug — it pollutes
+  the bug backlog and produces misleading trend data.
+- Do not create a new Epic when an applicable one already exists — search
+  first.
+- Do not leave the Component field unset "to decide later" — set it at
+  triage time, even if it's a best guess that gets corrected.

.claude/skills/onboard-org.md

@@ -0,0 +1,43 @@
+# Skill: onboard-org
+
+**When to use:** you (human or AI) are working in the `ai-agent-assembly` org
+for the first time this session — either a fresh machine, a fresh contributor,
+or a fresh agent context with no prior memory of this org.
+
+## Steps
+
+1. **Read the org baseline.** Claude Code: read `CLAUDE.md` at the root of
+   whichever repo you're in (it links back to `.github`'s `CLAUDE.md` as the
+   canonical source). Codex or any other `AGENTS.md`-reading tool: read
+   `AGENTS.md` instead — same content, Codex-facing. Do not skip this even if
+   the task looks small; it covers commit/branch/PR conventions, remote
+   naming, CI reality, and JIRA field mapping you will need immediately. Also
+   read `.claude/rules/01-security.md` specifically before writing any code —
+   of everything in `.claude/rules/`, it's the one with real blast radius if
+   skipped.
+2. **Confirm the workspace layout**, if you're operating from a multi-repo
+   workspace root rather than a single repo checkout — see
+   `.claude/WORKSPACE.md` in `.github` for the expected layout
+   (`~/ai-agent-assembly/<repo>/` siblings, org files installed at the root).
+3. **Pick the repo relevant to your task** — see the `choose-repo` skill for
+   the decision tree. Don't guess from the ticket title alone; check the
+   ticket's Component field first.
+4. **Bootstrap your local workspace**, once `AAASM-3943` ships: the org
+   baseline (`CLAUDE.md`, `AGENTS.md`, `.claude/rules/`, `.claude/skills/`)
+   will be installable into a workspace root via
+   `scripts/bootstrap-ai-workspace.sh` (exact CLI interface TBD — check the
+   script's own `--help` once it exists rather than assuming flags here).
+   Until then, clone `.github` directly and read its files in place, or read
+   them from whichever repo already carries a synced copy.
+5. **Read the target repo's own `.claude/CLAUDE.md` (or `AGENTS.md`)** before
+   writing any code. Repo-local files override or extend the org baseline for
+   that repo — build/test/lint commands, directory conventions, and gotchas
+   live there, not in the org baseline.
+
+## Do not
+
+- Do not restate org policy (commit format, branch format, remote naming,
+  JIRA fields) in task output — link back to `CLAUDE.md`/`AGENTS.md` instead.
+- Do not assume a repo's default branch or canonical remote name — both vary
+  per repo. Confirm with `git remote -v` and
+  `git ls-remote --symref <remote> HEAD` (see `setup-dev-env`).

.claude/skills/pr-review.md

@@ -0,0 +1,55 @@
+# Skill: pr-review
+
+**When to use:** immediately before requesting review on a PR — a final
+self-check pass, not a substitute for actual reviewer feedback.
+
+## Checklist
+
+- [ ] **Scope matches the ticket.** `git diff` against the base branch
+  touches only what the ticket describes. No drive-by refactors, renames, or
+  formatting-only changes to unrelated files bundled in.
+- [ ] **No unrelated changes bundled.** If you found and fixed something
+  unrelated while working, split it into its own commit/PR/ticket rather
+  than folding it in here.
+- [ ] **Commit messages follow gitmoji format.** Each commit is
+  `<emoji> (<scope>): <imperative summary>`, matches the change it
+  describes, and the history is bisectable (repo builds at every commit).
+- [ ] **PR title follows the convention:**
+  `[<ticket>] <emoji> (<scope>): <summary>`.
+- [ ] **PR body follows the repo's PR template** exactly — section headers
+  present, Jira ticket linked, checklist items addressed rather than left as
+  unchecked boilerplate.
+- [ ] **Base branch is correct** — the repo's actual default branch
+  (`master` or `main`, confirmed per `setup-dev-env`), not another feature
+  branch. If this PR is stacked on an unmerged dependency, that's called out
+  explicitly in the Summary (e.g. "Depends on #NN").
+- [ ] **Tests run and pass locally**, if the repo has a test suite and the
+  change touches tested code. Point at the repo's own `.claude/CLAUDE.md`
+  for the exact test command — don't guess.
+- [ ] **Lint/format/type-check run and pass locally**, if the repo has that
+  tooling configured. Same note — commands are repo-specific.
+- [ ] **All CI checks are green**, with one named exception: the known
+  GitHub Actions billing-block (see `CLAUDE.md`'s "CI reality" note) — a
+  `GitHub Actions` check-suite that completes in a few seconds with **zero
+  jobs**. Confirm that's actually what happened (`gh api
+  repos/<org>/<repo>/commits/<sha>/check-suites`, or the job annotations) before
+  waving a red check through — don't assume every red check is the billing
+  block. Any other failure (test, lint, type-check, build, a real Actions job
+  that ran and failed) must be fixed before requesting review, even if it
+  looks unrelated to your change. Coverage/SonarQube-style acceptance gates
+  that only fail because upstream Actions jobs never produced artifacts (a
+  downstream symptom of the same billing block) fall under the same
+  exception — don't chase those either.
+- [ ] **No security rule violations** per `.claude/rules/01-security.md` —
+  no secrets, credentials, tokens, or `.env` files in the diff; no dangerous
+  patterns (`curl | bash`, `eval` on untrusted input, `--no-verify`,
+  force-push to a shared branch) introduced.
+- [ ] **No build artifacts, compiled output, or commented-out dead code**
+  in the diff.
+
+## Do not
+
+- Do not treat this checklist as a substitute for actually reading your own
+  diff line by line — read it once before checking any box.
+- Do not check a box you haven't actually verified (e.g. "tests pass") just
+  because the change looks trivial.

.claude/skills/pr-reviewer.md

@@ -0,0 +1,115 @@
+# Skill: pr-reviewer
+
+**When to use:** you've been asked to *review* a PR — yours or someone
+else's, already open — not to write one. This is the reviewer's side of the
+exchange; `pr-review` is the author's self-check before requesting review.
+Don't conflate the two: this skill assumes the PR already exists and may
+have CI results, and its output is a review comment, not a code change
+(unless the requester separately asks you to also fix what you find).
+
+## 1. CI status
+
+Check every reported status, not just the overall summary:
+
+- If everything is green, move on.
+- If something is red, confirm *why* before deciding it's real. The org's
+  known GitHub Actions billing-block completes a check-suite in a few
+  seconds with **zero jobs** (`gh api repos/<org>/<repo>/commits/<sha>/check-suites`
+  or the job annotations will show this) — treat that as infra, not a code
+  failure, per `CLAUDE.md`'s CI-reality note. A downstream check (SonarQube,
+  Codecov) stuck `queued` or failing only because it never got artifacts
+  from a billing-blocked Actions run falls under the same exception.
+- Anything else red — a test, lint, type-check, or build job that actually
+  ran and failed — is a real failure. Fix it (if asked to) or block the
+  review on it (if only asked to review).
+- Coverage/SonarQube-style acceptance gates that fail on their own merits
+  (not as a billing-block symptom) can be called out but don't have to block
+  approval — flag them as a judgment call for whoever merges, per whatever
+  the requester told you about acceptable-to-ignore categories.
+
+## 2. Scope vs. ticket
+
+Read the actual ticket (description, acceptance criteria, and comment
+history — not just the title) and the PR description, then check the real
+diff against both:
+
+- Does the PR cover every acceptance criterion? List them and mark each one
+  met/not-met with evidence (a file, a line, a test) — don't just assert
+  "looks complete."
+- Does the PR do *only* what the ticket describes, or is something unrelated
+  bundled in (a drive-by refactor, an unrelated fix, a formatting pass on
+  untouched files)?
+- If the PR's own description claims something ("tested X", "verified Y"),
+  don't take it at face value — re-derive or spot-check it yourself where
+  practical (e.g. re-run the diff, re-check the file the description
+  references). Trust but verify.
+
+## 3. Side effects and correctness
+
+Read the diff itself, not a summary of it:
+
+- Does any change touch code, config, or docs outside what the ticket
+  describes? Check other files/repos that shouldn't have been touched
+  (`git status --porcelain` in adjacent repos if the change could plausibly
+  have spread there).
+- For any existing (not brand-new) function, file, or behavior being
+  modified: does the change preserve everything it isn't supposed to change?
+  A diff that's "purely additive" should be verified as such (e.g. `git diff
+  <pre-change-ref> <post-change-ref> -- <file>` showing only insertions), not
+  assumed from the PR description.
+- For scripts or code with real runtime behavior, don't just read it — run
+  it (dry-run, a scratch/temp target, existing test suite) if that's
+  feasible without side effects on shared state.
+
+## 4. Security
+
+Check against `.claude/rules/01-security.md` directly, not just skim for
+"anything security-related in the title":
+
+- No secrets, credentials, tokens, or `.env` contents in the diff.
+- No dangerous patterns introduced: `curl | bash`, `eval` on untrusted
+  input, `--no-verify`, force-push to a shared branch, unvalidated
+  input reaching a shell command or SQL query, newly-added write access to
+  something that didn't have it before.
+- For a script or tool that writes to the filesystem or network: confirm it
+  fails safe (doesn't silently overwrite/clobber, doesn't proceed past a
+  failed precondition) rather than trusting a comment that says it does.
+
+## 5. Frontend validation
+
+If the PR touches any FE code (component, page, styling, client-side logic):
+
+- Check the design spec (e.g. `design/vN/` in the target repo) if one
+  exists, and confirm the implementation matches it.
+- Use the Playwright MCP tooling to actually load the affected page(s) and
+  exercise the changed behavior — don't approve FE changes on code reading
+  alone.
+- Capture a screenshot (or short recording) of the validated state. If the
+  repo has a design/validation-report folder, save it there; otherwise note
+  in the review comment where the evidence lives.
+- If the PR touches no FE surface, say so explicitly in the review comment
+  rather than silently omitting the section — it should read as "N/A,
+  confirmed" not "skipped."
+
+## 6. Leave the record
+
+Post a PR comment (not a silent verdict) covering all five checks above,
+even when everything passed — "checked, found nothing" is still a useful
+record. Structure: CI status → scope-vs-ticket → side effects/correctness →
+security → frontend (or N/A) → a clear recommendation (ready to merge /
+mergeable with a named caveat / blocked on X). Do not approve or merge the
+PR yourself unless the requester has explicitly given you that authority —
+default to reporting findings and letting the ticket owner decide, per this
+org's auto-merge policy.
+
+## Do not
+
+- Do not treat every red CI check as the billing-block without confirming
+  it via check-suite/job-annotation evidence first.
+- Do not accept a PR description's claims ("tested", "verified", "no side
+  effects") without independently checking at least a sample of them.
+- Do not skip the security check because the PR "doesn't look like security
+  work" — the highest-risk changes are often the ones not framed that way.
+- Do not skip Playwright validation for FE changes because the change looks
+  small — small FE diffs break rendering just as often as large ones.
+- Do not merge or approve on your own authority unless explicitly told to.