# Design: Standardize AGENTS.md to the Janus/Cerberus structure

- **Date:** 2026-05-29
- **Author:** Iván Gómez Yaury
- **Status:** Draft (pending review)
- **Relationship:** Independent of sub-projects 1 and 2, but should land **before**
  sub-project 2's documentation additions so they slot into the restructured file.

## Context

hu-agent already follows the open `AGENTS.md` standard with a `CLAUDE.md` symlink
(`CLAUDE.md -> AGENTS.md`), consistent with the rest of the workspace — that part is
**already done**, no work needed.

What is missing is the **structure** that `humand-janus` and `humand-cerberus` use, which
is more standardized and, importantly, opens with an **Agent Coding Principles** block
that forces agents to self-correct (define success criteria, surgical changes, simplicity,
think-before-coding). hu-agent's current `AGENTS.md` is good content but organized
ad-hoc (sections 1–9) and lacks that principles preamble and the Documentation Rules /
Agent Context Map conventions.

## Goal

Restructure hu-agent's `AGENTS.md` to the shared Janus/Cerberus standard — prepending the
verbatim **Agent Coding Principles** block and reorganizing the existing content under a
**Project-Specific Guidelines** section with the standard subsections — **without losing
any existing content**. Keep a single root `AGENTS.md` (no per-module proliferation).

## Non-Goals

- **No per-module `AGENTS.md`.** Janus/Cerberus are multi-module Maven monorepos; hu-agent
  is a single Bun package. Spawning ~15 per-directory files would be over-engineering and
  high-maintenance. One root `AGENTS.md` with a minimal Agent Context Map.
- **No content loss.** Every fact in the current `AGENTS.md` (commands, layout, conventions,
  safety limits, operational facts, definition of done) is preserved — only reorganized.
- **No symlink work.** `CLAUDE.md -> AGENTS.md` already exists.
- **No behavior/code changes.** Docs only.

## Target structure

```
# hu-agent

## Agent Coding Principles            ← verbatim from janus/cerberus (the self-correction block)
  1. Think Before Coding
  2. Simplicity First
  3. Surgical Changes
  4. Goal-Driven Execution

## Project-Specific Guidelines
  ### Project Overview                ← from current §1 "What this project is"
  ### Module Structure                ← from current §4 "Source layout"
  ### Code Conventions                ← from current §5 "Code conventions"
  ### Documentation Rules             ← NEW (adopt the standard, see below)
  ### Naming Conventions              ← extracted from current §5 (import style, .js, @/ alias)
  ### Feature Creation Workflow       ← from current §6 "Editing rules" + §9 "Definition of done"
  ### Key Commands                    ← from current §3 "Commands you will actually run"
  ### Environment Variables           ← point to utils/config.ts + .env.example (incl. AGENT_PROVIDER, SANDBOX_MODE once they land)
  ### Ports                           ← from current §7 (PORT 3000, mounts under /hu-agent)
  ### Agent Context Map               ← NEW, minimal (root + infrastructure/)
  ### Repo Skills                     ← NEW (list .cursor/skills if any; else "none yet")
```

### The Agent Coding Principles block

Copied **verbatim** from `humand-janus/AGENTS.md` lines 3–33 (identical in cerberus) so it
stays consistent cross-repo. The four principles: *Think Before Coding* (surface
tradeoffs, don't assume), *Simplicity First* (YAGNI), *Surgical Changes* (touch only what
you must, clean up only your own mess), *Goal-Driven Execution* (define verifiable success
criteria, loop until verified). This is the block the user wants for its self-correction
effect.

### Documentation Rules (new section)

Adopt the standard's rule, adapted to hu-agent's single-package shape:

- When adding or changing a feature, update `AGENTS.md` **in the same commit/PR** if the
  change affects cross-cutting concerns (new commands, config env vars, testing patterns,
  tech-stack additions, Docker/infra changes).
- Keep docs minimal — what a developer needs to work in the area, not a changelog. If a
  section no longer reflects the code, fix or remove it.
- Whenever an `AGENTS.md` exists in a directory, verify a `CLAUDE.md` symlink points to it
  (`ln -s AGENTS.md CLAUDE.md`) — Claude Code reads `CLAUDE.md`.
- When adding a new `AGENTS.md`, update the Agent Context Map.

### Agent Context Map (minimal)

| Path | Covers |
|------|--------|
| `AGENTS.md` (root) | Whole service: stack, commands, source layout, conventions, safety limits, operational facts |
| `infrastructure/AGENTS.md` (if/when added) | Terraform IaC (envs, app module, modules) |

Single root file is the source of truth; the map exists so the convention is in place if a
focused `infrastructure/AGENTS.md` is ever added.

## Approach

A careful re-organization of the existing `AGENTS.md`: prepend the principles block, then
move each current section under the matching standard subsection, splitting "Naming
Conventions" out of the current conventions section and adding the three new sections
(Documentation Rules, Agent Context Map, Repo Skills). Verify no bullet from the original
is dropped (diff the old vs new content lists).

## Risks

- **Content drift during the move** — mitigated by a before/after content checklist: every
  fact in the old file maps to a location in the new file. The plan includes this as a
  verification step.
- **Over-restructuring** — resist rewriting the prose; this is a re-org, not a rewrite.
  Match the standard's section names but keep hu-agent's actual content and voice.

## Open questions

- Does hu-agent have repo-local skills under `.cursor/skills/`? If yes, list them in Repo
  Skills; if not, the section says "none yet" (verify at implementation time).