Agd Update Agents Md

Freshness check — determine what has changed since AGENTS.md was last updated:

# When was AGENTS.md last committed?
git log -1 --format="%ar" -- AGENTS.md

# What files changed since then? (guard against untracked/never-committed case)
AGENTS_COMMIT=$(git log -1 --format="%H" -- AGENTS.md)
[ -n "$AGENTS_COMMIT" ] && git diff --name-only "$AGENTS_COMMIT" HEAD || git status --short

• If AGENTS.md is untracked or was never committed, $AGENTS_COMMIT will be empty and the command falls back to git status --short automatically
• If the subshell returns empty without the guard, git diff --name-only HEAD silently diffs the working tree instead — always use the guarded form
• Scan the diff output for staleness signals:
  • New/removed directories (plugins/, src/, packages/) → structure drift
  • Changes to package.json, Makefile, or build configs → commands may be outdated
  • New CI workflow files (.github/workflows/) → undocumented pipeline steps
  • New linter/formatter configs (.eslintrc, vitest.config.ts) → style section stale
• Use signals to pre-classify the update scope before deeper analysis:
  • Fresh (0-1 signals AND committed <1 month ago): expect a minor 1-2 section edit
  • Moderate (2-3 signals): focus step 3 analysis on flagged areas only
  • Stale (4+ signals, OR last commit >3 months ago regardless of signal count): full pass required
• This is a predictive pre-classification to scope step 3 effort. The final update scope is confirmed in step 4 after analysis and may differ.

Analyze project for changes:

• Check package.json scripts vs documented commands
• Compare linter/formatter config with documented style
• Review CI/CD workflows for new steps
• Detect new tools or dependencies

Identify update scope:

• Minor update: 1-2 sections need changes
• Moderate update: 3-4 sections or new sections needed
• Major update: Significant restructure required

Update sections incrementally:

• Preserve existing structure and style
• Update outdated commands
• Add new sections for new tools/processes
• Remove obsolete sections
• Target: 50-80 lines — condense aggressively before writing
• Use relative paths for all references (e.g., ./docs/agents/testing.md, ../api/AGENTS.md)
• For monorepos: Add/update relative path references to sibling packages
• Update linked reference docs: if AGENTS.md links to files in docs/agents/ or similar, check those files for stale content (outdated architecture trees, removed components, renamed paths) and update them in the same pass

Check line count before writing:

• Count projected lines of updated content
• If over 100 lines, first try to condense: shorten descriptions, remove duplicated info, apply progressive disclosure
• If still over 100 lines after condensing, proceed to step 7 before writing

If projected content exceeds 100 lines — ask and then act: Use AskUserQuestion:

questions: [
  {
    "question": "The AGENTS.md will exceed 100 lines. Would you like me to split detailed content into a references folder?",
    "header": "References",
    "options": [
      {
        "label": "No, keep it compact",
        "description": "Try harder to condense. Keep AGENTS.md as a single file."
      },
      {
        "label": "Yes, create docs/agents/",
        "description": "Create docs/agents/ and move detailed sections there, leaving brief summaries with links in AGENTS.md."
      },
      {
        "label": "Yes, use custom path",
        "description": "Specify a custom path for the references folder."
      }
    ]
  }
]

If user chooses to split:

• Identify sections that are best candidates: architecture explanations, long code examples, multi-step guides
• For each section to move: create docs/agents/<section-name>.md (or user-specified path)
• Replace the section in AGENTS.md with a 2-3 line summary + See docs/agents/<section-name>.md for details.
• Ensure AGENTS.md stays under 100 lines after the split

Write updated AGENTS.md:

• Maintain consistent formatting
• Ensure all commands are current and executable

Validate the updated file:

• Run validation checklist from skill
• Test all commands are executable
• Ensure no information lost
• Verify file is under 100 lines

Report changes: Summarize what was updated: