agentsmd-hierarchy 1.0.0

package/README.md

@@ -0,0 +1,212 @@
+# AGENTS Hierarchy
+
+> A sharp little CLI and installable skill bundle for keeping layered `AGENTS.md` docs accurate, readable, and in sync with your repo.
+
+`agentsmd-hierarchy` packages two things together:
+
+- A CLI for checking, scaffolding, and refreshing hierarchical `AGENTS.md` files
+- An installable skill bundle you can drop into Codex, Claude Code, Cursor, or a Codex plugin directory
+
+## Why This Exists
+
+Large repos get messy fast. `AGENTS.md` files work best when they behave like a map: each directory explains its immediate children, local writing rules, and how guidance cascades down the tree.
+
+That keeps any single `AGENTS.md` lighter, which reduces context load and can improve model performance. It is useful for humans too, because the same hierarchy makes the project's structure easier to understand.
+
+This package helps you keep that map healthy without hand-maintaining everything:
+
+- Validate stale or malformed `AGENTS.md` files
+- Scaffold missing docs for new directories
+- Refresh inventory sections after the tree changes
+- Install the skill where your agent tooling can actually use it
+
+## Works With
+
+| Tool        | Install Shape                 |
+| ----------- | ----------------------------- |
+| Codex       | Skill bundle or plugin bundle |
+| Claude Code | Skill bundle                  |
+| Cursor      | Command file                  |
+
+## Quick Start
+
+If you just want to install it and go:
+
+```bash
+npx -y agentsmd-hierarchy install
+```
+
+That launches an interactive installer and lets you choose the target tool and scope.
+
+If you prefer deterministic installs:
+
+```bash
+npx -y agentsmd-hierarchy install --tool codex --scope personal --no-prompt
+```
+
+If you want the command available on your `PATH`:
+
+```bash
+npm install -g agentsmd-hierarchy
+```
+
+## Install Options
+
+### Personal install
+
+```bash
+npx -y agentsmd-hierarchy install --tool codex --scope personal --no-prompt
+```
+
+```bash
+npx -y agentsmd-hierarchy install --tool claude --scope personal --no-prompt
+```
+
+```bash
+npx -y agentsmd-hierarchy install --tool cursor --scope personal --no-prompt
+```
+
+### Project install
+
+Run this from inside a git repo, or pass `--project-root`.
+
+```bash
+npx -y agentsmd-hierarchy install --tool codex --scope project --no-prompt
+```
+
+```bash
+npx -y agentsmd-hierarchy install --tool claude --scope project --no-prompt
+```
+
+```bash
+npx -y agentsmd-hierarchy install --tool cursor --scope project --no-prompt
+```
+
+### Export a Codex plugin bundle
+
+```bash
+npx -y agentsmd-hierarchy install \
+  --tool codex \
+  --mode plugin \
+  --dest ./plugins/agentsmd-hierarchy \
+  --no-prompt
+```
+
+## CLI Commands
+
+Once installed globally, or via `npx`, the main workflow looks like this:
+
+```bash
+agentsmd-hierarchy check .
+agentsmd-hierarchy fix .
+agentsmd-hierarchy scaffold src/components
+```
+
+### `check [path]`
+
+Validate `AGENTS.md` files without changing them.
+
+```bash
+agentsmd-hierarchy check packages/app
+agentsmd-hierarchy check . --strict-placeholders
+```
+
+### `fix [path]`
+
+Refresh missing or stale `AGENTS.md` files.
+
+```bash
+agentsmd-hierarchy fix .
+agentsmd-hierarchy fix tests
+```
+
+### `sync [path]`
+
+Compatibility alias for `fix`.
+
+```bash
+agentsmd-hierarchy sync .
+```
+
+### `scaffold <dir>`
+
+Create the first `AGENTS.md` for a repo-relative directory.
+
+```bash
+agentsmd-hierarchy scaffold src/features/payments
+```
+
+### `install`
+
+Install the packaged skill bundle into a supported tool.
+
+```bash
+agentsmd-hierarchy install --tool codex --scope project --no-prompt
+```
+
+Helpful flags:
+
+- `--debug` for structured troubleshooting output
+- `--dry-run` to preview changes
+- `--json` to emit install summaries as JSON
+- `--force` to replace unmanaged destinations
+
+## What Gets Installed
+
+Depending on the target, this package installs:
+
+- A full skill bundle under `.codex/skills/agentsmd-hierarchy/`
+- A full skill bundle under `.claude/skills/agentsmd-hierarchy/`
+- A Cursor command file under `.cursor/commands/agentsmd-hierarchy.md`
+- A Codex plugin bundle at the destination you choose
+
+The shipped skill teaches agents to:
+
+- Read the `AGENTS.md` chain from repo root to target path
+- Treat each file as documentation for immediate children only
+- Use bundled helpers to validate and scaffold docs deterministically
+- Keep parent and child `AGENTS.md` files aligned as the tree evolves
+
+## Local Development
+
+This repo ships the published package contents and the tests that back them.
+
+```bash
+npm install
+npm test
+```
+
+The published npm package includes:
+
+- `bin/` for the executable entrypoint
+- `agentsmd-hierarchy/` for the distributable skill bundle and helper scripts
+
+## Releases
+
+This repo uses Changesets for versioning and npm publishing.
+
+Release steps:
+
+1. Run `npm run changeset` for each user-facing change and commit the resulting file under `.changeset/`.
+2. Merge those changesets to `main`.
+3. In GitHub, open `Actions` and run the `Release` workflow manually.
+4. Wait for the workflow to open or update the release PR with the version bump and changelog changes.
+5. Review and merge that release PR into `main`.
+6. In GitHub, run the `Release` workflow manually again from `main`.
+7. Wait for the workflow to publish the package to npm.
+
+During publish, the workflow also creates the matching GitHub tag and GitHub Release automatically, so npm releases and GitHub releases stay aligned.
+
+## Requirements
+
+- Node.js `>=20`
+
+## Contributing
+
+Contribution PRs are welcome.
+
+For user-facing changes, please include a Changeset by running `npm run changeset` and committing the generated file under `.changeset/` alongside your update.
+
+## License
+
+MIT

package/agentsmd-hierarchy/AGENTS.md

@@ -0,0 +1,21 @@
+# agentsmd-hierarchy
+
+Distributable skill bundle for AGENTS Hierarchy, combining the main skill instructions with agent metadata, reference docs, and bundled helper scripts.
+
+## Directories
+
+- `agents/`: Agent integration metadata for tool registries.
+- `references/`: Convention docs and example AGENTS files that support the skill instructions.
+- `scripts/`: Bundled helper CLIs and shared implementation used by the skill workflow.
+  Rules:
+  - Keep command entrypoints small and move reusable behavior into `scripts/lib/`.
+
+## Files
+
+- `SKILL.md`: Primary skill instructions that describe the AGENTS hierarchy workflow and preferred bundled commands.
+
+## Writing Rules
+
+- Keep `SKILL.md`, `agents/openai.yaml`, and the bundled scripts aligned so the documented workflow matches actual behavior.
+- Put reusable CLI logic under `scripts/lib/` and reserve top-level script files for thin entrypoints or prompt helpers.
+- Keep references focused on conventions and examples that the skill explicitly points users to.

package/agentsmd-hierarchy/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: agentsmd-hierarchy
+description: Navigate and maintain repositories that use hierarchical AGENTS.md files, where each directory AGENTS.md describes its immediate children, local writing rules, and cascading repo guidance. Use when Codex needs to understand a repo through AGENTS.md, follow AGENTS instructions before editing, or use repo CLI helpers to scaffold, sync, validate, or update AGENTS.md files after files or directories change.
+---
+
+# AGENTS Hierarchy
+
+## Overview
+
+Read `AGENTS.md` files as a layered map of the repository. Start at the repo root, walk down to the target path, use those files to decide what to open next, and keep the hierarchy current when the directory inventory changes.
+
+## Read the Chain
+
+1. Locate the repository root `AGENTS.md`.
+2. Read each `AGENTS.md` from root to the target directory in order.
+3. Apply parent guidance first, then let deeper `AGENTS.md` files narrow or override the rules for their own subtree.
+4. Use directory summaries and file bullets to decide which source files to inspect.
+5. When the target is a repo-local skill package, still read parent `AGENTS.md` files such as `.codex/AGENTS.md`; stop only because the skill package itself should not contain a nested `AGENTS.md`.
+
+## Interpret the Format
+
+- Treat each `AGENTS.md` as documentation for that directory's immediate children only.
+- Read `## Writing Rules` as the local policy for edits in that directory.
+- Treat indented `Rules:` blocks under child bullets as the most specific guidance for that item.
+- Use `## Generated Files` to spot artifacts that should usually be regenerated instead of hand-edited.
+- Do not expect one `AGENTS.md` to fully describe grandchildren; walk deeper in the tree when needed.
+
+## Respect Skill Package Exceptions
+
+- Do not add `AGENTS.md` files inside repo-local skill packages under `.codex/skills/` unless the repository explicitly asks for that pattern.
+- Use `SKILL.md`, `agents/openai.yaml`, and `references/` as the documentation surface for a skill package.
+- Treat the repo root `AGENTS.md` as enough context to discover that the repo contains local skills.
+
+## Update the Hierarchy
+
+- Audit the directory's immediate tracked children before editing so `## Directories`, `## Files`, and `## Generated Files` reflect the current inventory.
+- Prefer checking tracked paths with repository tooling such as `git ls-files` when available, then fall back to the filesystem when needed.
+- Update the current directory `AGENTS.md` whenever immediate files or subdirectories are added, removed, renamed, or materially repurposed.
+- Update the parent directory `AGENTS.md` when a child directory changes role or inventory.
+- Keep descriptions brief, behavioral, and focused on why a file or directory exists.
+- Keep file-specific rules inline on the relevant file bullet unless the repo explicitly wants the same rule duplicated in source comments.
+
+## Scaffold Carefully
+
+- Prefer the bundled AGENTS tool first when a directory needs its first `AGENTS.md`; use manual drafting only when the helper does not fit the task.
+- Use the bundled script path for the current skill package, such as `node .codex/skills/agentsmd-hierarchy/scripts/validate-agents.mjs --fix <repo-relative-directory>`.
+- Replace placeholders with real summaries before considering the directory documented.
+- Recheck the immediate child inventory before finishing so `## Directories`, `## Files`, and `## Generated Files` stay complete.
+
+## Use Repo Helpers
+
+Treat the bundled CLI helpers in this skill package as part of the skill:
+
+- Use [scripts/validate-agents.mjs](scripts/validate-agents.mjs) with `--check` to validate AGENTS structure, inventory correctness, and missing AGENTS.md files.
+- Use [scripts/validate-agents.mjs](scripts/validate-agents.mjs) with `--fix` to scaffold missing AGENTS.md files and refresh inventory sections while preserving compatible descriptions and rules.
+- Add `--debug` to these bundled scripts when you need extra visibility into repo-root resolution, inventory discovery, scope selection, or validation counts.
+- Prefer these bundled scripts before recreating scaffold, sync, or validation logic manually.
+- Use manual `AGENTS.md` edits to refine descriptions, rules, or edge cases around the script output, not to replace deterministic script work the helpers already cover.
+- Let the bundled scripts read repo-specific inventory exclusions from the root `AGENTS.md` `## AGENTS Hierarchy` section when that section lists excluded paths.
+- Run the bundled scripts from the repository root so they can treat the current working directory as the repo root by default.
+- Do not assume the repository exposes package-manager wrappers such as `pnpm`, `npm`, or `yarn` scripts; use the bundled script path unless the user explicitly asks for a repo-local wrapper.
+- Treat support modules in this directory, such as `scripts/cli-logger.mjs`, as internal implementation helpers for the CLIs rather than direct end-user commands.
+
+## Preferred CLI Workflow
+
+1. Read the AGENTS chain for the target path.
+2. Use the bundled AGENTS tool as the skill's default deterministic workflow whenever it covers the task.
+3. Use `node .codex/skills/agentsmd-hierarchy/scripts/validate-agents.mjs --fix <repo-relative-path>` after structural changes so missing AGENTS.md files are scaffolded and inventory sections match the current tree.
+4. Make any manual `AGENTS.md` edits that are still needed for descriptions, rules, or special cases the script cannot infer.
+5. Use `node .codex/skills/agentsmd-hierarchy/scripts/validate-agents.mjs --check <repo-relative-path-or-agents-file>` before finishing to verify the AGENTS structure, inventory, and required-file coverage deterministically.
+6. Add `--debug` to check or fix runs when you need the helper script to explain what it discovered and why it made a decision.
+
+## Load the Reference
+
+Open [references/agents-convention.md](references/agents-convention.md) when you need the canonical section layout, update checklist, or generated-file guidance.
+
+Open one of these example files when you want a concrete pattern to imitate:
+
+- [references/example-simple-flat-directory.md](references/example-simple-flat-directory.md)
+- [references/example-simple-test-helpers.md](references/example-simple-test-helpers.md)
+- [references/example-complex-package-root.md](references/example-complex-package-root.md)
+- [references/example-complex-source-directory.md](references/example-complex-source-directory.md)

package/agentsmd-hierarchy/agents/AGENTS.md

@@ -0,0 +1,16 @@
+# agentsmd-hierarchy/agents
+
+Agent registry metadata for the skill bundle, used to present the skill name, summary, and default prompt in supported tools.
+
+## Directories
+
+- None.
+
+## Files
+
+- `openai.yaml`: OpenAI/Codex-facing metadata for the skill's display name, summary, and default prompt.
+
+## Writing Rules
+
+- Keep metadata aligned with the name, scope, and workflow described in `../SKILL.md`.
+- Prefer concise user-facing copy that reflects the actual bundled commands and behavior.

package/agentsmd-hierarchy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'AGENTS Hierarchy'
+  short_description: 'Navigate and prefer bundled CLI helpers to scaffold, sync, validate, and maintain layered AGENTS.md files'
+  default_prompt: "Use $agentsmd-hierarchy to read this repository's AGENTS.md chain, follow the local rules, prefer the bundled or matching repo CLI helpers for scaffold, sync, and validation work before manual AGENTS editing, add --debug to those helper scripts when extra trace detail would help, then validate the result before finishing."

package/agentsmd-hierarchy/references/AGENTS.md

@@ -0,0 +1,20 @@
+# agentsmd-hierarchy/references
+
+Reference material that backs the skill instructions, including the canonical AGENTS convention and copy-pastable example layouts.
+
+## Directories
+
+- None.
+
+## Files
+
+- `agents-convention.md`: Canonical section layout, update checklist, and validation guidance for directory-level `AGENTS.md` files.
+- `example-complex-package-root.md`: Example AGENTS file for a package root with child directories, config files, and generated artifacts.
+- `example-complex-source-directory.md`: Example AGENTS file for a source subtree with generated files and file-specific rules.
+- `example-simple-flat-directory.md`: Example AGENTS file for a small directory that only contains files.
+- `example-simple-test-helpers.md`: Example AGENTS file for a compact helper-oriented test directory.
+
+## Writing Rules
+
+- Keep the convention document aligned with the behavior enforced by the bundled validator.
+- Keep example files small, valid Markdown, and clearly matched to the directory shape named in the filename.

package/agentsmd-hierarchy/references/agents-convention.md

@@ -0,0 +1,94 @@
+# AGENTS Convention
+
+## Required Layout
+
+Use this format for each directory-level `AGENTS.md`:
+
+1. `# <repo-relative-directory>`
+2. A brief overview paragraph
+3. `## Directories`
+4. `## Files`
+5. Optional `## Generated Files`
+6. `## Writing Rules`
+
+Document only the directory's immediate children. Do not list grandchildren in the current file.
+
+## Section Rules
+
+### Directories
+
+- Format each entry as `- \`name/\`: description`.
+- When a child directory needs special handling, add an indented `Rules:` label below the bullet and list one or more rule bullets beneath it.
+- Describe the child directory's purpose, not every file inside it.
+- List only immediate child directories.
+
+### Files
+
+- Format each entry as `- \`name.ext\`: description`.
+- When a file needs special handling, add an indented `Rules:` label below the bullet and list one or more rule bullets beneath it.
+- Exclude the local `AGENTS.md`.
+
+### Generated Files
+
+- Use this section for tracked generated artifacts such as lockfiles, `*.gen.*` files, or packaged archives.
+- State how the artifact should usually be refreshed.
+- Keep generated-file rule bullets short and actionable.
+
+### Writing Rules
+
+- Keep 2-6 concise bullets.
+- Focus on how to edit files in the directory, not on general coding advice already covered higher in the tree.
+- Avoid self-referential reminders about updating the `AGENTS.md`; use the bullets for concrete local editing guidance.
+
+## Cascading Behavior
+
+- Read `AGENTS.md` files from root to leaf.
+- Apply parent rules first.
+- Let child `AGENTS.md` files add local detail or override the parent for their own subtree.
+- Let child-bullet `Rules:` blocks win for that specific file or directory.
+
+## Skill Package Exception
+
+- Do not add `AGENTS.md` inside repo-local skill packages under `.codex/skills/` unless the repository explicitly asks for that.
+- Use `SKILL.md`, `agents/openai.yaml`, and `references/` to document skills instead.
+- It is fine for a repo root `AGENTS.md` to mention `.codex/` or local skills at a high level without creating nested skill-package `AGENTS.md` files.
+
+## Update Checklist
+
+Before editing, verify the directory's immediate tracked children so the file matches the current inventory. Prefer repository-aware listings such as `git ls-files` when available, then fall back to the filesystem for untracked local work.
+
+Update a directory `AGENTS.md` when:
+
+- A tracked file is added, removed, renamed, or materially repurposed.
+- A subdirectory is added, removed, renamed, or materially repurposed.
+- Local writing rules change.
+- A file becomes generated or stops being generated.
+
+Update the parent `AGENTS.md` too when the identity of a child directory changes.
+
+## Scaffolding Guidance
+
+- Use the skill's bundled `scripts/scaffold-agents.mjs` helper or the repo's matching helper when it exists.
+- Prefer the helper over hand-writing a first draft when the helper covers the task.
+- Treat scaffold output as a draft, not finished documentation.
+- Replace placeholder text before finishing the task.
+
+## Sync Guidance
+
+- Use the skill's bundled `scripts/sync-agents.mjs` helper or the repo's matching helper when it exists to refresh `## Directories`, `## Files`, and `## Generated Files` from the current repo inventory.
+- Prefer the helper over manually rebuilding inventory sections when the helper covers the task.
+- Let sync and validation helpers read repo-specific excluded inventory paths from the root `AGENTS.md` `## AGENTS Hierarchy` section when that section lists exclusions.
+- Let sync helpers preserve existing descriptions and writing rules when possible, then review any placeholder text they leave behind.
+
+## Validation Guidance
+
+- Use the skill's bundled `scripts/validate-agents.mjs` helper or the repo's matching helper when it exists to check title, overview, section layout, entry formatting, writing-rule count, and AGENTS package exclusions.
+- Prefer the validator over ad hoc manual checking so the skill ends with deterministic structure validation.
+- Placeholder descriptions may remain when the task allows them; use stricter placeholder validation only when the repo or task requires finished descriptions.
+
+## Example Files
+
+- For a small flat directory, open [example-simple-flat-directory.md](example-simple-flat-directory.md).
+- For a small helper directory, open [example-simple-test-helpers.md](example-simple-test-helpers.md).
+- For a package root with config, source, and generated files, open [example-complex-package-root.md](example-complex-package-root.md).
+- For a source directory with generated artifacts and file-specific rules, open [example-complex-source-directory.md](example-complex-source-directory.md).

package/agentsmd-hierarchy/references/example-complex-package-root.md

@@ -0,0 +1,37 @@
+# Complex Example: Package Root
+
+Use this example when a package root mixes config files, child directories, and tracked generated artifacts.
+
+```md
+# packages/front
+
+Frontend workspace for routes, components, static assets, and test tooling.
+
+## Directories
+
+- `e2e/`: Playwright suites for real user journeys.
+- `public/`: Static files served directly by the app.
+- `src/`: Application code for routes, components, and shared libraries.
+
+## Files
+
+- `.env.example`: Example frontend environment variables.
+  Rules:
+  - Keep it aligned with runtime env usage.
+- `package.json`: Frontend package manifest and scripts.
+  Rules:
+  - Keep scripts aligned with Vite and Playwright config.
+- `playwright.config.ts`: Playwright configuration for browser coverage.
+- `vite.config.ts`: Vite dev and build configuration.
+
+## Generated Files
+
+- `package-lock.json`: npm lockfile kept for tool compatibility.
+  Rules:
+  - Refresh with npm tooling instead of hand-editing.
+
+## Writing Rules
+
+- Keep package-level tooling files at the root and product code under `src/`.
+- Push feature-specific behavior into `src/` rather than package-level config files.
+```

package/agentsmd-hierarchy/references/example-complex-source-directory.md

@@ -0,0 +1,34 @@
+# Complex Example: Source Directory with Generated Artifacts
+
+Use this example when a source directory has child directories, authored files, generated files, and a few file-specific rules.
+
+```md
+# packages/front/src
+
+Frontend application source for route definitions, UI components, and bootstrapping.
+
+## Directories
+
+- `components/`: Shared UI grouped by feature or abstraction level.
+- `lib/`: Reusable app logic, API helpers, and route utilities.
+- `routes/`: File-based route modules.
+
+## Files
+
+- `router.tsx`: Router factory and router registration.
+- `start.ts`: App bootstrap and server middleware wiring.
+- `styles.css`: Global styles and design tokens.
+  Rules:
+  - Keep shared tokens centralized here instead of duplicating them in components.
+
+## Generated Files
+
+- `routeTree.gen.ts`: Generated route tree.
+  Rules:
+  - Regenerate it through routing tooling instead of hand-editing.
+
+## Writing Rules
+
+- Separate bootstrap, shared logic, components, and routes by responsibility.
+- Treat generated router output as read-only.
+```

package/agentsmd-hierarchy/references/example-simple-flat-directory.md

@@ -0,0 +1,23 @@
+# Simple Example: Flat Utility Directory
+
+Use this example when a directory has only files and no child directories.
+
+```md
+# scripts
+
+Helper scripts for local repo maintenance.
+
+## Directories
+
+- None.
+
+## Files
+
+- `rename-project.js`: Renames the project across package manifests and docs.
+- `verify-preview.mjs`: Checks that the preview app responds on expected routes.
+
+## Writing Rules
+
+- Keep scripts deterministic and safe to run from automation.
+- Keep script names tied to the repo task they automate.
+```

package/agentsmd-hierarchy/references/example-simple-test-helpers.md

@@ -0,0 +1,22 @@
+# Simple Example: Test Helpers Directory
+
+Use this example when a directory is small, focused, and mostly holds helper code for one part of the repo.
+
+```md
+# packages/back/tests/helpers
+
+Shared helpers used by backend test suites.
+
+## Directories
+
+- None.
+
+## Files
+
+- `integration.ts`: Creates reusable setup helpers for backend integration tests.
+
+## Writing Rules
+
+- Keep helpers generic enough to serve multiple suites.
+- Do not hide important assertions inside helper utilities.
+```

package/agentsmd-hierarchy/scripts/AGENTS.md

@@ -0,0 +1,21 @@
+# agentsmd-hierarchy/scripts
+
+Bundled CLI entrypoints and prompt helpers that support the skill's scaffold, sync, and validation workflow.
+
+## Directories
+
+- `lib/`: Shared implementation for logging, install flows, command registration, and AGENTS validation logic.
+
+## Files
+
+- `cli-logger.mjs`: Convenience re-export for the shared CLI logger implementation.
+- `cli-prompts.mjs`: Shared prompt and path-resolution helpers for interactive command flows.
+- `scaffold-agents.mjs`: CLI wrapper that scaffolds AGENTS files for a required repo-relative directory by delegating to the validator in fix mode.
+- `sync-agents.mjs`: Compatibility CLI wrapper that defaults to sync behavior via validator fix mode.
+- `validate-agents.mjs`: Direct CLI entrypoint for AGENTS validation and fix workflows.
+
+## Writing Rules
+
+- Keep executable entrypoints thin and move reusable logic into `lib/`.
+- Preserve repo-relative path handling and `--debug` passthrough across command wrappers.
+- Keep interactive prompts centralized in `cli-prompts.mjs` instead of duplicating prompt logic in entrypoints.

package/agentsmd-hierarchy/scripts/cli-logger.mjs

@@ -0,0 +1 @@
+export { createLogger } from './lib/cli-logger.mjs';