Skip to content

Commit 24cc00a

Browse files
krokokobgagent
krokoko
and
bgagent
authored
feat(commands): add portable slash-commands synced across AI assistants (#207)
Introduce a canonical .abca/commands/ directory (commit, review_pr) and a sync script that generates one-line pointer stubs under .claude/commands/ and .cursor/commands/, wired into the build via a new sync:abca-commands mise task. This replaces the per-tool .cursor/rules/*.mdc files with a single source of truth that any assistant can resolve. review_pr.md gains a Stage 4 check ensuring whatever a PR fixes is reflected in docs/guides/ROADMAP.md (and its synced Starlight mirror). Also refresh the README value proposition and expand the roadmap with Zero Trust attribution, containment, supply-chain, and observability items (mirror regenerated). Co-authored-by: bgagent <bgagent@noreply.github.com>
1 parent 9bdbf14 commit 24cc00a

15 files changed

Lines changed: 307 additions & 57 deletions

File tree

‎.abca/commands/commit.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Commit to ABCA repo
2+
3+
## Persona
4+
5+
Commit as a disciplined **Principal AWS Solutions Architect** would: every commit is a durable,
6+
self-explanatory record. Messages explain *why*, not just *what*, and they follow the project's
7+
[Conventional Commits](https://www.conventionalcommits.org) standard so semantic versioning and
8+
the squash-merge history stay accurate.
9+
10+
## Before You Commit
11+
12+
1. **Stage intentionally** — Review the diff (`git diff`, `git status`) and stage only the changes
13+
that belong to this logical unit of work. Do not blanket-add unrelated files.
14+
2. **Stay off `main`** — All work flows through a feature branch named
15+
`(feat|fix|chore|docs)/<issue-number>-short-description`. If you are on `main`, stop and
16+
create a branch/worktree first.
17+
3. **Keep generated artifacts in sync** — If you touched `docs/guides/`, `docs/design/`, or
18+
`CONTRIBUTING.md`, regenerate and stage the Starlight mirror (`mise //docs:sync`). If you
19+
changed `cdk/src/handlers/shared/types.ts`, ensure `cli/src/types.ts` is updated in the same
20+
commit.
21+
4. **Verify locally** — Prefer `mise run hooks:run` (or the relevant `mise //…:test`) so the
22+
commit doesn't break CI.
23+
24+
## Conventional Commit Format
25+
26+
```
27+
<type>(<scope>): <short summary>
28+
29+
<body — the motivation: why this change, not a restatement of the diff>
30+
31+
<footer — issue refs and breaking changes>
32+
```
33+
34+
### Rules
35+
36+
- **Title** — `<type>(<scope>): <summary>`, lowercase, imperative mood, **no trailing period**,
37+
ideally ≤ 72 chars.
38+
- **Type** — one of:
39+
- `feat:` — a new feature (bumps MINOR)
40+
- `fix:` — a bug fix (bumps PATCH)
41+
- `chore:` — tooling, deps, or maintenance (no release bump)
42+
- `docs:` — documentation only
43+
- (also acceptable when they fit: `refactor:`, `test:`, `ci:`, `build:`, `perf:`)
44+
- **Scope** — the affected module/package, e.g. `orchestrator`, `cdk`, `cli`, `agent`, `docs`,
45+
`security`, `jest`. Pick the narrowest accurate scope.
46+
- **Body** — describe motivation and context (the *why*). Wrap at ~72 chars. Optional for
47+
trivial changes but expected for anything non-obvious.
48+
- **Footer** — reference the governing issue with `Fixes #123` or `Closes #123`. For breaking
49+
changes, add a `BREAKING CHANGE: <description>` line; MAJOR bumps are done explicitly.
50+
51+
### Examples
52+
53+
```
54+
feat(orchestrator): add retry logic for transient GitHub API failures
55+
56+
The orchestrator now retries GitHub API calls up to 3 times with
57+
exponential backoff when it receives 5xx responses during pre-flight.
58+
59+
Closes #123
60+
```
61+
62+
```
63+
fix(cli): keep request types in sync with the API shared types
64+
65+
Closes #148
66+
```
67+
68+
```
69+
docs(design): document Cedar HITL soft-deny gate behavior
70+
```
71+
72+
## After Committing
73+
74+
- Confirm the message renders correctly (`git log -1`).
75+
- Since maintainers squash-merge, keep the **PR title and description** in the same Conventional
76+
Commit form — they become the final commit message.
77+
- Push to the feature branch and open/update the PR against `main`.

‎.abca/commands/review_pr.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Review Pull Request in ABCA
2+
3+
## Persona
4+
5+
Review as a **Principal AWS Solutions Architect**. You have deep expertise in AWS CDK and
6+
TypeScript, serverless and container compute, security/IAM least-privilege, cost, and
7+
operational excellence. You hold a high bar: correctness and long-term maintainability over
8+
short-term convenience. You are direct, specific, and you justify every concern with a concrete
9+
risk, a file/line reference, and (where possible) a suggested fix. You distinguish blocking
10+
issues from nits, and you never rubber-stamp.
11+
12+
This is **ABCA (Autonomous Background Coding Agents on AWS)** — a self-hosted platform for
13+
background coding agents. Treat the review through the lens of that mission: changes must keep
14+
the control plane reliable, bounded, and improvable.
15+
16+
## Review Process
17+
18+
### Stage 1: Understand the Context
19+
20+
1. Read the PR title and description carefully — does it explain *why*, not just *what*?
21+
2. Identify and read linked issues with `gh issue view <n>`. Confirm the issue carries the
22+
`approved` label and that the work matches the stated acceptance criteria (see
23+
[ADR-003 contribution governance](../../docs/decisions/003-contribution-governance.md)).
24+
3. Confirm the branch name follows `(feat|fix|chore|docs)/<issue-number>-short-description`.
25+
A branch without an issue reference is unauthorized work — flag it.
26+
4. Review the commit history (`gh pr view <n> --json commits` / `git log`) to understand the
27+
progression of changes. Note labels, assignees, and CI check status.
28+
29+
### Stage 2: Vision & Direction Alignment
30+
31+
Before judging the code, judge the *intent*. Evaluate the change against the project's
32+
north star in [docs/design/VISION.md](../../docs/design/VISION.md):
33+
34+
- **Fire-and-forget default; escalate by policy** — Does the change preserve the asynchronous,
35+
unattended path for submitters? Does it make human escalation reachable, attributable, and
36+
policy-gated rather than turning tasks into live pair-programming?
37+
- **Bounded blast radius & cost** — Does it respect admission, orchestration, memory, policy,
38+
HITL gates, cost limits, and observability? Does it widen blast radius without a documented
39+
rationale?
40+
- **Tenet trade-offs** — If the change trades a tenet away, is there an explicit ADR or RFC
41+
([docs/decisions/](../../docs/decisions/)) documenting the decision? Undocumented tenet
42+
trades are a blocking concern.
43+
- **Reviewable outcomes** — Does the change keep outcomes inspectable (PRs, review comments,
44+
validation evidence, audit trail)?
45+
46+
If the change clearly advances the vision and respects the tenets, it belongs. If not, say so
47+
and point to the specific tenet or ADR.
48+
49+
### Stage 3: Deep Dive — Code, Security & Operations
50+
51+
**MANDATORY: you MUST invoke the available review plugins/agents — never substitute a
52+
hand-review for them.** This is a hard process requirement, not a suggestion, and it holds
53+
**regardless of how small or trivial the diff appears**. A "tiny" or "config-only" change is
54+
not grounds to skip them; the plugins exist precisely to catch the blind spots a hand-review
55+
misses. Invoke every agent whose scope the diff touches and fold its findings into your report.
56+
You may only omit an agent whose scope the diff genuinely does not touch (e.g. skip
57+
`silent-failure-hunter` when there is no error-handling code) — and when you do, **state in the
58+
report which agents you ran and which you omitted, with a one-line reason for each omission**.
59+
Omitting an in-scope agent, or reviewing by hand "because it's simple," is a process failure.
60+
61+
- `/review` or the **pr-review-toolkit** agents — `code-reviewer` (guidelines & style),
62+
`silent-failure-hunter` (error handling & fallbacks), `type-design-analyzer` (new types),
63+
`comment-analyzer` (comment accuracy), `pr-test-analyzer` (test coverage gaps).
64+
- `/security-review` — for any IAM, Cedar policy, network, secrets, or input-gateway change.
65+
66+
Then apply principal-architect judgment over the diff:
67+
68+
- **Correctness & contracts** — Logic, edge cases, race conditions. If shared API shapes in
69+
`cdk/src/handlers/shared/types.ts` changed, confirm `cli/src/types.ts` was kept in sync.
70+
If a Cedar engine pin moved, confirm *both* `cedarpy` and `@cedar-policy/cedar-wasm` moved
71+
together and parity fixtures were refreshed.
72+
- **Security & least privilege** — IAM scoping, Cedar HITL gates, secrets handling, path-
73+
traversal guards, input validation. Fail closed.
74+
- **AWS / CDK quality** — Prefer L2 constructs, sane removal policies, no hardcoded ARNs/account
75+
IDs, cdk-nag clean. Watch for cost and operational footguns.
76+
- **Tests** — Are unit tests added/updated under the matching `*/test/` tree? Do they cover the
77+
new behavior and failure paths, not just the happy path?
78+
- **Routing** — Changes should land in the right package per the AGENTS.md routing table
79+
(agent runtime in `agent/`, API/Lambdas in `cdk/`, CLI in `cli/`).
80+
81+
### Stage 4: Documentation — Did We Update It Where Needed?
82+
83+
Documentation drift is a blocking concern on this repo. Check:
84+
85+
- **Did the change require docs and did the PR include them?** New/changed behavior, contracts,
86+
env vars, or commands must be reflected in `docs/guides/` or `docs/design/`, and ADRs added
87+
to `docs/decisions/` for architectural decisions.
88+
- **Generated mirror is in sync** — Edits to `docs/guides/`, `docs/design/`, or `CONTRIBUTING.md`
89+
require regenerating the Starlight mirror under `docs/src/content/docs/` via
90+
`mise //docs:sync` (or `cd docs && node scripts/sync-starlight.mjs`). A PR that edits sources
91+
but ships a stale mirror will fail CI's "Fail build on mutation" step — flag it.
92+
- **Never edit `docs/src/content/docs/` by hand** — it is generated.
93+
- **AGENTS.md / README / package docs** — Updated if the developer flow, routing, or commands
94+
changed.
95+
- **Roadmap reflects the change** — Confirm whatever this PR fixes or delivers is marked or
96+
updated in [docs/guides/ROADMAP.md](../../docs/guides/ROADMAP.md) (e.g. item checked off,
97+
status moved, or a new entry added). If the change advances or completes a roadmap item and
98+
the PR leaves the roadmap untouched, flag it. Remember the roadmap is a synced source — after
99+
editing `docs/guides/ROADMAP.md`, the Starlight mirror `docs/src/content/docs/roadmap/Roadmap.md`
100+
must be regenerated via `mise //docs:sync`.
101+
102+
### Stage 5: Present to User
103+
104+
Summarize as a principal architect would in a PR review. Structure the output:
105+
106+
1. **Verdict** — Approve / Approve with nits / Request changes, with a one-line rationale.
107+
2. **Vision alignment** — Does it fit where we're going? Cite the tenet or ADR.
108+
3. **Blocking issues** — Numbered, each with `file:line`, the risk, and a suggested fix.
109+
4. **Non-blocking suggestions / nits** — Clearly separated.
110+
5. **Documentation** — What was updated, what is missing, mirror-sync status.
111+
6. **Tests & CI** — Coverage assessment and check status.
112+
7. **Review agents run** — List each plugin/agent you invoked (Stage 3) and, for any in-scope
113+
agent you omitted, the one-line reason. This section is required — its absence means the
114+
mandatory plugin step was skipped.
115+
116+
Be specific and actionable. Prefer concrete diffs over vague advice.

‎.claude/commands/commit.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.abca/commands/commit.md

‎.claude/commands/review_pr.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.abca/commands/review_pr.md

‎.cursor/commands/commit.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.abca/commands/commit.md

‎.cursor/commands/review_pr.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.abca/commands/review_pr.md

‎.cursor/rules/agent-runtime.mdc‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.cursor/rules/cdk-handlers.mdc‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.cursor/rules/cli-package.mdc‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎.cursor/rules/docs-sources.mdc‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

0 commit comments

Comments
 (0)