Repository instructions for coding agents (Claude Code, Codex, etc.). This is the canonical file; the other agent-guide filename is a symlink to it, so every agent reads the same guide.
Open-source GitHub replacement (git server, CI/CD, hosting, snippets, issues, agent work-logs, live-presence, GraphQL, PR, smart blame) plus a local-first SwiftUI mobile app (offline viewer for GitHub + Linear).
The spec is authoritative: read docs/SPEC.md before touching any feature. If code
and spec disagree, the disagreement is the finding. Update the spec in the same PR that
changes behavior.
docs/SPEC.md # master spec — source of truth
server/ # platform backend (git server, API, CI, hosting)
mobile/ # SwiftUI iOS app (MVP)
ci/ # rig-managed CI gate scripts
.github/ # workflows, PR template (rig-managed)
rig.yaml # declarative repo guardrails
- Swift (mobile):
swift build(package) ·xcodebuild -scheme HyperGit build(app) · run on simulator via Xcode. - Tests:
swift test. - Tasks/issues: use the
taskCLI (writes to GitHub Issues in this repo). - Guardrails:
rig status(drift) ·rig apply(converge) ·rig doctor(deps). - Review before commit:
review diff -C .(multi-model, read-only).
- Git only — no other VCS. Projects → Linear. Browser IDE → hyperide (not us).
- Commits: Conventional Commits (
feat:,fix:,docs:,chore:), atomic, often. - Branches: feature branch → PR (squash-merge).
mainstays green. CI gates are not bypassed (no--no-verify). - Spec sync: any behavior change updates
docs/SPEC.mdin the same PR. - Agents are first-class users: design APIs/hooks/UI so machines read and write them too.
- Local-first on mobile: everything downloadable must work offline; sync is background.
- Minimal dependencies: prefer native frameworks; justify every new dependency.
- No secrets in git.
.env*,*.key,*.pem,credentials.tomlare gitignored.
- Swift 6, strict concurrency (
async/await,@Observable, Sendable). - Layers: Views → Store/ViewModel → Services → Clients (GitHub/Linear REST+GraphQL) → Persistence (SwiftData/SQLite).
- Backend is abstracted behind protocols so GitHub can be swapped for HyperGit later.