renatocaliari/cali-agents-md-generator

AGENTS.md Generator

Creates and maintains lean, high-signal AGENTS.md files for AI coding agents. Uses sem (semantic version control) for staleness detection on ongoing commits.

Prerequisites: sem

sem is required for staleness detection. Check if installed:

sem --version

If not installed:

brew install sem-cli

Verify it works in the project:

cd /path/to/project
sem diff --format json  # Should return JSON with entity changes

User Confirmation Contract (MUST FOLLOW)

Every write to AGENTS.md requires user approval before the write happens. This is not optional. The user must see what will change and explicitly confirm (yes / no / modify).

For each phase that produces a file change, the skill MUST:

1. Summarize the change in a table or diff:
   • Sections added (with proposed content)
   • Sections removed (with reason)
   • Sections modified (old → new, condensed)
   • Net line delta
2. Show the full proposed file (or the diff against the existing one) so the user can read it in context.
3. Ask explicitly: "Approve this change? (yes / no / modify)"
4. On "no": do not write. Ask what the user wants instead.
5. On "modify": ask which parts to change, iterate the proposal, re-confirm.
6. On "yes": write the file. Show the result. Do not re-ask for confirmation.

Forbidden patterns:

• Writing the file and then saying "let me know if you want changes"
• Skipping the summary because "the change is small"
• Showing only a partial diff that hides removals
• Auto-confirming on the user's behalf ("proceeding with the obvious choice")

Why this matters: AGENTS.md is read by every future agent session. A bad edit corrupts the context for hundreds of future calls. Confirmation cost is seconds; the cost of an unconfirmed bad edit is permanent.

Workflow

Phase 1: Check

Does the project root have AGENTS.md?

ls AGENTS.md 2>/dev/null

• If exists: Ask user if they want to review/update it. If yes, go to Phase 1.5.
• If missing: Ask user: "This project has no AGENTS.md. Shall I create one?"
  • If no: stop.
  • If yes: go to Phase 2.

Phase 1.5: Detect Divergence from Canonical Template

Skip if AGENTS.md does not exist (handled by Phase 1).

When AGENTS.md exists, do NOT assume it conforms to the canonical shape. Read it fully and classify before deciding what to do next:

# Count current size
wc -l AGENTS.md

# Read in full
cat AGENTS.md

Then classify into one of three buckets:

| Bucket | Signal | Next step | |---|---|---| | A. Conforms to template | Section headers match references/agmd-template.md; total ≤ 30 lines | Phase 3 (update-only: investigate each section, present a per-section diff old→new, do NOT rewrite the whole file) | | B. Diverges but contains valid content | Custom section names, but content is current; or over 30 lines with real value | Phase 3.5 (refactor to canonical shape) | | C. Contains legacy / deprecated sections | Some sections reference uninstalled tools, deprecated CLIs, removed packages, "## lat.md Documentation"-style sections, broken URLs, or describe tech no longer in the project. Other sections may still be valid — only the legacy ones are removed. | Phase 3.5 (refactor + flag for removal) |

How to detect "legacy / deprecated":

1. Cross-reference the section topic against the current codebase:

   # Example: check if a referenced tool/CLI is still installed
   which <tool-name> 2>/dev/null
   test -d <referenced-dir> 2>/dev/null
   grep -l "<referenced-package>" go.mod package.json requirements.txt 2>/dev/null
   

2. If the referenced thing is not present, the section is stale.
3. Common stale patterns: documentation for uninstalled extensions, removed CLI tools, deprecated npm packages, references to deleted files.

Always show the classification to the user before proceeding. They may re-classify if the skill's judgment is wrong.

Example output to user:

I read the existing AGENTS.md (62 lines) and compared it to the canonical template.

Classification: Bucket C (has legacy sections)

| Existing section | Lines | Status | Action | |---|---|---|---| | ## lat.md Documentation | 32 | Legacy (extension uninstalled) | Remove | | ## Datastar Go SDK v2 Watch | 9 | Current | Keep, move under canonical | | ## Funcionalidades do Produto | 8 | Custom but valid | Map to canonical section | | ## Landing Page | 7 | Custom but valid | Map to canonical section |

Propose: refactor to canonical shape, removing 32 lines of legacy content. OK to proceed?

Phase 2: Scaffold

Generate a minimal AGENTS.md using the template from references/agmd-template.md.

Before writing, follow the User Confirmation Contract:

1. Show the scaffolded file in full
2. Show a summary table: sections × estimated line count
3. Ask: "Scaffold looks right? (yes / no / modify)"
4. On yes → write the file
5. On no/modify → iterate before writing

Phase 3: Investigate & Fill

Analyze the full codebase to fill in placeholders:

1. Directory structure: find . -type f -name '*.go' | head -30 (or relevant extensions)
2. Entry points: Look for main.go, cmd/, index.ts, etc.
3. Build system: Check Makefile, go.mod, package.json, Dockerfile
4. Test setup: Find test files, check test runner config
5. Dependencies: Read go.mod, package.json, requirements.txt
6. Conventions: Scan existing code for naming patterns, error handling, project structure

Fill every [To be determined] and [Add your ... here] placeholder. Remove any section that stays empty after investigation.

Target: 20-30 lines max. If over 30 lines, move detailed content to separate docs.

Before writing, follow the User Confirmation Contract:

1. Show a diff table of every placeholder → filled value
2. Show the final line count
3. Show any sections that were removed because they stayed empty
4. Ask: "Proposed AGENTS.md (N lines). Approve? (yes / no / modify)"
5. On yes → write the file
6. On no/modify → iterate before writing

Phase 3.5: Refactor to Canonical Shape (when Phase 1.5 = B or C)

When the existing AGENTS.md has good content but wrong shape (Bucket B or C from Phase 1.5), restructure it. Do NOT just patch in place — the result must match the canonical template from references/agmd-template.md.

Steps:

1. Build a section map. For every existing section, decide:
   • Maps to canonical section (e.g. existing "Comandos" → canonical "Commands"): rewrite under the canonical header, condensed to 1-3 lines.
   • Does not map, but content is valuable (e.g. project-specific workflows, design notes): move to a separate docs/<topic>.md file and reference it from the canonical section ("See docs/landing-page.md").
   • Does not map, content is stale or references removed tech: remove.
2. Get user approval for the map before writing. Show:
   • Which sections map to which canonical headers
   • Which sections move to separate docs
   • Which sections are deleted (and why)
3. Rewrite the file in canonical shape, using references/agmd-template.md as the skeleton. Fill canonical sections from the mapped content.
4. Move out-of-shape content to separate docs/*.md files (preserve history, don't lose knowledge).
5. Verify line count is 20-30. If over, more content moves out.
6. Update .gitignore or add a comment explaining the new file structure if non-obvious.

Forbidden in this phase:

• Appending to AGENTS.md without restructuring (bloats the file)
• Keeping legacy sections "for context" (defeats the purpose)
• Inlining multi-paragraph explanations (move them to docs/*.md)

Phase 4: Review

This phase is the formal gate — file is on disk but not yet "approved".

Show the user:

1. The full final AGENTS.md
2. Final line count (target 20-30)
3. For each section: why it's there (what a future agent would be misled about without it)
4. Sections the agent could infer from code (candidates for removal)
5. A summary of what sem diff will check going forward

Ask explicitly: "Final review. Approve? (yes / no / modify)"

• On yes: "✅ AGENTS.md approved. Future agent sessions will read this."
• On no: ask which sections to change, iterate
• On modify: apply the requested edits, re-show the full file, re-ask

Do not consider the task complete until the user has explicitly approved.

Phase 4.5: Validate (runs validator skill if available)

After the user approves in Phase 4, run the validator skill to catch quality issues the human review may have missed. The validator is read-only and warn-only — it never blocks, it surfaces.

Discover the validator skill (same portable pattern the pre-commit hook uses — project-local first, then home, then XDG):

VALIDATOR_DIR=""
for d in \
    "./.agents/skills/cali-agents-md-validator" \
    "./.pi/skills/cali-agents-md-validator" \
    "${HOME}/.agents/skills/cali-agents-md-validator" \
    "${HOME}/.pi/skills/cali-agents-md-validator" \
    "${XDG_DATA_HOME:-${HOME}/.local/share}/agents/skills/cali-agents-md-validator"; do
  [ -f "${d}/SKILL.md" ] && VALIDATOR_DIR="${d}" && break
done

If the validator is installed:

if [ -n "${VALIDATOR_DIR}" ] && [ -f "${VALIDATOR_DIR}/references/validate-agents-md.sh" ]; then
  bash "${VALIDATOR_DIR}/references/validate-agents-md.sh" ./AGENTS.md || true
fi

Show the validator report to the user. If there are failures (not just warnings):

1. Offer to fix each failure.
2. If user accepts the fix: loop back to Phase 3 (or Phase 3.5 for refactor) — including a full User Confirmation Contract cycle (show diff, ask yes/no/modify) — then re-run Phase 4.5. Do not re-write without re-confirming.
3. If user declines the fix: document the failures in the commit message and proceed. Do not silently ignore.

If the validator is NOT installed: skip silently. Do not block the skill. Mention once: "Validator skill not found. Skipping automated quality check. Install at any time: see cali-agents-md-validator skill."

Why this phase exists: Human review is good for content ("is this section meaningful?") but bad for mechanical checks (line count, secrets, missing required sections). The validator is the single source of truth for mechanical quality. Running it here closes the build → review → test loop on every AGENTS.md the skill produces.

Phase 5: Offer Staleness Guard (ALWAYS)

Every time this skill is invoked — whether creating new, reviewing, or evolving — check if the sem pre-commit hook is installed and offer to install it.

Check if hook exists:

test -f .git/hooks/pre-commit && grep -q "sem diff" .git/hooks/pre-commit 2>/dev/null && echo "installed" || echo "not installed"

If not installed, ask the user:

The sem pre-commit hook detects when code entities (functions, classes, methods) change and warns if AGENTS.md may be stale. This keeps your project docs accurate without manual checking.

Shall I install the sem staleness hook in .git/hooks/pre-commit?

If user confirms, install:

# If no existing pre-commit hook:
cp references/pre-commit-hook.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# If existing hook needs merging: append sem check to end of existing hook
cat references/pre-commit-hook.sh >> .git/hooks/pre-commit

If user declines, skip silently. Don't ask again in this session.

If already installed, confirm silently:

✅ sem staleness hook already installed in .git/hooks/pre-commit

Template Design Principles

• 20-30 line budget — LLMs degrade with too many instructions
• No backward compatibility by default — Bold refactoring over legacy support
• Placeholder sections — Fill as project grows, then remove placeholders
• Section protection via HTML comments — <!-- Do not restructure or delete sections -->
• Only document non-obvious things — Code structure belongs in code, not AGENTS.md

Staleness Detection

The pre-commit hook uses sem diff --format json to detect entity-level changes (functions, classes, methods, headings) and warns when AGENTS.md may need updating.

What sem provides:

• Entity-level diffs (not just line numbers)
• Rename detection
• Structural change classification
• JSON output for script consumption

What the hook checks:

• Whether any code entities changed in the staged files
• Lists the changed entities with type and file
• Reminds to review AGENTS.md

CI Guard (Optional)

For GitHub Actions, add the workflow from references/github-action-guard.yml to .github/workflows/agents-md-guard.yml. It runs sem diff in CI and comments on PRs when code entities change without corresponding AGENTS.md updates.

Examples

Example 1: New project without AGENTS.md

Input: "This project has no AGENTS.md, create one"

Steps:

1. Check: ls AGENTS.md 2>/dev/null → not found
2. Ask: "Shall I create one?" → User says yes
3. Scaffold from template
4. Investigate: entry points, build system, tests, conventions
5. Fill placeholders, target 70-100 lines (sweet spot), 150 hard limit
6. Present for review
7. Offer hook installation

Output: "Created AGENTS.md with 24 lines covering: entry point, build, test, conventions. Hook installed."

Example 2: Existing AGENTS.md needs update

Input: "Check if our AGENTS.md is still accurate"

Steps:

1. Check: ls AGENTS.md 2>/dev/null → found
2. Ask: "Want to review/update it?" → User says yes
3. Phase 1.5: Read AGENTS.md, classify → Bucket A (conforms to template)
4. Run: sem diff --format json → shows 5 entity changes since last AGENTS.md update
5. Investigate changed entities
6. Update relevant sections
7. Offer hook installation (if not installed)

Output: "Found 5 entity changes since last update. Updated 2 sections. Hook already installed."

Example 3: Hook installation

Input: "Install the staleness hook"

Steps:

1. Check: test -f .git/hooks/pre-commit && grep -q "sem diff" .git/hooks/pre-commit → not found
2. Explain benefit
3. Ask: "Shall I install?" → User says yes
4. Install: cp references/pre-commit-hook.sh .git/hooks/pre-commit
5. Verify: chmod +x .git/hooks/pre-commit

Output: "✅ Sem staleness hook installed. It will warn when code entities change without AGENTS.md updates."

Example 4: Existing AGENTS.md with legacy / bloated content

Input: "Our AGENTS.md is outdated and bloated, clean it up"

Steps:

1. Check: ls AGENTS.md 2>/dev/null → found (62 lines, expected 20-30)
2. Ask: "Want to review/update it?" → User says yes
3. Phase 1.5: Read AGENTS.md, classify → Bucket C (has legacy "lat.md Documentation" section)
4. Show user the section map: legacy section removed, project-specific sections moved to docs/, canonical sections refilled
5. Get user approval
6. Phase 3.5: Refactor to canonical shape, move out-of-shape content to docs/landing-page.md and docs/funcionalidades.md
7. Verify: 24 lines, conforms to template
8. Offer hook installation

Output: "Refactored 62-line AGENTS.md to 24-line canonical shape. Removed 1 legacy section (32 lines). Moved 2 custom sections to docs/. Hook already installed."

Edge Cases

Project has no .git directory

• Cannot install pre-commit hook
• Tell user: "This project has no git repo. Initialize git first, then install the hook."
• Still generate AGENTS.md (it's useful without the hook)

sem is not installed

• Check: sem --version → not found
• Offer to install: brew install sem-cli
• If user declines: skip hook installation, still generate AGENTS.md
• Note: staleness detection won't work without sem

AGENTS.md is already > 30 lines, has legacy sections, or has custom valid sections

• See Phase 1.5 → Bucket B/C classification. These edge cases are now covered by the bucket logic in Phase 1.5 and the refactor workflow in Phase 3.5. Do not duplicate the logic here.

User declines hook installation

• Skip silently
• Don't ask again in this session
• AGENTS.md is still useful without the hook

Test Cases

Should activate

• "Create AGENTS.md for this project"
• "Generate agents md"
• "Setup agents md"
• "Check if AGENTS.md is stale"
• "Update the agents md"
• "Install the sem hook"

Should NOT activate

• "Read AGENTS.md" (just reading, not updating)
• "What is AGENTS.md?" (general question)
• "Edit the AGENTS.md file" (direct edit, not skill workflow)

References

• references/agmd-template.md — Minimal AGENTS.md template (70-100 lines)
• references/pre-commit-hook.sh — sem-based staleness detection hook
• references/github-action-guard.yml — Optional CI guard workflow

Rollback

If a generated AGENTS.md turns out to be bad days or weeks later:

git revert <commit>  # restore previous AGENTS.md
# then re-run this skill with the old file as the starting point

The skill is idempotent: re-running on an existing file goes through Phase 1.5 classification (Bucket A/B/C) and applies the right path. Recovery does not require a special "undo" path.