AGENTS.md
file-level
1
files
1
commits
0
hotspots
0
🧊 dead
0
💥 blast risk
| 1 | # Knowtation — agent instructions |
| 2 | |
| 3 | ## Version control (read first) |
| 4 | |
| 5 | This repo uses **Muse** for the canonical history on **MuseHub (staging)** and **Git** for **GitHub** (PRs, CI, mirrors). |
| 6 | |
| 7 | | Intent | Tooling | |
| 8 | |--------|---------| |
| 9 | | **Default** — ship product changes to MuseHub | `muse status` → `muse code add …` → `muse commit -m "…"` → `muse push staging <branch>` | |
| 10 | | **GitHub-only** — PR, branch protection, Actions | `git add` / `git commit` / `git push` when the user or task says Git is the target | |
| 11 | |
| 12 | - Staging remote name: **`staging`** (`aaronrene/knowtation` on `staging.musehub.ai`). |
| 13 | - **`.museignore`** governs Muse snapshots; keep it aligned with **`.gitignore`** for secrets and local data (`config/local.yaml`, `data/`, etc.). |
| 14 | - If the user says "commit" without specifying **Muse** or **Git**, **prefer Muse** for this tree or ask once. |
| 15 | |
| 16 | ## GitHub mirror workflow — MANDATORY, no exceptions |
| 17 | |
| 18 | **NEVER push directly to `main` on GitHub.** Every Muse merge to local `main` must be mirrored to GitHub via a PR from the `muse-mirror` branch. This is what preserves the PR audit trail (PR #NNN links, diff view, review threads). |
| 19 | |
| 20 | **Required steps every time code lands on Muse `main`:** |
| 21 | |
| 22 | ```bash |
| 23 | # 1. After: muse checkout main && muse merge feat/<branch> |
| 24 | git add -A && git commit -m "mirror: muse <sha-before>..<sha-after> (<description>)" |
| 25 | git checkout -B muse-mirror # reset muse-mirror branch to current HEAD |
| 26 | git push origin muse-mirror --force # push mirror branch to GitHub |
| 27 | |
| 28 | # 2. Open a PR from muse-mirror → main |
| 29 | gh pr create --base main --head muse-mirror \ |
| 30 | --title "mirror: <description>" \ |
| 31 | --body "Muse mirror — <muse-sha-range>" |
| 32 | |
| 33 | # 3. Merge the PR (merge commit, not squash or rebase) |
| 34 | gh pr merge --merge |
| 35 | ``` |
| 36 | |
| 37 | **Hard stops — if you are about to run either of these, STOP:** |
| 38 | - `git push origin main` — use muse-mirror instead |
| 39 | - `git push origin HEAD` while on `main` — use muse-mirror instead |
| 40 | |
| 41 | **Why this rule exists:** The GitHub PR history is the permanent, human-readable audit record. PRs #226, #227, … are proof that every change was reviewed before landing. Pushing directly to `main` skips that record entirely and is not recoverable after the fact. |
| 42 | |
| 43 | ## Knowtation product (MCP / CLI / vault) |
| 44 | |
| 45 | Orchestration, MCP vs CLI, retrieval, and write-back: **[docs/AGENT-ORCHESTRATION.md](docs/AGENT-ORCHESTRATION.md)**. One-page surface overview: **[docs/AGENT-INTEGRATION.md](docs/AGENT-INTEGRATION.md)**. |
| 46 | |
| 47 | **Private vaults:** outside the repo or only via ignored `config/local.yaml` — not under in-repo `vault/` if remotes may be public. |
| 48 | |
| 49 | ## Tests and quality |
| 50 | |
| 51 | Follow project conventions in **[CONTRIBUTING.md](CONTRIBUTING.md)** and existing test layout under `test/`. Do not commit secrets or gitignored paths. |