Skip to content

Add agent onboarding entry points to Json #37

Open

Description

Context and request

Json has no AGENTS.md and no CLAUDE.md. The Repository Standard requires every repository to be usable by an agent that has never seen it before, without special configuration, and names these two files as the required set.

Today an agent entering this repository has no pointer to the PSModule standards, the module conventions, or the framework it is built on. It has to infer all of it from the file tree — which is how a repository ends up drifting from a standard it was never told about.

Acceptance criteria.

  • AGENTS.md exists at the repository root, states in a line or two what this repository is, and points to the canonical agent guidance in PSModule/docs.
  • CLAUDE.md exists at the repository root and imports AGENTS.md with @AGENTS.md.
  • Neither file restates guidance that lives in PSModule/docs; both are pointers.
  • An agent opening the repository with no prior context can follow AGENTS.md to the module standard and the repository standard.

Technical decisions

Both files go at the repository root. The PSModule Repository Standard specifies root placement with CLAUDE.md importing AGENTS.md, and that is what Template-PSModule ships. The MSX Repository Standard specifies .claude/CLAUDE.md instead. The PSModule standard governs module repositories, so root placement wins here.

That discrepancy is a real inconsistency between the two standards pages and should be raised against the docs repositories separately — it is not resolved by this issue, only navigated.

.github/copilot-instructions.md is explicitly optional and is not added. Template-PSModule ships without one, and the standard treats runtime adapter files as something to add only when a runtime needs loading or path rules that AGENTS.md cannot express.

These files stay short. They are the agent equivalent of a README: pointers, not copies, so the linked documentation remains the single source of truth.

Implementation plan

  • Adopt AGENTS.md from Template-PSModule, adjusting only the repository identification line
  • Add CLAUDE.md containing the @AGENTS.md import
  • Confirm both files are at the repository root, not under .github/
  • Verify the links to PSModule/docs resolve
  • Sanity-check by asking an agent with no context what this repository is and how to work in it

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions