diff --git a/.claude/skills/choose-repo.md b/.claude/skills/choose-repo.md new file mode 100644 index 0000000..efdbb56 --- /dev/null +++ b/.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/`) 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). diff --git a/.claude/skills/contribution-guide.md b/.claude/skills/contribution-guide.md new file mode 100644 index 0000000..98bad03 --- /dev/null +++ b/.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: + ``` + (): + ``` + (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: + ``` + [] (): + ``` + 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. diff --git a/.claude/skills/issue-classification.md b/.claude/skills/issue-classification.md new file mode 100644 index 0000000..9d51d15 --- /dev/null +++ b/.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. diff --git a/.claude/skills/onboard-org.md b/.claude/skills/onboard-org.md new file mode 100644 index 0000000..b0ea3ab --- /dev/null +++ b/.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//` 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 HEAD` (see `setup-dev-env`). diff --git a/.claude/skills/pr-review.md b/.claude/skills/pr-review.md new file mode 100644 index 0000000..ca1335c --- /dev/null +++ b/.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 + ` (): `, matches the change it + describes, and the history is bisectable (repo builds at every commit). +- [ ] **PR title follows the convention:** + `[] (): `. +- [ ] **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///commits//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. diff --git a/.claude/skills/pr-reviewer.md b/.claude/skills/pr-reviewer.md new file mode 100644 index 0000000..3390a5b --- /dev/null +++ b/.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///commits//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 + -- ` 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. diff --git a/.claude/skills/setup-dev-env.md b/.claude/skills/setup-dev-env.md new file mode 100644 index 0000000..21814ef --- /dev/null +++ b/.claude/skills/setup-dev-env.md @@ -0,0 +1,47 @@ +# Skill: setup-dev-env + +**When to use:** setting up a local machine (or a fresh worktree) to work on +one or more `ai-agent-assembly` repos. + +## Checklist + +1. **Clone the relevant repo(s).** Use `choose-repo` to confirm which + repo(s) you actually need before cloning everything. If you're following + the multi-repo workspace layout (`.claude/WORKSPACE.md`), clone into the + sibling-directory layout described there rather than nesting repos inside + each other. +2. **Verify git remote naming before you push anything.** The canonical + remote (pointing at `ai-agent-assembly/`) is named `remote` in some + checkouts and `origin` in others — a local `origin` is sometimes a + personal fork (notably in `go-sdk`). Run: + ``` + git remote -v + ``` + and confirm which remote name resolves to `ai-agent-assembly/`. + **Never assume `origin`.** Also confirm the default branch — most repos + use `master`, but `agent-assembly-docs` and `inner-document` use `main`: + ``` + git ls-remote --symref HEAD + ``` +3. **Install the per-repo toolchain.** Each repo owns its own install/build/ + test/lint commands in its `.claude/CLAUDE.md` (and usually its `README.md` + or `CONTRIBUTING.md`) — don't duplicate those commands here; they drift. + Read that repo's file and run its documented install step (e.g. `cargo + build`, `uv sync`, `pnpm install`, `go mod download` — check the actual + repo, don't assume). +4. **Confirm pre-commit hooks are installed**, if the repo uses them (check + for a `.pre-commit-config.yaml`, `lefthook.yml`, or similar). Run the + repo's documented install command for its hook manager. Never bypass + hooks with `--no-verify` without explicit confirmation from the person + who asked for the work. +5. **Confirm CI health on the default branch** before branching off it — see + the CI reality note in `CLAUDE.md` (GitHub Actions is frequently + billing-blocked; treat that as infra, not a code failure, and validate + locally instead of waiting on CI). + +## Do not + +- Do not hardcode `origin` as the push remote in scripts or muscle memory — + it varies per repo and per contributor's fork setup. +- Do not copy another repo's install commands into this one's setup — always + defer to that repo's own `.claude/CLAUDE.md`. diff --git a/.claude/skills/task-intake.md b/.claude/skills/task-intake.md new file mode 100644 index 0000000..42e55ed --- /dev/null +++ b/.claude/skills/task-intake.md @@ -0,0 +1,44 @@ +# Skill: task-intake + +**When to use:** you have a JIRA ticket (project `AAASM`) and need to go from +"assigned" to "actually writing code." + +## Steps + +1. **Read the ticket and its Epic.** Don't work from the ticket summary alone + — read the full description and acceptance criteria, then open the parent + Epic for the broader goal the ticket serves. If the ticket is a Subtask, + also read the parent Story. +2. **Confirm the repo.** Check the Component field + (`customfield_10041`) — see the `choose-repo` skill if it's unset or looks + wrong. +3. **Check for blocking dependencies.** Look for: + - JIRA issue links (`blocks` / `is blocked by`). + - Prior tickets in the same Epic that this one is stacked on (common in + this org — see the branch-naming note below). + - An open PR from a dependency ticket that hasn't merged yet. If your + ticket depends on unmerged work, branch off that PR's branch, not off + the default branch (stacked branches) — note this explicitly in your PR + description ("Depends on #NN"). +4. **Transition the ticket to In Progress** and **comment that you're + starting work**, including which branch/worktree you're using. This is + the signal to other contributors (and other agents working the same + Epic) that the ticket is claimed. +5. **Determine the branch name**: `///` + (see `CLAUDE.md` / `AGENTS.md` for the full convention and type values). + If stacking on a dependency branch, branch from that branch's tip, not + from the default branch. +6. **Create the worktree** for the branch (see `setup-dev-env` and + `contribution-guide` for the mechanics) and only then start implementing. + +## Do not + +- Do not start writing code before the ticket is transitioned to In Progress + — this org relies on that state to avoid duplicate work across agents. +- Do not assume no dependency exists just because the ticket doesn't + explicitly say so — check the Epic for sibling tickets that touch the same + files or same directory, especially when multiple agents work an Epic + concurrently. +- Do not rename the ticket or reinterpret its scope from your own reading of + the description — if the described work seems off, comment and ask rather + than silently redefining it.