docs: add awa agent skills#447
Conversation
Add two portable Agent Skills so coding agents work from awa's actual API and operational semantics: - awa-jobs: authoring, enqueuing, and handling jobs in Rust and Python (job kinds, transactional enqueue, retry vs snooze, cron, callbacks, progress and lifecycle hooks). - awa-operations: deploying and operating the fleet (migrations, rolling upgrades, storage transitions, DLQ, managed Postgres, web admin UI). Validate every skill against the Agent Skills specification in CI, bundle skills into the release binary archives, and document them in the README. Add an AGENTS.md with the always-on build/lint/test rules, the migration policy pointer, and skill-authoring governance.
|
Warning Review limit reached
Next review available in: 36 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds ChangesAgent Skills
Estimated code review effort: 3 (Moderate) | ~20 minutes Suggested labels: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d3a1c1c124
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/ci.yml:
- Around line 43-46: Add a job-level permissions block to the agent-skills job,
granting only contents: read. Keep the existing Agent Skills validation
configuration unchanged.
- Around line 48-49: Update the actions/checkout step in the CI workflow to set
persist-credentials to false, ensuring the checkout token is not retained for
subsequent validator commands; leave the setup-uv step unchanged.
In `@skills/awa-jobs/SKILL.md`:
- Around line 104-106: Format the transactional enqueue example in the
documentation as a fenced Python code block, keeping only the async with and
tx.insert statements inside the fence. Place the explanatory “Or use
awa.bridge.insert_job...” prose outside the code block.
- Around line 150-153: Update the ReportArgs construction in the PeriodicJob
example to use valid Rust struct syntax: provide each required field explicitly
or use ReportArgs::default() as the struct-update base if that constructor is
supported. Keep the existing nightly-report job configuration unchanged.
In `@skills/awa-operations/SKILL.md`:
- Line 5: Update the compatibility frontmatter in SKILL.md to distinguish
fleet-dependent /readyz health checks from database-only commands such as awa
health and storage status. Remove the implication that all health workflows
require a live worker fleet, while preserving the existing PostgreSQL and
deployed awa CLI requirements.
- Around line 23-29: Update the CLI production-resolution and mutating-command
authorization flow described in this documentation so an explicit --database-url
cannot bypass production safeguards: identify production direct URLs using the
same production classification as named contexts, require the existing explicit
acknowledgement/--yes behavior and reject non-interactive execution without it,
then update this section to document the enforced behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c4df76f8-0449-4420-a0a3-bcc707e99175
📒 Files selected for processing (6)
.github/workflows/ci.yml.github/workflows/release.ymlAGENTS.mdREADME.mdskills/awa-jobs/SKILL.mdskills/awa-operations/SKILL.md
| Read-only commands may fall back to `DATABASE_URL` or the default context. | ||
| Mutating commands refuse to run against an implicit target whenever more than | ||
| one context is defined — pass an explicit `--context` or `--database-url`. A | ||
| context marked `production = true` prompts for confirmation on a mutating | ||
| command; `--yes` skips the prompt, and a non-interactive shell without `--yes` | ||
| refuses rather than hanging. An explicit `--database-url` is never treated as | ||
| production. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^skills/awa-operations/SKILL.md$|AGENTS.md$|skills-ref|pyproject|requirements|uv.lock)' || true
echo "== skill excerpt =="
sed -n '1,80p' skills/awa-operations/SKILL.md 2>/ Dev/null || true
echo "== AGENTS snippets =="
if [ -f AGENTS.md ]; then sed -n '1,220p' AGENTS.md; fi
echo "== search production/database-url flags/implementation =="
rg -n --hidden --glob '!*.lock' "production|production confirmation|confirmation|database-url|--database-url|DATABASE_URL|DATABASE" .Repository: hardbyte/awa
Length of output: 50370
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== skill full relevant excerpt =="
python3 - <<'PY'
from pathlib import Path
p = Path("skills/awa-operations/SKILL.md")
text = p.read_text(errors="replace")
print(text[:4000])
print("---- line numbers 20-32 ----")
for i, line in enumerate(text.splitlines(), 1):
if 20 <= i <= 32:
print(f"{i}: {line}")
PY
echo "== context implementation relevant sections =="
python3 - <<'PY'
from pathlib import Path
p = Path("awa-cli/src/context.rs")
text = p.read_text(errors="replace")
for start,end in [(1,125),(170,240),(470,530)]:
print(f"---- {start}-{end} ----")
for i,line in enumerate(text.splitlines(),1):
if start <= i <= end:
print(f"{i}: {line}")
PY
echo "== main implementation relevant sections =="
python3 - <<'PY'
from pathlib import Path
p = Path("awa-cli/src/main.rs")
text = p.read_text(errors="replace")
for start,end in [(305,350),(845,915)]:
print(f"---- {start}-{end} ----")
for i,line in enumerate(text.splitlines(),1):
if start <= i <= end:
print(f"{i}: {line}")
PY
echo "== context test relevant sections =="
python3 - <<'PY'
from pathlib import Path
p = Path("awa-cli/tests/context_cli_test.rs")
text = p.read_text(errors="replace")
for start,end in [(1,230),(570,700)]:
print(f"T---- {start}-{end} ----")
for i,line in enumerate(text.splitlines(),1):
if start <= i <= end:
print(f"T{i}: {line}")
PYRepository: hardbyte/awa
Length of output: 27823
Do not make explicit database URLs a production-safety bypass.
Both the documented production gate and the CLI implementation treat --database-url as non-production, so changing awa --database-url <production-dsn> migrate or a mutating command can bypass the production = true confirmation required for named production contexts. Require an explicit acknowledgement for direct production URLs and update the CLI production-resolution/pathing to enforce it.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/awa-operations/SKILL.md` around lines 23 - 29, Update the CLI
production-resolution and mutating-command authorization flow described in this
documentation so an explicit --database-url cannot bypass production safeguards:
identify production direct URLs using the same production classification as
named contexts, require the existing explicit acknowledgement/--yes behavior and
reject non-interactive execution without it, then update this section to
document the enforced behavior.
- awa-jobs: deriving JobArgs needs only the `awa` facade (it re-exports the trait and macro); drop the incorrect `awa-model` requirement and use `use awa::JobArgs`. - awa-jobs: correct unique-insert behaviour — single-row insert/insert_with and row-by-row insert_many raise UniqueConflict; only insert_many_copy skips silently. - awa-jobs: carve out on_rescued_enqueue — maintenance rescue follow-ups are best-effort (commit-then-dispatch), not atomic like worker/callback outcomes. - awa-jobs: fix the non-compiling periodic-job example; fence the Python transactional-enqueue example. - Narrow skill `compatibility` to the awa 0.7 API and instruct pinning to the matching release tag; document per-persona, tag-pinned installation in the README (repo + CLI release archive). Keep skills out of crates/wheels/images with rationale in AGENTS.md. - CI: give the agent-skills job `contents: read` and set `persist-credentials: false` on checkout. - awa-operations: clarify which workflows need a live fleet vs the database.
coderabbitai
Bot
added
the
full-ci
The awa facade re-exports the JobArgs derive macro, so deriving needs no separate awa-model dependency — matches the awa-jobs skill fix.
1 participant
Summary
Adds two portable Agent Skills so coding agents work from awa's actual API and operational semantics instead of guessing. Split across awa's two personas:
awa-jobs— authoring, enqueuing, and handling jobs in Rust and Python: job kinds, transactional enqueue, priorities and aging, retry vs. snooze, unique jobs, cron, in-process and webhook callbacks, and progress/lifecycle hooks.awa-operations— deploying and operating the fleet: CLI reference, migrations and rolling upgrades, storage transitions, the DLQ, the maintenance/leader model, managed Postgres, and the web admin UI.Also:
agent-skillsjob validates everyskills/<name>/SKILL.mdagainst the Agent Skills specification.awa-<tag>-<target>/skills/).Design notes
SnoozenotRetryAfterfor polling waits;flip-ring-authorityis a one-way door; a long-held snapshot pins the MVCC horizon and blocks ring prune).AGENTS.md. Cross-cutting facts (cron, ring flip) are stated once and cross-referenced rather than duplicated across the two skills.Validation
uvx --from skills-ref==0.1.1 agentskills validate skills/awa-jobsuvx --from skills-ref==0.1.1 agentskills validate skills/awa-operationsSummary by CodeRabbit
Summary by CodeRabbit
New Features
awa-jobsandawa-operationsusage guidance.CI
Documentation