From 36e0da748a14bd0f4ad9ac8d47e755789588d140 Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Sun, 15 Nov 2026 13:07:49 +0100 Subject: [PATCH 1/8] docs: refresh-agent-docs design Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- .../2026-11-15-refresh-agent-docs-design.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md diff --git a/docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md b/docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md new file mode 100644 index 00000000..afcb0eb2 --- /dev/null +++ b/docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md @@ -0,0 +1,128 @@ +# Refresh AGENTS.md, CLAUDE.md and README (with a demo GIF) + +## Goal and scope + +Bring the three entry-point docs back in line with the code at `main@ab178587`, add a tool-neutral +`AGENTS.md`, and put a short demo GIF at the top of the README. + +In scope: `AGENTS.md` (new), `CLAUDE.md`, `README.md`, a reproducible GIF recorder script, the +committed GIF, the doc-path checker, and the handful of comments that cite CLAUDE.md sections. + +Out of scope: the VitePress docs (`docs/**`) beyond what a moved reference needs, `skills/**` +(none of them cites CLAUDE.md or AGENTS.md), and generating agent files for `smpy new` apps. + +## Approach + +**`AGENTS.md` is the canonical agent guide; `CLAUDE.md` imports it.** Codex, Cursor, OpenCode and +other agents read `AGENTS.md`; Claude Code reads `CLAUDE.md` and follows its `@AGENTS.md` import. +`CLAUDE.md` keeps only what is Claude Code specific: the `Agent` tool model routing and the Codex +subagent rules from "Working in parallel". + +Rejected: +- Symlink `CLAUDE.md -> AGENTS.md`: symlinks break on Windows checkouts and leave no place for + Claude-only rules. +- Two full copies: they drift, which is the problem this change fixes. + +## Design + +### AGENTS.md (moved from CLAUDE.md, fixed and trimmed) + +Fixes, all verified against the code: +- `make lint` row and CI paragraph: add the locale, doc-path, test-sleep and raw-fetch checks, the + `docs-build` job, and `alembic check` inside `ci-doctor`. +- Doctor vs dev boot: a dev boot adds `SM012`/`SM031`; `SM025` runs at boot in every environment. +- `make new-module` also runs `smpy openapi gen-types`, so `pages/api.generated.ts` is in the + commit list. +- "Full list" of make targets points at the root `Makefile`; `docs/reference/make-commands.md` + covers the scaffolded app's Makefile. +- Middleware order: add Sentry context (when enabled) and the fixed-tenant Tenant middleware when + `default_tenant` is set. +- Module layout: `models/`, `task_config.py`, `cli.py` are allowed roots; extra root dirs only via + `DOMAIN_AREAS` in `host/tests/test_module_layout.py`. +- Package count `~23` PyPI packages. + +Trims (history and API detail that already lives in the linked docs), keeping every "do/don't" +rule: +- Migrations: drop the root/head SHA list and mislabel history; keep "where, `upgrade heads`, + `--head