Skip to content

Dashecorp rig-gitops — AGENTS.md

Compiled from facts/. Do not edit by hand. Regenerate: ./scripts/compile-agents-md.sh

Repository

GitOps manifests and documentation hub for the Dashecorp engineering rig. Managed via Flux (GitOps) on k3s/GCP.

Session start (every agent, every session)

  1. BEFORE any rig work, WebFetch https://research.rig.dashecorp.com/BRAIN.md (public, ~12 KB) — it is the current truth for the repo manifest, surfaces, agent deployments, and primary flows. Compiled from facts/*.yaml in dashecorp/rig-docs; CI fails on drift.
  2. Then fetch https://research.rig.dashecorp.com/llms.txt for the research/proposal/user-story index.
  3. read_memories scoped to target repo before implementing.

Stack

Field Value
Runtime node@22
Language javascript (TypeScript: false)
Package manager npm
Test framework vitest
Linters eslint, prettier
Deployment flux + kubernetes (k3s on GCP)
Secrets sops + age

Essential commands

Command Purpose
./scripts/compile-agents-md.sh Regenerate this file from facts/
./scripts/compile-agents-md.sh --check Verify AGENTS.md is in sync (CI)
./scripts/build-docs.sh Regenerate docs-site/
./scripts/migrate-frontmatter.sh Backfill audience: in docs/

Code conventions

  • Commits: conventional (feat, fix, refactor, docs, test, chore, ci) Format: type(scope): description — e.g. feat(auth): add OAuth2 login
  • Branches: feature/issue-{N}-short-description
  • Merge: squash-only
  • Closes N: required — include Closes #N in every PR body

PR workflow

  • Always create PR, never push to main directly
  • Run the project test suite before git push — fail-then-stop if tests exit non-zero; note result in PR body Test plan section
  • PR body MUST include a 'Test plan' section (transcript or summary of test run and result)
  • Use 'Closes #N' in PR body to auto-close on merge
  • Wait for Review-E approval before merging
  • After creating PR, post progress updates to Discord thread in #tasks

MCP servers configured

  • memory — shared rig memory — search before implementing, write after merge
  • github — GitHub API — issues, PRs, code search
  • advisor — operational advisor handoff for stuck situations

Common pitfalls

  1. npx -y does not prefer globally-installed packages; install globally first
  2. GitHub Packages npm: repo visibility doesn't cascade to published package versions
  3. rig-conductor API events require PascalCase fields and UPPER_SNAKE type names
  4. Kubernetes pods with imagePullPolicy=Always need explicit deletion to pick up new images
  5. Terraform moved blocks must be added to every workspace tracking the resource
  6. SOPS-encrypted files must never be committed in plaintext; always encrypt before staging
  7. Flux HelmRelease reconciliation can stall silently; check flux get hr -A after changes
  8. docs/*.md frontmatter must include 'audience: agents|humans|both' — 'queries' is now optional/legacy
  9. User stories enter as GitHub issues in dashecorp/rig-docs (via GitHub mobile app or web); never create user-story issues in other repos — they won't be picked up by the agent loop
  10. Research + proposals live as markdown PRs in dashecorp/rig-docs under src/content/docs/{research,proposals}/; CI creates implementation issues on proposal approval — do NOT create them by hand
  11. Diagrams in rig-docs are Mermaid source inline in markdown — do NOT commit PNG or SVG artifacts; the remark-mermaid plugin renders them client-side and the source stays in the DOM for agents
  12. Run the project's test suite (npm test / pytest -q / dotnet test) before git push — fail-then-stop if tests fail; note 'no test suite present' in PR body when none exist

Documentation standard

  • All docs/*.md require YAML frontmatter with title, description, type, audience, updated
  • audience enum: agents | humans | both
  • Tables over paragraphs; code blocks for commands
  • Full spec: docs/documentation-standard.md

Branching & PR rules

  • Never push directly to main
  • Branch prefix must match commit type: feature/, fix/, refactor/, docs/, chore/, ci/, test/
  • Every PR that adds or changes behavior must include doc updates

Review expectations

Every PR is checked for: correctness, security (OWASP top 10), tests, docs (valid frontmatter), conventional commits. Blocking: security issues, bugs, broken tests, missing docs on behavior changes.

See also