feat: init command should scaffold AGENTS.md template

[mickume]

Summary

The init command should copy an AGENTS.md template to the project root if the file does not already exist. This gives coding agents (Claude Code, Cursor, Codex, etc.) project-specific instructions from day one.

Context

AGENTS.md is already referenced in the codebase:

• agent_fox/fix/analyzer.py:44 — _CONVENTION_FILES = ("CLAUDE.md", "AGENTS.md", "README.md") — the analyzer loads conventions from one of these files
• Skills af-spec and af-fix mention AGENTS.md in their documentation

But init never creates it. Users have to know about the convention and write the file manually.

Requirements

1. Create an AGENTS.md template — either as a static file in agent_fox/_templates/ or generated inline (like config.toml)
2. During agent-fox init, write the template to {project_root}/AGENTS.md only if the file does not already exist (idempotent, same pattern as .claude/settings.local.json)
3. Re-init (agent-fox init on existing project) should not overwrite a user-modified AGENTS.md
4. Template content should include agent-fox-specific instructions: spec-driven workflow, branch conventions (develop/feature/*), make check before committing, and pointers to .specs/ and docs/

Implementation Notes

• init is defined in agent_fox/cli/init.py:92-184
• The command has no template-copy mechanism today — everything is generated inline or via Pydantic introspection. A simple Path.write_text() with an existence check is sufficient.
• Consider using importlib.resources or Path(__file__) to locate the template if stored as a static file

Open Questions

• Should the template be minimal (section headers only, user fills in) or pre-populated with agent-fox conventions?
• Should it be git-tracked by default, or added to .gitignore? (Recommendation: git-tracked, since it's project-specific configuration for agents)

[mickume]

Finalized PRD

This PRD was generated from this issue using the af-spec skill.
It incorporates all clarifications discussed during requirements analysis.

PRD: Init Command — Scaffold AGENTS.md Template

Problem

AGENTS.md is referenced throughout the agent-fox codebase as a project
convention file for coding agents. The auto-improve analyzer
(agent_fox/fix/analyzer.py) searches for it in _CONVENTION_FILES, and
skills (af-spec, af-fix) mention it in their documentation. However, the
init command never creates it — users must know about the convention and
write the file manually.

Solution

Extend the agent-fox init command to scaffold an AGENTS.md file in the
project root. The template is a static file bundled in
agent_fox/_templates/agents_md.md. The file is copied verbatim on first
init; re-init skips the copy if the file already exists (user content is
never overwritten).

The template content is the current AGENTS.md from the agent-fox repository
itself — it provides a well-structured starting point covering orientation
steps, project structure, spec-driven workflow, quality commands, git
workflow, and session completion criteria.

Requirements

1. Bundle a static AGENTS.md template at
   agent_fox/_templates/agents_md.md. The template content is a copy of
   the existing AGENTS.md from this repository.

2. During agent-fox init (fresh project), copy the template to
   {project_root}/AGENTS.md using UTF-8 encoding. Log a user-facing
   message: Created AGENTS.md.

3. During agent-fox init (re-init on existing project), check whether
   {project_root}/AGENTS.md already exists. If it does, skip the copy
   silently (no message, no warning). If it does not exist, copy the
   template and log: Created AGENTS.md.

4. The existence of CLAUDE.md in the project root does NOT affect whether
   AGENTS.md is created. Both files may coexist.

5. AGENTS.md is user-owned content intended to be git-tracked. It MUST NOT
   be added to .gitignore by init.

6. In --json mode, include an "agents_md" field in the JSON output
   indicating the action taken: "created" if the file was written,
   "skipped" if it already existed.

Implementation Notes

• init is defined in agent_fox/cli/init.py:92-184.
• The template should be loaded using Path(__file__) relative resolution
  (consistent with how _templates/prompts/ are loaded in
  agent_fox/session/prompt.py).
• The copy logic follows the same pattern as _ensure_claude_settings():
  check existence, write if absent, skip if present.
• No merge or update logic on re-init — the file is user-owned once created.

Dependencies

This spec has no cross-spec dependencies.

Clarifications

• Template content: Verbatim copy of the existing AGENTS.md from this
  repository. The template is a generic starting point; users customize it
  for their project.
• Template storage: Static file at agent_fox/_templates/agents_md.md,
  loaded via Path(__file__) resolution. Not generated inline.
• CLAUDE.md interaction: AGENTS.md is always created regardless of
  whether CLAUDE.md exists. The analyzer's _CONVENTION_FILES priority
  order is unchanged.
• JSON mode: The {"status": "ok"} response gains an "agents_md"
  field with value "created" or "skipped".
• Logging: User-facing click.echo only. Message shown only when file
  is created, not when skipped.
• Encoding: UTF-8.
• File location: Path.cwd() / "AGENTS.md" — project root.

[mickume]

Finalized PRD (Updated)

This PRD was generated from this issue using the af-spec skill.
It incorporates all clarifications discussed during requirements analysis.
Update: Template uses generalized placeholder markers instead of verbatim copy.

PRD: Init Command — Scaffold AGENTS.md Template

Problem

AGENTS.md is referenced throughout the agent-fox codebase as a project
convention file for coding agents. The auto-improve analyzer
(agent_fox/fix/analyzer.py) searches for it in _CONVENTION_FILES, and
skills (af-spec, af-fix) mention it in their documentation. However, the
init command never creates it — users must know about the convention and
write the file manually.

Solution

Extend the agent-fox init command to scaffold an AGENTS.md file in the
project root. The template is a static file bundled in
agent_fox/_templates/agents_md.md. The file is copied verbatim on first
init; re-init skips the copy if the file already exists (user content is
never overwritten).

The template content is a generalized version of the AGENTS.md from the
agent-fox repository, with project-specific paths replaced by placeholder
markers (e.g., <main_package>/) that users fill in for their project.

Requirements

1. Bundle a static AGENTS.md template at
   agent_fox/_templates/agents_md.md. The template content is a
   generalized version of the existing AGENTS.md from this repository,
   with project-specific references replaced by placeholder markers.

2. During agent-fox init (fresh project), copy the template to
   {project_root}/AGENTS.md using UTF-8 encoding. Log a user-facing
   message: Created AGENTS.md.

3. During agent-fox init (re-init on existing project), check whether
   {project_root}/AGENTS.md already exists. If it does, skip the copy
   silently (no message, no warning). If it does not exist, copy the
   template and log: Created AGENTS.md.

4. The existence of CLAUDE.md in the project root does NOT affect whether
   AGENTS.md is created. Both files may coexist.

5. AGENTS.md is user-owned content intended to be git-tracked. It MUST NOT
   be added to .gitignore by init.

6. In --json mode, include an "agents_md" field in the JSON output
   indicating the action taken: "created" if the file was written,
   "skipped" if it already existed.

Clarifications

• Template content: Generalized version of the existing AGENTS.md from
  this repository with placeholder markers (e.g., <main_package>/,
  <test_directory>/). Users customize the placeholders for their project.
• Template storage: Static file at agent_fox/_templates/agents_md.md,
  loaded via Path(__file__) resolution. Not generated inline.
• CLAUDE.md interaction: AGENTS.md is always created regardless of
  whether CLAUDE.md exists. The analyzer's _CONVENTION_FILES priority
  order is unchanged.
• JSON mode: The {"status": "ok"} response gains an "agents_md"
  field with value "created" or "skipped".
• Logging: User-facing click.echo only. Message shown only when file
  is created, not when skipped.
• Encoding: UTF-8.
• File location: Path.cwd() / "AGENTS.md" — project root.