oibot/agent-skills
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

feat: add tokenless Tobserver change skill

Browse source
This commit is contained in:
Tobias Ostner 2026-07-24 20:22:01 +07:00
parent 8cc510b2c7
commit 886a885355
6 changed files with 1364 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

95
tobserver-change/SKILL.md Normal file
View file

@ -0,0 +1,95 @@
---
name: tobserver-change
description: >-
Safely prepares and revises reviewed Codeberg pull requests for declarative
NixOS changes to the canonical oibot/Tobserver repository. Use this skill
whenever the user asks to change, configure, update, fix, inspect, or prepare
a deployment-related Tobserver change, address feedback on a Tobserver PR, or
mentions its NixOS configuration, services, packages, or secrets wiring. Do
not use for live-server access, deployment, or unrelated NixOS repositories.
license: MIT
compatibility: Requires Bash, Git, OpenSSH, curl, jq, Nix, nixpkgs-fmt, Gitleaks, a personal oibot Codeberg SSH key, and protected main that forbids direct pushes.
metadata:
short-description: Prepare reviewed Tobserver NixOS changes
---
# Tobserver Change
Use the trusted `tobserver-agent` command, packaged from [`scripts/tobserver-agent`](scripts/tobserver-agent), to create isolated workspaces, run policy checks, and submit tokenless Forgejo AGit pull requests. The protected repository and human web merge are the approval boundary; the live server is outside the agent's reach.
## Required setup
- Before first use or after an authentication/policy failure, read [`references/setup.md`](references/setup.md). It defines the required Codeberg branch protection, personal SSH identity, installation, verification, and bot-retirement sequence.
- Work only in a workspace created or validated by `tobserver-agent`.
- Use only `https://codeberg.org/oibot/Tobserver.git` for fetches and `ssh://git@codeberg.org/oibot/Tobserver.git` for AGit submission.
- Never use a Codeberg API token, authenticated browser session, raw push command, or pull-request write API. The helper uses SSH AGit and public read-only API requests.
## Non-negotiable boundary
- Keep work on local `agent/*` branches and helper-managed `tobserver-agent-*` AGit topics.
- Never push to, force-push, delete, or merge `main` or any remote branch.
- Never approve or merge the pull request; the user does that in Codeberg's web UI.
- Never SSH to Tobserver, copy files to it, run remote commands, deploy, or run `nixos-rebuild` against it.
- Never request or use the server's SOPS age private key, decrypt SOPS files, expose plaintext secrets, or modify encrypted payloads.
- Never bypass a failed helper check. Preserve failed or interrupted workspaces for recovery.
If the helper is unavailable, the setup is unconfirmed, or the workspace is rejected, stop and report the missing prerequisite. Do not reproduce its privileged behavior ad hoc.
## 1. Establish the workspace
Run `tobserver-agent status`. If no valid active workspace exists:
- New change: `tobserver-agent start "<short task description>"`
- Existing PR correction: `tobserver-agent revise <PR_NUMBER>`
- Explicit interrupted work: `tobserver-agent resume /tmp/tobserver-agent.XXXXXX`
For revisions, accept only an open AGit PR in `oibot/Tobserver` targeting `main`, opened by `oibot`, with a helper-managed topic and `refs/pull/<number>/head`. Inspect the PR, discussion, diff, relevant modules, flake outputs, and recent commits before editing.
Respect “plan only” or “do not push.” Investigate without submission; create a workspace only when useful and preserve it.
## 2. Make the smallest declarative change
1. Explain the files and behavior to change, safe macOS checks, and human-only follow-up.
2. Prefer focused changes to existing modules. Avoid unrelated refactors and `flake.lock` churn.
3. Separate secret wiring from human secret provisioning. Do not edit `secrets/` or `.sops.yaml`.
4. Do not run Linux builds, deployment tools, or commands that instantiate and execute a Tobserver system closure.
## 3. Check and review
Run `tobserver-agent check`. It enforces Nix formatting, Git whitespace, `nix flake check --no-build`, Tobserver derivation evaluation, secret-path policy, and Gitleaks.
Fix relevant failures and rerun. If a platform or external constraint blocks a check, report the exact failure and workspace path; do not submit.
Inspect the final diff for credentials, decrypted values, private keys, unrelated edits, generated result links, and accidental lock-file changes.
## 4. Submit for human review
Before submission, read and instantiate [`assets/pull-request-body.md`](assets/pull-request-body.md). Report the workspace, branch/topic, diff summary, checks, risks, and manual steps.
Unless the user explicitly requested no submission, run:
```sh
tobserver-agent submit --title "<concise commit title>" --body-file <body-file>
```
The helper commits the change, pushes only to `refs/for/main/<topic>`, creates or linearly updates one PR, verifies its public metadata, and cleans the workspace only after success.
Report the PR URL and ask the user to review and merge it in Codeberg. Deployment remains manual after merge.
## Recovery
- Preserve workspaces after failed checks, interrupted work, ambiguous behavior, or failed submission.
- Resume with `tobserver-agent resume <workspace>`.
- Run `tobserver-agent cleanup <workspace>` only when the user explicitly requests cleanup after understanding unsubmitted work will be deleted.
## Maintenance
When changing the bundled helper, run:
```sh
bash -n scripts/tobserver-agent
scripts/tobserver-agent --help
tests/tobserver-agent-test
```
Then run one representative safe workspace check without submitting or accessing the live server.