docs: add self-contained AGENTS.md SSoT for AI agents#16
Merged
Conversation
Add an AGENTS.md (and CLAUDE.md pointer) in this repository root that serves as the single source of truth for AI coding agents working here. The file is fully self-contained (no references to files outside this submodule) and English-only (apart from one literal Chinese template string for AI-attribution). Cross-vendor: AGENTS.md is the native format for Codex, Copilot CLI; CLAUDE.md, .cursor/rules/main.mdc, and .github/copilot-instructions.md all point to AGENTS.md. 🤖 本提交由 AI Agent (Copilot) 创建 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a standard ignore block for AI/agent local caches, configs, and scratch files (.claude/, .codex/, .cursor/, .antigravity/, .aider*, .continue/, .roo/, .windsurf/, .copilot/, AGENTS.local.md, etc.). The committed SSoT files (AGENTS.md, CLAUDE.md, docs/agents/) remain tracked — only ad-hoc local agent state is ignored. 🤖 本提交由 AI Agent (Copilot) 创建 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a repository-root, self-contained guidance document for AI coding agents (AGENTS.md) and a thin pointer file for Claude (CLAUDE.md) to centralize cross-tool agent instructions for this SDK.
Changes:
- Add
AGENTS.mdas the intended single source of truth for agent conventions, quality gates, and safety rules. - Add
CLAUDE.mdto redirect toAGENTS.md.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| CLAUDE.md | Adds a pointer directing Claude to read AGENTS.md. |
| AGENTS.md | Adds centralized agent guidance, repo description, workflow commands, and conventions. |
Comments suppressed due to low confidence (1)
AGENTS.md:56
- Quality gates reference
npm run lint(eslint) andnpm test(vitest), but the repo currently has no lint script and tests are executed vianode --test(see package.json scripts). Consider updating these bullets to reflect the actual gates enforced in this repo.
- `npm run lint` passes (eslint clean)
- `npm run typecheck` passes (no `any` regressions in public types)
- `npm test` passes (vitest)
- `npm run build` produces a clean `dist/` with type declarations
- New public API has unit tests + a README usage example
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+22
to
+27
| ```bash | ||
| npm install | ||
| npm run build # tsc -> dist/ | ||
| npm test # vitest | ||
| npm run lint # eslint | ||
| npm run typecheck |
Comment on lines
+41
to
+42
| 3. **All public types re-exported from `src/index.ts`**. Downstream | ||
| consumers import only from the package root. |
Comment on lines
+79
to
+80
| - `.cursor/rules/main.mdc` → read this file | ||
| - `.github/copilot-instructions.md` → read this file |
LucienSong
added a commit
to LucienSong/shell-sdk
that referenced
this pull request
May 24, 2026
* spec: align address format to 0x 64-char hex 32-byte - Rewrite address.ts: BLAKE3(algo_id||pk) → 32 bytes, 0x hex display - Remove bech32m/pq1 encoding; no version byte - Rename: bytesToShellAddress, shellAddressToBytes, deriveShellAddressFromPublicKey, isShellAddress, normalizeShellAddress - Keep legacy pq* aliases (deprecated) for callers during transition - system-contracts.ts: system addresses now 32-byte big-endian (matching shell-chain) - Update all src/*.ts: imports, comments, pq1 examples → 0x - index.ts: export new Shell* names + legacy aliases Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add self-contained AGENTS.md SSoT for AI agents (ShellDAO#16) * docs: add self-contained AGENTS.md SSoT for AI agents Add an AGENTS.md (and CLAUDE.md pointer) in this repository root that serves as the single source of truth for AI coding agents working here. The file is fully self-contained (no references to files outside this submodule) and English-only (apart from one literal Chinese template string for AI-attribution). Cross-vendor: AGENTS.md is the native format for Codex, Copilot CLI; CLAUDE.md, .cursor/rules/main.mdc, and .github/copilot-instructions.md all point to AGENTS.md. 🤖 本提交由 AI Agent (Copilot) 创建 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(gitignore): ignore local AI/Agent state directories Add a standard ignore block for AI/agent local caches, configs, and scratch files (.claude/, .codex/, .cursor/, .antigravity/, .aider*, .continue/, .roo/, .windsurf/, .copilot/, AGENTS.local.md, etc.). The committed SSoT files (AGENTS.md, CLAUDE.md, docs/agents/) remain tracked — only ad-hoc local agent state is ignored. 🤖 本提交由 AI Agent (Copilot) 创建 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(readme): align with shell-chain v0.23.0 — drop pq1/Bech32m, document 32-byte 0x addresses, flag signing-hash drift (ShellDAO#17) * docs(readme): align with chain v0.23.0 — drop pq1/Bech32m examples, document 32-byte 0x address format, flag signing-hash drift Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: fix system-contracts table, address exports, and error messages Address three Copilot review comments on PR ShellDAO#17: 1. Fix malformed system-contracts table (3-column header with 2-column rows) — collapse to a clean 2-column Name/Address table with full 32-byte literal addresses. 2. Fix normalizeShellAddress error example (lines 206, 737) to match the actual thrown message: 'expected 0x + 64-char hex address, got: …' 3. Fix system-contracts module reference: remove the non-existent validatorRegistryHexAddress / accountManagerHexAddress entries; document only the actual exports (validatorRegistryAddress / accountManagerAddress) with their full 32-byte canonical values; update the isSystemContractAddress example to use a 32-byte address. Also fix stale error message in the error-handling table: 'expected 20 address bytes' → 'expected 32 address bytes' to match address.ts:37. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test: update fixtures and assertions for v0.23.0 0x address format Replace all pq1/Bech32m address references in test fixtures and assertions with valid 0x + 64-char hex Shell addresses. Update keystore fixture address fields to match BLAKE3-derived canonical addresses. Fix tampered-address test to produce a valid 64-char hex address before mutation so the keystore address-mismatch guard is exercised (not the format validator). Update rust-compat fixture pq_address and transaction hash vectors for 32-byte address encoding. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: align README and PQTx comments with PQVM-native design (ShellDAO#18) * docs: replace EVM-compatible headline; clarify PQTx fee-field comments - README: PQVM-native chain description - src/transactions.ts: EIP-1559-style fee fields (not claiming ECDSA-based signing), Shell chain ID label instead of EIP-155, removed bare EIP-1559 and EIP-155 labels Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(transactions): address review comments — standardize chainId/fee-field JSDoc - Standardize chainId description to 'EIP-155 chain ID (Shell Chain)' in BuildTransactionOptions (was 'Shell chain ID'), matching all other helpers - Remove '-style' suffix from EIP-1559 fee field docs in BuildTransactionOptions for consistency with DEFAULT_MAX_FEE_PER_GAS / DEFAULT_MAX_PRIORITY_FEE_PER_GAS - Add '(scaffolded; not enforced by the chain)' note to maxFeePerGas and maxPriorityFeePerGas fields to clarify gas fields are present in encoding but not yet active on-chain - Update DEFAULT_TX_TYPE comment to explain fee-field scaffolding intent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(sdk): scrub stale pq1 bech32m mentions from README/examples Remove stale documentation and example references that implied pq1 bech32m was a valid current render. Current v0.23.0-compatible APIs use BLAKE3-derived 32-byte Shell addresses rendered as 0x + 64 lowercase hex; deprecated Pq* aliases remain for API compatibility. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
LucienSong
added a commit
that referenced
this pull request
May 24, 2026
* spec: align address format to 0x 64-char hex 32-byte - Rewrite address.ts: BLAKE3(algo_id||pk) → 32 bytes, 0x hex display - Remove bech32m/pq1 encoding; no version byte - Rename: bytesToShellAddress, shellAddressToBytes, deriveShellAddressFromPublicKey, isShellAddress, normalizeShellAddress - Keep legacy pq* aliases (deprecated) for callers during transition - system-contracts.ts: system addresses now 32-byte big-endian (matching shell-chain) - Update all src/*.ts: imports, comments, pq1 examples → 0x - index.ts: export new Shell* names + legacy aliases * docs: add self-contained AGENTS.md SSoT for AI agents (#16) * docs: add self-contained AGENTS.md SSoT for AI agents Add an AGENTS.md (and CLAUDE.md pointer) in this repository root that serves as the single source of truth for AI coding agents working here. The file is fully self-contained (no references to files outside this submodule) and English-only (apart from one literal Chinese template string for AI-attribution). Cross-vendor: AGENTS.md is the native format for Codex, Copilot CLI; CLAUDE.md, .cursor/rules/main.mdc, and .github/copilot-instructions.md all point to AGENTS.md. 🤖 本提交由 AI Agent (Copilot) 创建 * chore(gitignore): ignore local AI/Agent state directories Add a standard ignore block for AI/agent local caches, configs, and scratch files (.claude/, .codex/, .cursor/, .antigravity/, .aider*, .continue/, .roo/, .windsurf/, .copilot/, AGENTS.local.md, etc.). The committed SSoT files (AGENTS.md, CLAUDE.md, docs/agents/) remain tracked — only ad-hoc local agent state is ignored. 🤖 本提交由 AI Agent (Copilot) 创建 --------- * docs(readme): align with shell-chain v0.23.0 — drop pq1/Bech32m, document 32-byte 0x addresses, flag signing-hash drift (#17) * docs(readme): align with chain v0.23.0 — drop pq1/Bech32m examples, document 32-byte 0x address format, flag signing-hash drift * docs: fix system-contracts table, address exports, and error messages Address three Copilot review comments on PR #17: 1. Fix malformed system-contracts table (3-column header with 2-column rows) — collapse to a clean 2-column Name/Address table with full 32-byte literal addresses. 2. Fix normalizeShellAddress error example (lines 206, 737) to match the actual thrown message: 'expected 0x + 64-char hex address, got: …' 3. Fix system-contracts module reference: remove the non-existent validatorRegistryHexAddress / accountManagerHexAddress entries; document only the actual exports (validatorRegistryAddress / accountManagerAddress) with their full 32-byte canonical values; update the isSystemContractAddress example to use a 32-byte address. Also fix stale error message in the error-handling table: 'expected 20 address bytes' → 'expected 32 address bytes' to match address.ts:37. * test: update fixtures and assertions for v0.23.0 0x address format Replace all pq1/Bech32m address references in test fixtures and assertions with valid 0x + 64-char hex Shell addresses. Update keystore fixture address fields to match BLAKE3-derived canonical addresses. Fix tampered-address test to produce a valid 64-char hex address before mutation so the keystore address-mismatch guard is exercised (not the format validator). Update rust-compat fixture pq_address and transaction hash vectors for 32-byte address encoding. --------- * docs: align README and PQTx comments with PQVM-native design (#18) * docs: replace EVM-compatible headline; clarify PQTx fee-field comments - README: PQVM-native chain description - src/transactions.ts: EIP-1559-style fee fields (not claiming ECDSA-based signing), Shell chain ID label instead of EIP-155, removed bare EIP-1559 and EIP-155 labels * docs(transactions): address review comments — standardize chainId/fee-field JSDoc - Standardize chainId description to 'EIP-155 chain ID (Shell Chain)' in BuildTransactionOptions (was 'Shell chain ID'), matching all other helpers - Remove '-style' suffix from EIP-1559 fee field docs in BuildTransactionOptions for consistency with DEFAULT_MAX_FEE_PER_GAS / DEFAULT_MAX_PRIORITY_FEE_PER_GAS - Add '(scaffolded; not enforced by the chain)' note to maxFeePerGas and maxPriorityFeePerGas fields to clarify gas fields are present in encoding but not yet active on-chain - Update DEFAULT_TX_TYPE comment to explain fee-field scaffolding intent --------- * docs(sdk): scrub stale pq1 bech32m mentions from README/examples Remove stale documentation and example references that implied pq1 bech32m was a valid current render. Current v0.23.0-compatible APIs use BLAKE3-derived 32-byte Shell addresses rendered as 0x + 64 lowercase hex; deprecated Pq* aliases remain for API compatibility. --------- Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
LucienSong
added a commit
that referenced
this pull request
May 24, 2026
First published release with 32-byte 0x hex address format (breaking from 0.8.x). Includes docs cleanup PRs #16-#19 on top of the 0.9.0 dev tag. Requires shell-chain >= v0.23.0. Co-authored-by: LucienSong <LucienSong@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add a self-contained
AGENTS.md(andCLAUDE.mdpointer) at the repository root, serving as the single source of truth for AI coding agents working in this submodule.Why
Cross-tool agent guidance (Codex, Copilot CLI, Cursor, Claude, Antigravity) needs a single canonical entry point.
AGENTS.mdis the cross-vendor convention — natively recognized by Codex/Copilot CLI; other tools point to it via thin pointer files.Self-contained
The file does not reference any path outside this submodule. All cardinal rules (wire-format fidelity, key-handling, commit conventions, agent attribution, language policy) are inlined.
Language
English-only, except for one literal Chinese template string in code formatting that AI agents are required to emit verbatim in PR/Issue bodies.
Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com