Skip to content

[feature] Emit AGENTS.md from spec for cross-host interop #199

Description

@yuyu04

What problem does this solve

cladding authors CLAUDE.md to carry project/agent instructions, but that file is read only by Claude-family hosts. The vendor-neutral, Linux-Foundation-stewarded AGENTS.md standard (https://agents.md/) is now read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Zed, and others (60k+ repos). Since cladding already targets three hosts (Claude Code / Codex / Gemini CLI), its spec-derived context is stranded behind a Claude-only filename — other agents in the same repo don't see it.

Proposed shape

Generate/maintain an AGENTS.md alongside CLAUDE.md, derived from the same sources cladding already owns:

  • spec.yaml::project + ai_hints (preferred persona, forbidden/preferred patterns, primary branch, test framework)
  • docs/conventions.md (style derived from code)

Emit it during clad init / clad sync so it stays in step. cladding's own AGENTS.md already exists for code-style — this is about generating one for adopting projects from their spec.

Versioning scope (GOVERNANCE.md §2)

  • Minor — additive generated artifact (new CLI behavior; doesn't change spec schema)

In-scope check (GOVERNANCE.md §4.1 / §4.2)

  • Not regressing Iron Law conformance
  • Not bypassing the anti-self-cert guard
  • Not forking the Ironclad spec
  • Not cosmetic-only — ships with a test asserting the generated AGENTS.md reflects ai_hints/conventions for a fixture project

Alternatives considered

  • Symlink AGENTS.md → CLAUDE.md — but the two have different intended audiences/sections; a derived file (spec-sourced, host-neutral) is cleaner and keeps CLAUDE.md as the Claude-specific layer.

Willing to implement?

  • Yes — small, high cross-host reach

From a competitive-gap analysis (portability cluster).

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