Merge pull request #1 from spacedriveapp/main

update

Author: GoetschiM

.agents/skills/async-state-safety/SKILL.md

@@ -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

.agents/skills/commit-all/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: commit-all
+description: Use this skill when the user asks to "commit all", "commit everything", or wants all outstanding changes committed. Groups unrelated changes into separate, well-described commits instead of one catch-all commit.
+---
+
+# Commit All
+
+## Goal
+
+Commit every outstanding change in the working tree — but group unrelated changes into separate, informative commits so the git history stays useful.
+
+## Workflow
+
+1. **Survey all changes.** Run `git status` and `git diff` (staged + unstaged) to see the full picture. Include untracked files.
+2. **Identify logical groups.** Cluster files by the change they belong to. A "group" is a set of files that were modified for the same reason (e.g. a bug fix, a new feature, a config tweak, a dependency update). Use file paths, diff content, and your understanding of the codebase to decide.
+3. **Order commits.** Infra/config/dependency changes first, then library/core changes, then feature/UI changes, then docs/polish.
+4. **For each group, create one commit:**
+   - Stage only the files belonging to that group (`git add <file> ...`). Never use `git add -A` or `git add .`.
+   - Write a concise, informative commit message that describes *what* changed and *why*. Follow the repo's existing commit style (check `git log --oneline -10`).
+   - Do not lump unrelated changes together just because they're small.
+5. **Verify.** After all commits, run `git status` to confirm the tree is clean. Run `git log --oneline -n <N>` (where N = number of commits created) to show the user what was committed.
+
+## Commit Message Rules
+
+- Keep the subject line under 72 characters.
+- Use imperative mood ("add", "fix", "update", not "added", "fixes").
+- If a change is trivial (whitespace, typo, formatting), it's fine to batch those into one commit labeled accordingly.
+- End every commit message with the Co-Authored-By trailer.
+
+## Hard Rules
+
+- Never combine unrelated changes in one commit.
+- Never skip or discard changes — everything gets committed.
+- Never use `git add -A` or `git add .`.
+- Do not push. Only commit locally.
+- Do not commit files that look like they contain secrets (`.env`, credentials, tokens). Warn the user about those instead.

.agents/skills/messaging-adapter-parity/SKILL.md

@@ -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

.agents/skills/pr-gates/SKILL.md

@@ -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

.agents/skills/pr-slicer/SKILL.md

@@ -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