Skip to content

docs: AGENTS.md as the agent guide; CLAUDE.md imports it; README corrected with a demo GIF - #937

Merged
antosubash merged 8 commits into
mainfrom
docs/refresh-agent-docs
Nov 15, 2026
Merged

antosubash merged 8 commits into
mainfrom
docs/refresh-agent-docs

Conversation

@antosubash

Copy link
Copy Markdown
Owner

Summary

  • AGENTS.md is the repository's agent guide. Codex, Cursor, OpenCode and other agents read it; CLAUDE.md imports it with @AGENTS.md and keeps only the Claude Code rules (subagent models, Codex as a subagent). The content moved from CLAUDE.md, corrected against the code:
    • the full make lint list and the CI jobs (docs-build; alembic check inside ci-doctor);
    • which diagnostics only a dev boot runs (SM012, SM031) and that SM025 runs everywhere;
    • middleware order (Sentry context, fixed tenant);
    • module layout roots (models/, task_config.py, cli.py, DOMAIN_AREAS);
    • what make new-module generates (pages/api.generated.ts).
      History that the linked docs already hold (migration revision ids, scaffolder internals) was trimmed; every rule stays.
  • README restructured and corrected.
    • A demo GIF at the top.
    • A build-an-app path: the /setup wizard, presets, uv run smpy ….
    • A table of the 17 bundled modules.
    • make dev needs ../dev-services, with the SQLite-only alternative.
    • make migration LABEL=….
    • DB-backed configuration and the generated SM_SECRET_KEY.
    • Only permissions needs users under Keycloak.
    • Signup and base_url are settings.
    • An AGENTS.md / smpy skills add pointer.
  • Demo GIF: scripts/record_readme_demo.py drives a running stack with Playwright and converts the video with ffmpeg. docs/assets/readme-demo.gif is 720 px, 10 fps, 23 s, 4.05 MiB. Feature flags have no create UI, so the GIF toggles one.
  • Tooling: make ci-doc-paths also checks AGENTS.md, with a test. Comments that cited CLAUDE.md sections point at AGENTS.md. The same stale settings facts are fixed in modules/users/README.md and docs/framework-conventions.md.

Design: docs/superpowers/specs/2026-11-15-refresh-agent-docs-design.md. Plan: docs/superpowers/plans/2026-11-15-refresh-agent-docs.md.

Verification

  • Local CI:
    • make lint ✅
    • PYTEST_WORKERS=8 make test-py ✅ (8489 passed, 49 skipped)
    • make test-js ✅ (909 passed)
  • The GIF was recorded against a live SQLite stack. I checked frames from every step: no error pages, no blank frames.
  • Code review: two passes with two reviewers each. Both passes checked every factual claim in AGENTS.md and the README against source. Rejected findings and their reasons are in the review notes.
  • No browser QA: no app page changes.
  • Verification report: https://claude.ai/artifact/BMRnTEgwt3sMmN62x3KchB

Report links are Claude Artifacts and start private. The author can share them from claude.ai/code/artifacts if reviewers need access.

Test plan

  • CI is green
  • The README renders the GIF on GitHub
  • A Claude Code session in the repo loads AGENTS.md through the @AGENTS.md import

https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4

…orts it

Moves CLAUDE.md's conventions into a tool-neutral AGENTS.md, corrected against the code (lint and CI checks, dev-boot-only diagnostics, middleware order, module layout roots, new-module outputs) and trimmed of history the linked docs hold. CLAUDE.md keeps the Claude Code subagent and Codex rules. check_doc_paths now scans AGENTS.md.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
scripts/record_readme_demo.py drives a running dev stack with Playwright and converts the video with ffmpeg; docs/assets/readme-demo.gif is its output (720 px, 10 fps, 23 s, 4 MB).

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
Build-an-app path with the /setup wizard and presets, a bundled-modules table, the dev-services caveat for make dev, make migration LABEL=..., DB-backed configuration and the generated SM_SECRET_KEY, the real Keycloak dependency (permissions), signup as a setting, and an AGENTS.md pointer.

Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
🔒 Security Review ✅ Completed 2026-11-15T12:35:17.998981Z d9ca89f PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying simple-module-python with  Cloudflare Pages  Cloudflare Pages

Latest commit: d9ca89f
Status: ✅  Deploy successful!
Preview URL: https://356d90aa.simple-module-python.pages.dev
Branch Preview URL: https://docs-refresh-agent-docs.simple-module-python.pages.dev

View logs

@antosubash
antosubash merged commit d98d0be into main Nov 15, 2026
17 checks passed
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