Skip to content

AGENTS.md: dedup against new global (D-0006) #333

@chipi

Description

@chipi

Context

This repo's AGENTS.md predates the consolidated global AGENTS.md at
chipi/agentic-ai-homelab/AGENTS.md.
The global owns universal rules; per-project files should keep ONLY
project-specific content. This was codified as decision D-0006 in
agentic-ai-homelab/docs/history/0002-decisions.md.

This repo's AGENTS.md is currently ~669L. Expected post-dedup:
~100-150L of only-project-specific content.

Goal

Bring this project's AGENTS.md into compliance with the D-0006 pattern:
global owns universal rules, project files own only what's specific here.

The classification rule

For every rule currently in AGENTS.md:

Bucket Example Action
Duplicate of global "Never push without explicit approval" Delete — global covers it
Project specialization "Never push to main; the auth team's RFC-0007 mandates PR review" Keep + flag relationship to the global rule
Project-specific only Stack table, named ADR anchors, domain knowledge, custom workflows Keep as-is

If you find yourself reluctant to delete a duplicate because "ours is
worded better", that's a signal to update the global instead — open a PR
to chipi/agentic-ai-homelab first, then come back here.

Concrete steps

  1. Pull the global side-by-side with this repo's AGENTS.md:
    curl -s https://raw.githubusercontent.com/chipi/agentic-ai-homelab/main/AGENTS.md > /tmp/global-agents.md
    diff -u /tmp/global-agents.md AGENTS.md | less
  2. Classify each rule into one of the three buckets above.
  3. Add this preamble at the top of AGENTS.md:
    > Layers on `~/.config/opencode/AGENTS.md` (canonical:
    > https://github.com/chipi/agentic-ai-homelab/blob/main/AGENTS.md).
    > Only project-specific rules live here.
  4. Verify nothing critical was lost: read the trimmed file end-to-end. If
    it reads as "everything an agent specifically working on this project
    needs to know that the global doesn't cover", you're done.
  5. Branch, commit AGENTS.md: dedup against new global (D-0006), open PR.

Acceptance

  • AGENTS.md shrunk to roughly ~100-150L (from ~669L)
  • Top of file has the layered-on-global preamble
  • All project-specific rules / stack / ADR anchors / domain knowledge preserved
  • Zero rules in the file restate universal global rules

Cross-references

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions