aaronrene / knowtation public
AGENTS.md markdown
51 lines 2.7 KB
Raw
sha256:0d530f9ef27b8b75547d1db7701a74bc77b77aa8f3d7fa3a8672cf2af36e63bb reconcile: import GitHub-direct RBAC/OAuth/companion and ho… Human minor ⚠ breaking 6 hours ago

Knowtation — agent instructions

Version control (read first)

This repo uses Muse for the canonical history on MuseHub (staging) and Git for GitHub (PRs, CI, mirrors).

Intent Tooling
Default — ship product changes to MuseHub muse status → muse code add … → muse commit -m "…" → muse push staging <branch>
GitHub-only — PR, branch protection, Actions git add / git commit / git push when the user or task says Git is the target
  • Staging remote name: staging (aaronrene/knowtation on staging.musehub.ai).
  • .museignore governs Muse snapshots; keep it aligned with .gitignore for secrets and local data (config/local.yaml, data/, etc.).
  • If the user says "commit" without specifying Muse or Git, prefer Muse for this tree or ask once.

GitHub mirror workflow — MANDATORY, no exceptions

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).

Required steps every time code lands on Muse main:

# 1. After: muse checkout main && muse merge feat/<branch>
git add -A && git commit -m "mirror: muse <sha-before>..<sha-after> (<description>)"
git checkout -B muse-mirror          # reset muse-mirror branch to current HEAD
git push origin muse-mirror --force  # push mirror branch to GitHub

# 2. Open a PR from muse-mirror → main
gh pr create --base main --head muse-mirror \
  --title "mirror: <description>" \
  --body "Muse mirror — <muse-sha-range>"

# 3. Merge the PR (merge commit, not squash or rebase)
gh pr merge --merge

Hard stops — if you are about to run either of these, STOP:

  • git push origin main — use muse-mirror instead
  • git push origin HEAD while on main — use muse-mirror instead

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.

Knowtation product (MCP / CLI / vault)

Orchestration, MCP vs CLI, retrieval, and write-back: docs/AGENT-ORCHESTRATION.md. One-page surface overview: docs/AGENT-INTEGRATION.md.

Private vaults: outside the repo or only via ignored config/local.yaml — not under in-repo vault/ if remotes may be public.

Tests and quality

Follow project conventions in CONTRIBUTING.md and existing test layout under test/. Do not commit secrets or gitignored paths.

File History 2 commits
sha256:0d530f9ef27b8b75547d1db7701a74bc77b77aa8f3d7fa3a8672cf2af36e63bb reconcile: import GitHub-direct RBAC/OAuth/companion and ho… Human minor ⚠ 6 hours ago
sha256:a5a868958d54fc728983f8c0d39bca08882c8757b5b30909739d1c2f38df9613 docs: Muse-first agent guidance and AGENTS.md Human 39 days ago