Skip to content

docs: Added CLAUDE.md with AGENTS.md and references - #141

Open
rmad17 wants to merge 19 commits into
mainfrom
feat/claude-md
Open

rmad17 wants to merge 19 commits into
mainfrom
feat/claude-md

Conversation

@rmad17

@rmad17 rmad17 commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Changes

Adds agent guidelines for this SDK as a single AGENTS.md, with the detail behind each section offloaded to a references/ folder. No library code changes.

  • Added AGENTS.md covering the role, working principles, project structure, Always Do / Ask First / Never Do boundaries, and security considerations (algorithm pinning, token-derived hosts, unverified JWT values, organization policy scope, DPoP, token exchange, token store caching and cache keys, the verified= trust boundary, error handling). It reflects the current main, including the client telemetry headers added in feat: send Auth0-Client and User-Agent headers on requests to Auth0 #153.
  • Added references/ files, read on demand from AGENTS.md.
    • commands.md - CI-matching install, test, and lint commands
    • testing.md - fixtures, async test patterns, coverage
    • code-style.md - naming, error patterns, comment rules
    • flow-map.md - entry points, helpers, tests, and docs per flow
    • docs-update.md - tracked docs and a code-to-docs mapping
    • git-workflow.md - branches, commits, PR template, CI workflows, releases
    • pitfalls.md - common failures
  • Added .venv-* to .gitignore.

Why a single AGENTS.md. Other agent tools read AGENTS.md by default, and Claude Code reads a repo-root AGENTS.md directly when no CLAUDE.md exists. A separate CLAUDE.md that AGENTS.md imports with @./CLAUDE.md depends on Claude Code import syntax that other tools may not expand, and means two files to maintain.

Testing

Documentation only. No source, tests, or dependencies changed, so there is no runtime or test impact.

  • This change adds unit test coverage - not applicable, docs only
  • This change adds integration test coverage - not applicable, docs only
  • This change has been tested on the latest version of the platform/language or why not - not applicable, docs only

Checklist

@rmad17
rmad17 requested a review from a team as a code owner October 12, 2026 15:26
rmad17 and others added 4 commits October 28, 2026 23:28
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread AGENTS.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread references/code-style.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
sanchitmehtagit
sanchitmehtagit previously approved these changes Nov 5, 2026
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread CLAUDE.md Resolved
Comment thread references/git-workflow.md Resolved
Comment thread references/pitfalls.md Resolved
Comment thread references/pitfalls.md Resolved
Comment thread references/pitfalls.md Resolved
Comment thread references/pitfalls.md Resolved
rmad17 and others added 2 commits November 10, 2026 10:16
…etry

Move the CLAUDE.md content into AGENTS.md and remove CLAUDE.md, so a single
file serves all agent tools. Add the client telemetry changes from #153 to
the project structure, test lists, helper list, flow map, docs mapping, and
the custom_fetch notes.

Co-Authored-By: Claude <noreply@anthropic.com>
rmad17 and others added 8 commits November 10, 2026 10:22
Cold-cache discovery outages in the token methods still raise a raw httpx
error, so the "never leak" and "fail closed" statements now apply to new
code and name the existing exception.

Co-Authored-By: Claude <noreply@anthropic.com>
Note that a run takes release notes from the release PR body, creates the
GitHub release and tag, and publishes to PyPI.

Co-Authored-By: Claude <noreply@anthropic.com>
Break the Always Do request-handling bullet and the Releases paragraph into
labelled points, with no change to the rules they state.

Co-Authored-By: Claude <noreply@anthropic.com>
Break the Python floor, async test, dependency list, and custom_fetch
pitfalls into labelled points, with no change to the guidance.

Co-Authored-By: Claude <noreply@anthropic.com>
requirements.txt includes freezegun alongside the pytest packages, so name
it in the Ask First dependency bullet and the pitfalls note.

Co-Authored-By: Claude <noreply@anthropic.com>
A plain httpx.AsyncClient() uses httpx's 5 second default (0.28.1), so the
discovery and JWKS fetches have a timeout. What does not apply to them is
options.timeout.

Co-Authored-By: Claude <noreply@anthropic.com>
Split the closing sentence and name the timeout and telemetry headers
instead of "either behaviour".

Co-Authored-By: Claude <noreply@anthropic.com>
Drop the CODEOWNERS team handle, the unverifiable branch protection note, and
the unsupported agent release policy. Correct the SCA trigger branches and
replace opinion and time-relative wording with plain statements.

Co-Authored-By: Claude <noreply@anthropic.com>

This branch has not been deployed

No deployments
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.

3 participants