Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .agents/skills/async-state-safety/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
name: async-state-safety
description: This skill should be used when the user asks to change "worker lifecycle", "cancellation", "retrigger behavior", "state machine", "delivery receipts", "timeouts", or "race conditions". Enforces explicit async/state invariants and targeted race-safe verification.
---

# Async State Safety

## Goal

Prevent race regressions in async and stateful paths.

## Required Invariants

- Define valid terminal states before coding.
- Define allowed state transitions before coding.
- Keep terminal transitions idempotent.
- Ensure duplicate events cannot double-apply terminal effects.
- Ensure retries do not corrupt state.

## Race Checklist

- Cancellation racing completion
- Timeout racing completion
- Retry racing ack/receipt update
- Concurrent updates to the same worker/channel record
- Missing-handle and stale-handle behavior

## Implementation Checklist

- Add or update transition guards.
- Keep error handling explicit and structured.
- Preserve status/event emission on all terminal branches.
- Document why each race path converges safely.

## Verification Checklist

- Run targeted tests for each touched race path.
- Add at least one negative-path test for terminal convergence.
- Add at least one idempotency test where applicable.
- Run broad gate checks after targeted checks pass.

## Handoff Requirements

- Terminal states and transition matrix
- Race windows analyzed
- Targeted commands and outcomes
- Residual risks and follow-up tests
40 changes: 40 additions & 0 deletions .agents/skills/messaging-adapter-parity/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
name: messaging-adapter-parity
description: This skill should be used when the user asks to change "Slack adapter", "Telegram adapter", "Discord adapter", "Webhook adapter", "status delivery", "message routing", or "delivery receipts". Enforces cross-adapter parity and explicit delivery semantics.
---

# Messaging Adapter Parity

## Goal

Prevent adapter-specific regressions by validating behavior contracts across messaging backends.

## Contract Areas

- User-visible reply behavior
- Status update behavior (`surfaced` vs `not surfaced`)
- Delivery receipt ack/failure semantics
- Retry behavior and bounded backoff
- Error mapping and logging clarity

## Parity Checklist

- For every changed adapter path, compare expected behavior with at least one other adapter.
- If an adapter intentionally does not surface a status, ensure receipt handling still converges correctly.
- Ensure unsupported features degrade gracefully and predictably.
- Ensure worker terminal notices cannot loop indefinitely.

## Verification Checklist

- Run targeted tests for the touched adapter.
- Run targeted tests for receipt ack/failure paths.
- Run at least one parity comparison check across adapters.
- Run broad gate checks after targeted checks pass.

## Required Handoff

- Adapter paths changed
- Contract decisions made
- Receipt behavior outcomes
- Verification evidence
- Residual parity gaps
44 changes: 44 additions & 0 deletions .agents/skills/pr-gates/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
name: pr-gates
description: This skill should be used when the user asks to "open a PR", "prepare for review", "address review comments", "run gates", or "verify before pushing" in this repository. Enforces preflight/gate workflow, migration safety, and review-evidence closure.
---

# PR Gates

## Mandatory Flow

1. Run `just preflight` before finalizing changes.
2. Run `just gate-pr` before pushing or updating a PR.
3. If the same command fails twice in one session, stop rerunning and switch to root-cause debugging.
4. Do not push when any gate is red.

## Review Feedback Closure

For every P1/P2 review finding, include all three:

- Code change reference (file path and concise rationale)
- Targeted verification command
- Pass/fail evidence from that command

## Async And Stateful Changes

When touching worker lifecycle, cancellation, retries, state transitions, or caches:

- Document terminal states and allowed transitions.
- Explicitly reason about race windows and idempotency.
- Run targeted tests in addition to broad gate runs.
- Capture the exact command proving the behavior.

## Migration Safety

- Never edit an existing file in `migrations/`.
- Add a new timestamped migration for every schema change.
- If a gate flags migration edits, stop and create a new migration file.

## Handoff Format

- Summary
- Changed files
- Gate commands executed
- P1/P2 finding-to-evidence mapping
- Residual risk
55 changes: 55 additions & 0 deletions .agents/skills/pr-slicer/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
name: pr-slicer
description: This skill should be used when the user asks to "split this PR", "make this smaller", "create stacked PRs", "slice this change", or "reduce review churn". Helps break work into low-risk, reviewable slices with clear verification per slice.
---

# PR Slicer

## Goal

Reduce review latency and rework by shipping smaller, independent slices.

## Default Slice Budgets

- Target `<= 400` changed lines per slice when practical.
- Target `<= 10` changed files per slice when practical.
- Target `1-4` commits per slice.
- Keep each slice behaviorally coherent and independently verifiable.

## Slicing Order

1. Extract prerequisites first.
2. Land mechanical refactors next.
3. Land behavior changes after prerequisites are merged.
4. Land UI/docs/polish last.

## Slice Packet Template

For each slice, define:

- `Goal`
- `Owned files`
- `Out of scope`
- `Risk level` (`low`/`medium`/`high`)
- `Verification command(s)` with expected pass condition
- `Rollback plan`

## Hard Rules

- Avoid mixing refactor and behavior changes in one slice unless unavoidable.
- Avoid touching unrelated subsystems in one slice.
- Avoid cross-slice hidden dependencies.
- If a slice depends on unmerged work, state it explicitly.

## Verification Discipline

- Run narrow checks first for touched behavior.
- Run project gate checks before handoff.
- Record exact commands and outcomes for each slice.

## Final Handoff Format

- Slice list with order and purpose
- Per-slice owned files
- Per-slice verification evidence
- Residual risk and follow-up slices
41 changes: 41 additions & 0 deletions .agents/skills/provider-integration-checklist/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
name: provider-integration-checklist
description: This skill should be used when the user asks to add or modify an "LLM provider", "model routing", "OAuth flow", "auth token handling", "provider config", or "fallback chain". Enforces provider integration completeness across config, routing, docs, and verification.
---

# Provider Integration Checklist

## Goal

Ship provider and routing changes without regressions in auth, config, and model selection.

## Change Checklist

- Add config keys and defaults in one place.
- Validate config resolution order (`env > DB > default` where applicable).
- Validate model identifier parsing and normalization.
- Validate routing defaults, task overrides, and fallback chains.
- Validate auth flow behavior for both success and failure paths.
- Validate token/secret handling and redaction behavior.

## Compatibility Checklist

- Keep existing providers unaffected.
- Keep unknown-provider errors actionable.
- Keep provider-specific errors distinguishable.
- Keep docs and examples aligned with actual config keys.

## Verification Checklist

- Narrow tests for changed provider/routing/auth paths.
- Negative-path tests for invalid config and auth failures.
- Smoke path proving model call routes to expected backend.
- Broad gate checks after targeted checks pass.

## Required Handoff

- Config keys changed
- Routing behavior changed
- Auth behavior changed
- Verification evidence
- Docs updated
56 changes: 56 additions & 0 deletions .agents/skills/release-bump-changelog/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
name: release-bump-changelog
description: Use this skill when preparing a release bump or updating release notes. It writes a launch-style release story from the actual change set, then runs `cargo bump` so the generated GitHub notes and the marketing copy land together in `CHANGELOG.md`.
---

# Release Bump + Changelog

## Goal

Create a version bump commit where each release section includes both:

- a launch-style narrative (marketing copy)
- the exact GitHub-generated release notes

## Workflow

1. Ensure the working tree is clean (except allowed release files).
2. Draft release story markdown from real changes (PR titles, release-note bullets, and diff themes).
- Target style: similar to the `v0.2.0` narrative (clear positioning + concrete highlights).
- Keep it factual and specific to the release.
- Write to a temp file (outside repo is preferred):
- `marketing_file="$(mktemp)"`
- write markdown content to `$marketing_file`
3. Run `cargo bump <patch|minor|major|X.Y.Z>` with marketing copy input:
- `SPACEBOT_RELEASE_MARKETING_COPY_FILE="$marketing_file" cargo bump <...>`
- This invokes `scripts/release-tag.sh`.
- The script generates GitHub-native notes (`gh api .../releases/generate-notes`).
- The script upserts `CHANGELOG.md` with:
- `### Release Story` (from your marketing file)
- GitHub-generated notes body
- The script includes `CHANGELOG.md` in the release commit.
4. Verify results:
- `git show --name-only --stat`
- Confirm commit contains `Cargo.toml`, `Cargo.lock` (if present), and `CHANGELOG.md`.
- Confirm tag was created (`git tag --list "v*" --sort=-v:refname | head -n 5`).

## Requirements

- `gh` CLI installed and authenticated (`gh auth status`).
- `origin` remote points to GitHub, or set `SPACEBOT_RELEASE_REPO=<owner/repo>`.
- Marketing copy is required unless explicitly bypassed with `SPACEBOT_SKIP_MARKETING_COPY=1`.

## Release Story Format

Use markdown only (no outer `## vX.Y.Z` heading; script adds it). Recommended structure:

1. One strong opening paragraph (why this release matters)
2. One paragraph on major technical shifts
3. Optional short highlight bullets for standout additions/fixes

Avoid vague hype. Tie claims to concrete shipped changes.

## Notes

- Do not use a standalone changelog sync script.
- `CHANGELOG.md` is seeded from historical releases and then maintained by the release bump workflow.
47 changes: 47 additions & 0 deletions .agents/skills/review-fix-loop/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
name: review-fix-loop
description: This skill should be used when the user asks to "address review feedback", "fix PR comments", "close findings", "respond to reviewer notes", or "reduce review churn". Enforces a finding-to-evidence closure loop for every review round.
---

# Review Fix Loop

## Goal

Close review rounds with minimal back-and-forth by mapping every finding to a code change and proof.

## Execution Loop

1. Parse findings into `P1`, `P2`, `P3`.
2. Build a closure table before editing.
3. Implement the smallest coherent fix batch.
4. Run targeted verification.
5. Update closure table with outcomes.
6. Run broader gate checks.

## Closure Table

Use one row per finding:

| Finding | Severity | Owned files | Planned change | Verification command | Result |
|---|---|---|---|---|---|

## Re-Run Control

- If the same command fails twice, stop rerunning.
- Isolate a smaller reproduction command.
- Patch the smallest likely cause.
- Re-run narrow verification before broad checks.

## Verification Ladder

- Start narrow: unit/module behavior checks for touched paths.
- Continue medium: compile/lint/type checks for touched surfaces.
- End broad: repository gate commands.

## Handoff Requirements

- Findings closed
- Commands executed
- Pass/fail evidence per finding
- Remaining open findings with rationale
- Residual risk
19 changes: 17 additions & 2 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,25 @@ interface/node_modules/
interface/dist/

# Not needed for the build
docs/
tests/
scripts/

# Exclude docs except what's needed for self_awareness.rs embeds
docs/node_modules/
docs/.next/
docs/out/
docs/app/
docs/components/
docs/lib/
docs/design-docs/
docs/*.json
docs/*.ts
docs/*.tsx
docs/*.mjs
docs/*.yaml
docs/*.lock
docs/.gitignore
docs/.node-version
fly.toml
AGENTS.md
RUST_STYLE_GUIDE.md
LICENSE
Loading