Agent rules index

This page is the canonical loader for repository governance instructions. AGENTS.md stays small and mandatory, but the detailed rules live here and in the linked rule files so new sessions do not have to absorb the full policy corpus up front.

Bootstrap sequence

  1. Read AGENTS.md.
  2. Load this index.
  3. Load 05-non-negotiable-checklist.md.
  4. Load 10-session-bootstrap.md (always-load; deterministic startup orchestration before enforcement).
  5. Detect repository, branch, and worktree state.
  6. Reject implementation from the dev or main checkout unless the user explicitly overrides that rule.
  7. If GitHub hierarchy metadata is needed and .specfact/backlog/github_hierarchy_cache.md is missing or stale, refresh it with python scripts/sync_github_hierarchy_cache.py.
  8. Load additional rule files from the applicability matrix below before implementation (beyond the always-load set, which already includes this index, the checklist, and session bootstrap).

Precedence

  1. Direct system and developer instructions
  2. Explicit user override where repository governance allows it
  3. AGENTS.md
  4. docs/agent-rules/05-non-negotiable-checklist.md
  5. Other docs/agent-rules/*.md files selected through this index
  6. Change-local OpenSpec artifacts and workflow notes

Always-load rules

Order File Purpose
0 INDEX.md Deterministic rule dispatch and precedence
5 05-non-negotiable-checklist.md Invariant SHALL gates
10 10-session-bootstrap.md Startup checks and stop conditions

Applicability matrix

Task signal definitions

Use these canonical applies_when tokens in rule file frontmatter (under docs/agent-rules/*.md). They are the vocabulary AGENTS.md bootstrap and automation consume; do not invent ad-hoc strings.

Canonical signal Typical user intent
session-bootstrap First-load / startup sequencing (INDEX.md, checklist, session bootstrap).
implementation Code or behavior change in a worktree.
openspec-change-selection Choosing, validating, or editing an OpenSpec change.
branch-management Branch / worktree operations and conflicts.
github-public-work Public-repo GitHub issue linkage and hierarchy.
change-readiness Pre-flight metadata completeness before implementation.
finalization Closing out a change, evidence, or PR.
release Versioning, tagging, publish prep.
documentation-update User-facing docs and README edits.
repository-orientation Onboarding / where things live in the repo.
command-lookup CLI usage and command discovery.
detailed-reference Long-form catalogs and non-blocking reference.
verification Quality gates, tests, review artifacts.

Validation: hatch run validate-agent-rule-signals (runs scripts/validate_agent_rule_applies_when.py) checks every rule file’s applies_when list against this set. CI runs it from the Docs Review workflow when governance docs change.

Matrix row (human summary) Canonical signals (applies_when) Required rule files Optional rule files
Any implementation request implementation, openspec-change-selection, verification 10-session-bootstrap.md, 40-openspec-and-tdd.md, 50-quality-gates-and-review.md 20-repository-context.md; sibling internal wiki/ (see Internal wiki and strategic context in 40-openspec-and-tdd.md) when present
Code or docs changes on a branch branch-management, implementation 30-worktrees-and-branching.md 80-current-guidance-catalog.md
Public GitHub issue work github-public-work, change-readiness 60-github-change-governance.md 30-worktrees-and-branching.md
Release or finalization work finalization, release, documentation-update, verification 70-release-commit-and-docs.md, 50-quality-gates-and-review.md 80-current-guidance-catalog.md
Repo orientation or command lookup repository-orientation, command-lookup 20-repository-context.md 80-current-guidance-catalog.md

Canonical rule files

Preservation note

The prior long AGENTS.md content has been preserved by reference in these rule files. The goal of this migration is to reduce startup token cost without silently dropping repository instructions.