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

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.

Canonical signal Typical user intent
session-bootstrap First-load and startup sequencing
implementation Code or behavior change in a worktree
openspec-change-selection Choosing, validating, or editing an OpenSpec change
branch-management Branch and worktree operations
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 and repo layout questions
command-lookup Hatch commands and workflow lookup
detailed-reference Long-form catalog and preserved guidance
verification Quality gates, tests, and review artifacts

Validation: hatch run validate-agent-rule-signals runs scripts/validate_agent_rule_applies_when.py and checks every rule file’s applies_when list against this set.

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