agent-centric

name	agent-centric
description	Track decisions (AGD) with validation and indexing. Use when making design decisions, recording important choices, discussing trade-offs, or when user mentions AGD or decision record.
hooks	{"PostToolUse":[{"matcher":"Bash|Write|Edit","hooks":[{"type":"command","command":"CLAUDE_PROJECT_DIR=\"$CLAUDE_PROJECT_DIR\" \"$CLAUDE_PROJECT_DIR/.agents/scripts/validate-agds.py\""},{"type":"command","command":"CLAUDE_PROJECT_DIR=\"$CLAUDE_PROJECT_DIR\" \"$CLAUDE_PROJECT_DIR/.agents/scripts/generate-index.py\""}]}]}

Agent Centric

Framework for agent-centric development. Currently provides AGD (Agent-centric Governance Decision) tracking.

What is AGD?

AGD (Agent-centric Governance Decision) is a decision record mechanism, similar to ADR or RFC. Each AGD has a unique number (e.g., AGD-001) that records important decisions, rationale, and impact.

AGD covers any important decision, not just architecture - including design patterns, conventions, tool choices, process decisions, etc.

AGD follows the RFC archival model: original files are preserved, and later decisions express how earlier ones evolve.

• updates: extends or modifies an earlier decision; the earlier decision remains partially valid
• obsoletes: completely replaces an earlier decision; the earlier decision is no longer current
• related: reference-only connection, similar to RFC see-also; does not change validity of either decision

AGD exists to give the project stable references for important decisions and durable rationale that survives code evolution. It should let us trace from today's implementation back to why it was chosen, and then judge whether that decision still stands, has been updated, or has been replaced.

When to Use

• Making important design/architecture decisions
• User explicitly asks to record a decision
• Discussing trade-offs that should be documented
• Referencing or searching existing decisions

Setup

On each skill load, sync scripts and initialize if needed:

if [ ! -d "$CLAUDE_PROJECT_DIR/.agents" ]; then
  CLAUDE_PROJECT_DIR="$CLAUDE_PROJECT_DIR" CLAUDE_SKILL_DIR="$CLAUDE_SKILL_DIR" bash "$CLAUDE_SKILL_DIR/scripts/init.sh"
else
  CLAUDE_PROJECT_DIR="$CLAUDE_PROJECT_DIR" CLAUDE_SKILL_DIR="$CLAUDE_SKILL_DIR" bash "$CLAUDE_SKILL_DIR/scripts/sync-scripts.sh"
fi

If scripts were updated, briefly inform the user.

Automatic Behaviors

Hooks run automatically when you use Write/Edit/Bash tools on AGD files:

• Validates all AGD files (tags, references)
• Regenerates indexes automatically (silent on success)

If validation fails, you'll see errors and should fix them (e.g., add missing tags to config.json).

Creating AGD Files

File Naming

AGD-{number}_{kebab-case-name}.md

Examples: AGD-001_use-postgresql.md, AGD-002_adopt-hexagonal-architecture.md

File Format

---
title: "Decision Title"
description: "Brief description"
tags: tag1, tag2
updates: AGD-001
obsoletes: AGD-002
related: AGD-003
---

## Context
Why this decision is needed.

## Decision
What was decided.

## Consequences
Impact of this decision.

See references/agd.md for complete field documentation.

Searching Decisions

IMPORTANT: Always use grep and find to search. Do NOT read files to search.

# By keyword
grep -r "keyword" "$CLAUDE_PROJECT_DIR/.agents/decisions/"

# By AGD number
find "$CLAUDE_PROJECT_DIR/.agents/decisions/" -name "AGD-001*"

# By tag
grep "#tagname" "$CLAUDE_PROJECT_DIR/.agents/INDEX-TAGS.md"

# By relationship
grep "AGD-001" "$CLAUDE_PROJECT_DIR/.agents/INDEX-AGD-RELATIONS.md"

Managing Tags

Add tags to .agents/config.json before using them:

{
  "tags": ["core", "auth", "api"]
}

See references/config.md for config details.

Version History

• v1.6.1 (2026-04-13): Fully manage updated_by/obsoleted_by by syncing and pruning reverse references, skip validation of auto-generated reverse fields
• v1.6.0 (2026-04-13): Add related relationship with RFC-style see-also semantics, extend relation index with -(r)->, clarify archival relationship model
• v1.5.0 (2026-01-23): Remove PreToolUse hook (PostToolUse validation sufficient), fix exit codes to use code 2 for blocking errors
• v1.4.0 (2026-01-22): Add PreToolUse hook to block invalid AGD creation, auto-detect project dir
• v1.3.0 (2025-01-22): Split references/, renamed validate-agds.py
• v1.2.0 (2025-01-22): Split to SKILL.md + REFERENCE.md
• v1.1.0 (2025-01-21): Merged index files, hooks in frontmatter, auto-init
• v1.0.0 (2025-01-21): Initial version