m3taversal
4e20986c25
- AGENT-SOP.md: enforceable checklist for commit/review/deploy cycle - auto-deploy.sh + systemd units: 2-min timer pulls from Forgejo, syncs to working dirs, restarts services only when Python changes, smoke tests - prune-branches.sh: dry-run-by-default branch cleanup tool - Delete root diagnostics/ (stale artifacts, all code moved to ops/) - Delete 7 orphaned HTML prototypes (untracked, local-only) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# Agent SOP: Ship, Review, Deploy
|
|
|
|
Load at session start. No exceptions.
|
|
|
|
## Code Changes
|
|
|
|
1. Branch from main: `git checkout -b {agent-name}/{description}`
|
|
2. Make changes. One branch per task. One concern per PR.
|
|
3. Commit with agent-name prefix, what changed and why.
|
|
4. Push to Forgejo. Open PR with deploy manifest (see deploy-manifest.md).
|
|
5. Ganymede reviews. Address feedback on same branch.
|
|
6. Merge after approval. Delete branch immediately.
|
|
7. Auto-deploy handles the rest. Do not manually deploy.
|
|
|
|
## Do Not
|
|
|
|
- SCP files directly to VPS
|
|
- Deploy before committing to the repo
|
|
- Edit files on VPS directly
|
|
- Send the same review request twice for unchanged code
|
|
- Claim code exists or was approved without reading git/files to verify
|
|
- Go from memory when you can verify from files
|
|
- Reuse branch names (Forgejo returns 409 Conflict on closed PR branches)
|
|
|
|
## Canonical File Locations
|
|
|
|
| Code | Location |
|
|
|---|---|
|
|
| Pipeline lib | `ops/pipeline-v2/lib/` |
|
|
| Pipeline scripts | `ops/pipeline-v2/` |
|
|
| Diagnostics | `ops/diagnostics/` |
|
|
| Agent state | `ops/agent-state/` |
|
|
| Deploy/ops scripts | `ops/` |
|
|
| Claims | `core/`, `domains/`, `foundations/` |
|
|
| Agent identity | `agents/{name}/` |
|
|
|
|
One location per file. If your path doesn't match this table, stop.
|
|
|
|
## Verification Before Acting
|
|
|
|
- Before editing: read the file. Never describe code from memory.
|
|
- Before reviewing: check git log for prior approvals on the same files.
|
|
- Before deploying: `git status` must show clean tree.
|
|
- Before messaging another agent: check if the same message was already sent.
|
|
|
|
## Branch Hygiene
|
|
|
|
- Delete branch immediately after merge.
|
|
- Nightly research branches: deleted after 7 days if unmerged.
|
|
- Never leave a branch open with no active work.
|
|
|
|
## Deploy
|
|
|
|
After merge to main, auto-deploy runs within 2 minutes on VPS:
|
|
1. Pulls latest main into deploy checkout
|
|
2. Syntax-checks all Python files
|
|
3. Syncs to working directories (pipeline, diagnostics, agent-state)
|
|
4. Restarts services only if Python files changed
|
|
5. Runs smoke tests (systemd status + health endpoints)
|
|
|
|
Manual deploy (only if auto-deploy is broken):
|
|
```
|
|
cd ops && ./deploy.sh --dry-run && ./deploy.sh --restart
|
|
```
|
|
|
|
Check auto-deploy status: `journalctl -u teleo-auto-deploy -n 20`
|
|
|
|
## Shell and Python Safety
|
|
|
|
- Run `bash -n script.sh` after modifying any shell script.
|
|
- Never interpolate shell variables into Python strings via `'$var'`.
|
|
Pass values via `os.environ` or `sys.argv`.
|
|
- Never write credentials to `.git/config`. Use per-command `git -c http.extraHeader`.
|
|
|
|
## Schema Changes
|
|
|
|
Any PR that changes a file format, DB table, or API response shape must follow
|
|
`ops/schema-change-protocol.md`. Tag all consumers. Include migration.
|