Agent Centric

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.

Release history

See CHANGELOG.md for version history. VERSION is the machine-readable version owner.