Skip to content

feat(init): write a root AGENTS.md and CLAUDE.md - #264

Merged
Bccorb merged 1 commit into
mainfrom
feat/init-root-agents-md
Oct 9, 2026
Merged

Bccorb merged 1 commit into
mainfrom
feat/init-root-agents-md

Conversation

@Bccorb

@Bccorb Bccorb commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Part of fells-code/seamless-auth-api#383

What

seamless init now writes a root AGENTS.md and a CLAUDE.md containing See @AGENTS.md, next to docker-compose.yml and seamless.config.json. Each starter directory already ships its own guide (fells-code/seamless-templates#115); the root one says how they fit together.

The content comes from a pure function, buildAgentsMd in src/generators/agents/agents.ts, built from the init choices:

  • which directories exist and which template each came from, linking web/AGENTS.md, api/AGENTS.md, mobile/AGENTS.md
  • how the auth server runs (Docker image, or auth/ source run by compose in local mode), or the managed instance
  • admin console mode and URL, ports from the generated compose
  • how to start the stack (docker compose up, matching init's next steps; per-service commands for managed), seamless check
  • the owner email becoming the first admin, and where OWNER_EMAIL lives for that auth mode
  • the rules block (no hand-rolled JWT, password, session cookie or login endpoint code; use the SDK in web/ and the adapter in api/) and https://docs.seamlessauth.com/llms.txt

Both files are written unconditionally, like the compose file and seamless.config.json, so --force into a non-empty directory replaces them the same way.

Notes

  • The pinned templates release (v0.17.0) predates chore: bump seamless auth-api, admin dashboard, and templates versions #115, so its starters have no AGENTS.md yet. init checks for the file after copying and links the starter's README.md instead, so the guide never links to nothing. Once templates are released and SEAMLESS_TEMPLATES_REF is bumped, the links switch to AGENTS.md with no further change.
  • seamless add does not write project root files (its stack goes under seamless/), so it is unchanged.

Testing

  • Unit tests for web+api on docker, full-stack Next.js, with mobile, auth from local source, admin none, managed, and the README fallback; init tests assert what is passed in.
  • End to end: init my-app --local --yes --email=you@example.com </dev/null, --nextjs, and --mobile --auth=local (the latter two with SEAMLESS_TEMPLATES_REF=main to see the AGENTS.md links resolve).
  • npm run build, npm test, npm run coverage, npm run check:types-current, npm run check:templates-pin all pass.

…roject

The guide is built from the choices init made: each starter's directory and
template (linking its own AGENTS.md, or its README on templates releases that
ship none), how the auth server runs, the admin console, ports, how to start
the stack, the first admin, and the rules for agents. CLAUDE.md is
'See @AGENTS.md' so Claude Code loads it. Written for local and managed
scaffolds alike.
@Bccorb
Bccorb merged commit c8506a9 into main Oct 9, 2026
5 checks passed
@Bccorb
Bccorb deleted the feat/init-root-agents-md branch October 15, 2026 03:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant