diff --git a/.claude/skills/solidity-natspec/SKILL.md b/.agents/skills/solidity-natspec/SKILL.md similarity index 100% rename from .claude/skills/solidity-natspec/SKILL.md rename to .agents/skills/solidity-natspec/SKILL.md diff --git a/.claude/skills/solidity-natspec/scripts/check_natspec.mjs b/.agents/skills/solidity-natspec/scripts/check_natspec.mjs similarity index 100% rename from .claude/skills/solidity-natspec/scripts/check_natspec.mjs rename to .agents/skills/solidity-natspec/scripts/check_natspec.mjs diff --git a/.agents/skills/update-docs/SKILL.md b/.agents/skills/update-docs/SKILL.md new file mode 100644 index 0000000000..0fe479869f --- /dev/null +++ b/.agents/skills/update-docs/SKILL.md @@ -0,0 +1,290 @@ +--- +name: update-docs +description: Update project documentation based on recent commits. Use when the user asks to update, sync, or refresh docs after code changes. +--- + +# Update Documentation + +Automatically update project documentation based on recent commits and code changes. + +## Arguments + +Parse the arguments provided in `$ARGUMENTS`: + +- `commits=N` - Analyze last N commits (default: 10) +- `scope=X` - Update specific scope only (ats or mass-payout) +- `dry-run` - Preview changes without modifying files + +Examples: + +- `/update-docs` - Update all based on recent commits +- `/update-docs commits=20` - Analyze last 20 commits +- `/update-docs commits=5 scope=ats` - Last 5 commits, ATS scope only +- `/update-docs dry-run` - Preview changes without modifying files + +## Context + +Arguments provided by user: $ARGUMENTS + +--- + +## What This Skill Does + +This skill automates documentation updates by: + +1. **Reviewing Recent Commits** + - Analyzes commit messages for feature additions, fixes, and breaking changes + - Identifies changed files to understand scope + - Extracts relevant implementation details + - Collects commit hashes for reference + +2. **Reviewing CHANGELOGs (Read-Only for Context)** + - **IMPORTANT**: Reads existing CHANGELOGs to understand current version and recent changes + - Identifies which packages are affected by the feature + - Notes what type of change this would be (Major/Minor/Patch) + - **Does NOT modify CHANGELOGs** - this is a manual task for the user + +3. **Updating Documentation** + - Updates user guides with new features + - Updates developer guides with architectural patterns + - Updates architecture overviews + - Updates API documentation + - Updates getting started guides if setup changed + - Creates or updates "What's New" sections + - Updates README files if needed + +4. **Generating Summary** + - Creates a summary of all documentation changes + - Lists all documentation files modified + - Provides CHANGELOG update suggestions for manual entry + - Provides a checklist for manual review + +--- + +## Instructions for Claude + +When this skill is invoked, follow these steps: + +### Step 1: Discovery Phase + +1. **Review Recent Commits** + - Use `git log --oneline -N` to get recent commits (N from arguments or default 10) + - Look for commits with keywords: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:` + - Identify scope from commit scopes and file paths (ats, mass-payout, sdk, contracts) + - Extract feature descriptions from commit messages + - Note commit hashes for reference + - Use `git diff` on relevant commits to understand actual code changes + +2. **Review Existing CHANGELOGs (Read-Only for Context)** + - Locate CHANGELOGs based on scope: + - ATS Contracts: `packages/ats/contracts/CHANGELOG.md` + - ATS SDK: `packages/ats/sdk/CHANGELOG.md` + - Mass Payout Contracts: `packages/mass-payout/contracts/CHANGELOG.md` + - Mass Payout SDK: `packages/mass-payout/sdk/CHANGELOG.md` + - Mass Payout Backend: `apps/mass-payout/backend/CHANGELOG.md` (if exists) + - Mass Payout Frontend: `apps/mass-payout/frontend/CHANGELOG.md` (if exists) + - Read existing CHANGELOG to: + - Understand current version number + - Check if feature is already documented + - Determine what category this change would be (Major/Minor/Patch) + - **Important:** Do NOT modify CHANGELOGs - only read for context + +3. **Identify Scope** + - Determine if changes affect: + - ATS (Asset Tokenization Studio) + - Mass Payout + - SDK (either ATS SDK or Mass Payout SDK) + - Contracts (smart contracts) + - Global (affects entire monorepo) + +### Step 2: Analysis Phase + +1. **Map Changes to Documentation** + + For each relevant commit, determine which documentation files need updates: + + **User-Facing Features (feat: commits):** + - `docs/{scope}/user-guides/` - Add new guides or update existing ones + - `docs/{scope}/intro.md` - Update features list if major feature + - `docs/{scope}/getting-started/` - Update if affects setup or quick start + + **Developer-Facing Changes (refactor:, feat: in contracts/sdk):** + - `docs/{scope}/developer-guides/` - Add technical implementation details + - `docs/{scope}/api/` - Update API reference + - `README.md` (root or package) - Update if affects installation or setup + + **Contract Changes:** + - `docs/{scope}/developer-guides/contracts/` - Update contract documentation + - `docs/{scope}/api/contracts/` - Update contract API reference + + **SDK Changes:** + - `docs/{scope}/developer-guides/sdk-*.md` - Update SDK guides + - `docs/{scope}/api/sdk-reference.md` - Update SDK API reference + +2. **Read Existing Documentation** + - Read the identified documentation files + - Understand the current structure and style + - Identify where new content should be inserted + +### Step 3: Update Phase + +For each documentation file that needs updating: + +1. **User Guides** + - Add new step-by-step guides for new features + - Update existing guides if feature modifies existing flows + - Include screenshots placeholders: `![Feature Name](../../images/feature-name.png)` + - Follow existing format and style + +2. **Developer Guides** + - Add technical implementation details + - Include code examples + - Document new architecture patterns + - Update architecture diagrams (mermaid) if needed + +3. **API Documentation** + - Document new endpoints (REST API) + - Document new contract functions + - Document new SDK methods + - Include request/response examples + +4. **Getting Started Guides** + - Update prerequisites if needed + - Add new environment variables + - Update configuration steps + +5. **Intro/Index Pages** + - Update feature lists + - Update use cases if applicable + - Update architecture diagrams if needed + +### Step 4: Validation Phase + +1. **Check Internal Links** + - Verify all internal links use `.md` extensions + - Ensure links point to existing files + - Fix any broken links found + +2. **Check Consistency** + - Ensure terminology is consistent with existing docs + - Verify code examples follow project conventions + - Check that formatting matches existing docs + +3. **Create Summary** + - List all documentation files modified + - Summarize key changes made + - Provide checklist of items that need manual review: + - [ ] Screenshots need to be added + - [ ] Code examples need testing + - [ ] Links need verification + - [ ] **CHANGELOGs need manual updates** (see suggestions below) + +### Step 5: Output Phase + +1. **Present Changes** + - Show summary of documentation updates + - List modified files + - Highlight any manual steps needed + +2. **Provide CHANGELOG Update Suggestions** + - **Important:** Do NOT modify CHANGELOG files + - Instead, provide suggestions for manual CHANGELOG updates: + - Which CHANGELOG files need updates + - Suggested change type (Major/Minor/Patch) + - Suggested entry format with commit hash + - Example entry the user can copy/paste + - Format suggestion as: + + ``` + CHANGELOG Suggestions (Manual Update Required): + + packages/ats/contracts/CHANGELOG.md + Type: Minor + Suggested entry: + ### Minor Changes + - abc123d: Add freeze reason parameter + + packages/mass-payout/sdk/CHANGELOG.md + Type: Major + Suggested entry: + ### Major Changes + - def456e: Migrate to GraphQL API + BREAKING CHANGE: REST endpoints deprecated + ``` + +3. **Suggest Next Steps** + - Update CHANGELOGs manually using suggestions above + - Run docs locally to verify formatting: `npm run docs:start` + - Add missing screenshots + - Test code examples + - Review and commit changes + +--- + +## Special Cases + +### No Relevant Commits Found + +If no feature or fix commits are found in the range, report that no documentation updates are needed and suggest expanding the commit range. + +### Multiple Scopes Affected + +If commits affect multiple scopes (e.g., both ATS and Mass Payout), update documentation in all affected areas and provide CHANGELOG suggestions for all relevant packages. + +### Breaking Changes + +If commits indicate breaking changes: + +- Add prominent warning boxes in affected documentation +- Create migration guides in documentation +- In CHANGELOG suggestions, recommend "Major Changes" category +- Include migration path in suggested CHANGELOG entry + +### CHANGELOG Already Has Entry + +If the CHANGELOG already has an entry for the feature: + +- Note that it's already documented +- Skip CHANGELOG suggestions for this feature + +### Missing CHANGELOG Files + +If a package doesn't have a CHANGELOG: + +- Note in the summary that CHANGELOG is missing +- Suggest creating one using Changesets format + +--- + +## Configuration + +**Documentation Structure:** + +``` +docs/ + ats/ + intro.md + getting-started/ + user-guides/ + developer-guides/ + api/ + mass-payout/ + intro.md + getting-started/ + user-guides/ + developer-guides/ + api/ + references/ + guides/ +``` + +--- + +## Notes + +- This skill creates or updates documentation files but does NOT commit them automatically +- Always review generated documentation before committing +- Screenshots and diagrams referenced in docs need to be added manually +- Code examples should be tested before finalizing +- Internal links should be verified after updates +- The skill follows existing documentation style and conventions diff --git a/.claude/commands/docs/update-docs.md b/.claude/commands/docs/update-docs.md deleted file mode 100644 index b479a10deb..0000000000 --- a/.claude/commands/docs/update-docs.md +++ /dev/null @@ -1,562 +0,0 @@ ---- -description: Update documentation based on EPs, ADRs, and commits -argument-hint: [options] ---- - -# Update Documentation - -Automatically update project documentation based on implemented Enhancement Proposals (EPs), accepted Architecture Decision Records (ADRs), and recent commits. - -## Arguments - -Parse the arguments provided in `$ARGUMENTS`: -- `ep=N` - Update docs for specific EP number N -- `adr=N` - Update docs for specific ADR number N -- `commits=N` - Analyze last N commits -- `scope=X` - Update specific scope only (ats or mass-payout) -- `dry-run` - Preview changes without modifying files - -If no arguments provided, scan for all implemented EPs and accepted ADRs. - -Examples: -- `/update-docs` - Update all -- `/update-docs ep=3` - Update docs for EP-0003 -- `/update-docs adr=2 scope=mass-payout` - Update docs for ADR-0002 in mass-payout -- `/update-docs commits=20 dry-run` - Preview updates based on last 20 commits - -## Context - -Arguments provided by user: $ARGUMENTS - ---- - -## What This Skill Does - -This skill automates documentation updates by: - -1. **Scanning Enhancement Proposals (EPs)** - - Finds EPs with status: `Implemented` or `๐Ÿš€ Implemented` - - Extracts feature details from the EP - - Identifies which documentation sections need updates - -2. **Scanning Architecture Decision Records (ADRs)** - - Finds ADRs with status: `Accepted` or `โœ… Accepted` - - Extracts architectural decisions and their implications - - Identifies which developer guides and architecture docs need updates - - Determines if setup/prerequisites changed - -3. **Reviewing Recent Commits** - - Analyzes commit messages for feature additions - - Identifies changed files to understand scope - - Extracts relevant implementation details - - Collects commit hashes for reference - -4. **Reviewing CHANGELOGs (Read-Only for Context)** - - **IMPORTANT**: Reads existing CHANGELOGs to understand current version and recent changes - - Identifies which packages are affected by the feature - - Notes what type of change this would be (Major/Minor/Patch) - - **Does NOT modify CHANGELOGs** - this is a manual task for the user - -5. **Updating Documentation** - - Updates user guides with new features (from EPs) - - Updates developer guides with architectural patterns (from ADRs) - - Updates architecture overviews (from ADRs) - - Updates API documentation - - Updates getting started guides if setup changed (from ADRs) - - Creates or updates "What's New" sections - - Updates README files if needed - -6. **Generating Summary** - - Creates a summary of all documentation changes - - Lists all documentation files modified - - Provides CHANGELOG update suggestions for manual entry - - Provides a checklist for manual review - ---- - -## Instructions for Claude - -When this skill is invoked, follow these steps: - -### Step 1: Discovery Phase - -1. **Check for Enhancement Proposals (EPs)** - - Look in `docs/references/proposals/` for EP files - - Filter EPs with status: `Implemented` or `๐Ÿš€ Implemented` - - Read each implemented EP to understand: - - Feature name and scope (ATS, Mass Payout, SDK, Global) - - What was implemented - - UI/UX changes - - API changes - - Documentation requirements mentioned in the EP - -2. **Check for Architecture Decision Records (ADRs)** - - Look in `docs/references/adr/` for ADR files - - Filter ADRs with status: `Accepted` or `โœ… Accepted` - - Read each accepted ADR to understand: - - Architectural decision made and scope (ATS, Mass Payout, SDK, Global) - - Context and problem statement - - Decision outcome and rationale - - Consequences (positive and negative impacts) - - Technologies/patterns chosen - - Documentation requirements implied by the decision - - ADRs often require updates to: - - Architecture overview documents - - Developer guides (explaining new patterns/technologies) - - API documentation (if APIs changed) - - Getting started guides (if setup/prerequisites changed) - -3. **Review Recent Commits (if commits=N argument provided)** - - Use `git log` to get recent commits - - Look for commits with keywords: `feat:`, `feature:`, `add:`, `implement:` - - Identify scope from file paths (ats, mass-payout, sdk, contracts) - - Extract feature descriptions from commit messages - - Note commit hashes for reference - -4. **Review Existing CHANGELOGs (Read-Only for Context)** - - Locate CHANGELOGs based on scope: - - ATS Contracts: `packages/ats/contracts/CHANGELOG.md` - - ATS SDK: `packages/ats/sdk/CHANGELOG.md` - - Mass Payout Contracts: `packages/mass-payout/contracts/CHANGELOG.md` - - Mass Payout SDK: `packages/mass-payout/sdk/CHANGELOG.md` - - Mass Payout Backend: `apps/mass-payout/backend/CHANGELOG.md` (if exists) - - Mass Payout Frontend: `apps/mass-payout/frontend/CHANGELOG.md` (if exists) - - Read existing CHANGELOG to: - - Understand current version number - - Check if feature is already documented - - Determine what category this change would be (Major/Minor/Patch) - - **Important:** Do NOT modify CHANGELOGs - only read for context - -5. **Identify Scope** - - Determine if changes affect: - - ATS (Asset Tokenization Studio) - - Mass Payout - - SDK (either ATS SDK or Mass Payout SDK) - - Contracts (smart contracts) - - Global (affects entire monorepo) - - Map scope to specific CHANGELOGs to update - -### Step 2: Analysis Phase - -1. **Map Features to Documentation** - - For each implemented feature, determine which documentation files need updates: - - **User-Facing Features:** - - `docs/{scope}/user-guides/` - Add new guides or update existing ones - - `docs/{scope}/intro.md` - Update features list if major feature - - `docs/{scope}/getting-started/` - Update if affects setup or quick start - - **Developer-Facing Features:** - - `docs/{scope}/developer-guides/` - Add technical implementation details - - `docs/{scope}/api/` - Update API reference - - `README.md` (root or package) - Update if affects installation or setup - - `CHANGELOG.md` - Add entry with version and changes - - **Contract Changes:** - - `docs/{scope}/developer-guides/contracts/` - Update contract documentation - - `docs/{scope}/api/contracts/` - Update contract API reference - - **SDK Changes:** - - `docs/{scope}/developer-guides/sdk-*.md` - Update SDK guides - - `docs/{scope}/api/sdk-reference.md` - Update SDK API reference - -2. **Read Existing Documentation** - - Read the identified documentation files - - Understand the current structure and style - - Identify where new content should be inserted - -### Step 3: Update Phase - -For each documentation file that needs updating: - -1. **User Guides** - - Add new step-by-step guides for new features - - Update existing guides if feature modifies existing flows - - Include screenshots placeholders: `![Feature Name](../../images/feature-name.png)` - - Follow existing format and style - - Add to index pages with card boxes if applicable - -2. **Developer Guides** - - Add technical implementation details - - Include code examples - - Document new architecture patterns - - Update architecture diagrams (mermaid) if needed - - Add deployment instructions if needed - -3. **API Documentation** - - Document new endpoints (REST API) - - Document new contract functions - - Document new SDK methods - - Include request/response examples - - Add code snippets - -4. **Getting Started Guides** - - Update prerequisites if needed - - Add new environment variables - - Update configuration steps - - Add troubleshooting entries for common issues - -5. **Intro/Index Pages** - - Update feature lists in card boxes - - Update use cases if applicable - - Update architecture diagrams if needed - - Update system requirements if changed - -### Step 4: Validation Phase - -1. **Check Internal Links** - - Verify all internal links use `.md` extensions - - Ensure links point to existing files - - Fix any broken links found - -2. **Check Consistency** - - Ensure terminology is consistent with existing docs - - Verify code examples follow project conventions - - Check that formatting matches existing docs - -3. **Create Summary** - - List all documentation files modified - - Summarize key changes made - - Provide checklist of items that need manual review: - - [ ] Screenshots need to be added - - [ ] Code examples need testing - - [ ] Links need verification - - [ ] **CHANGELOGs need manual updates** (see suggestions below) - -### Step 5: Output Phase - -1. **Present Changes** - - Show summary of documentation updates - - List modified files - - Highlight any manual steps needed - -2. **Provide CHANGELOG Update Suggestions** - - **Important:** Do NOT modify CHANGELOG files - - Instead, provide suggestions for manual CHANGELOG updates: - - Which CHANGELOG files need updates - - Suggested change type (Major/Minor/Patch) - - Suggested entry format with commit hash and EP/ADR reference - - Example entry the user can copy/paste - - Format suggestion as: - ``` - CHANGELOG Suggestions (Manual Update Required): - - ๐Ÿ“ packages/ats/contracts/CHANGELOG.md - Type: Minor - Suggested entry: - ### Minor Changes - - abc123d: Add freeze reason parameter (EP-0005) - - ๐Ÿ“ packages/mass-payout/sdk/CHANGELOG.md - Type: Major - Suggested entry: - ### Major Changes - - def456e: Migrate to GraphQL API (ADR-0002) - BREAKING CHANGE: REST endpoints deprecated - Migration: See docs/mass-payout/api/migration-guide.md - ``` - -3. **Suggest Next Steps** - - Update CHANGELOGs manually using suggestions above - - Run docs locally to verify formatting - - Add missing screenshots - - Test code examples - - Review and commit changes - ---- - -## Examples - -### Example 1: Update docs for implemented EP - -``` -User: /update-docs --ep 0003 - -Claude: -I'll update the documentation for EP-0003: Scheduled Distributions. - -Discovery Phase: -โœ“ Found EP: docs/references/proposals/0003-mp-scheduled-distributions.md -โœ“ Status: ๐Ÿš€ Implemented -โœ“ Scope: Mass Payout -โœ“ Feature: Automatic recurring distributions with cron-like scheduling -โœ“ Affected packages: Backend (NestJS), SDK - -Review CHANGELOGs: -โœ“ Read packages/mass-payout/sdk/CHANGELOG.md (current version: 1.1.0) -โœ“ Read apps/mass-payout/backend/CHANGELOG.md (current version: 1.1.5) -โœ“ Change type: Minor (new feature, backward compatible) - -Analysis Phase: -Documentation files to update: -- docs/mass-payout/user-guides/creating-distributions.md (add scheduling section) -- docs/mass-payout/user-guides/index.md (add scheduled distributions card) -- docs/mass-payout/intro.md (update features and use cases) -- docs/mass-payout/developer-guides/backend/architecture.md (add scheduling service) - -[Proceeds to update each file...] - -Update Phase: -โœ“ Updated user guides with scheduling steps -โœ“ Updated architecture docs with CronService component -โœ“ Updated intro.md use cases - -Summary of Changes: -โœ“ Updated 4 documentation files -โœ“ Added "Scheduled Distributions" section to user guide -โœ“ Updated architecture diagram with CronService - -CHANGELOG Suggestions (Manual Update Required): - -๐Ÿ“ packages/mass-payout/sdk/CHANGELOG.md -Type: Minor -Current version: 1.1.0 โ†’ Suggested: 1.2.0 -Suggested entry: -### Minor Changes -- a1b2c3d: Add scheduled and recurring distribution support (EP-0003) - -๐Ÿ“ apps/mass-payout/backend/CHANGELOG.md -Type: Minor -Current version: 1.1.5 โ†’ Suggested: 1.2.0 -Suggested entry: -### Minor Changes -- a1b2c3d: Implement CronService for automatic payout execution (EP-0003) - -Manual Steps Needed: -- [ ] Update CHANGELOGs using suggestions above -- [ ] Add screenshots for scheduled distribution UI -- [ ] Test cron expression examples -- [ ] Verify all links work in deployed docs - -Would you like me to commit these changes? -``` - -### Example 2: Update docs based on recent commits - -``` -User: /update-docs --commits 20 --scope ats - -Claude: -Analyzing last 20 commits in ATS scope... - -Found relevant commits: -1. e0a3f03: feat(ats): add multi-signature approval for transfers -2. a1b2c3d: feat(contracts): add freeze reason parameter -3. c4d5e6f: feat(sdk): add batch transfer method - -Review CHANGELOGs: -โœ“ Read packages/ats/contracts/CHANGELOG.md (current version: 2.0.0) -โœ“ Read packages/ats/sdk/CHANGELOG.md (current version: 2.1.0) -โœ“ Changes found: - - Multi-sig approval: Major (breaking change in approval flow) - - Freeze reason: Minor (new parameter, backward compatible) - - Batch transfer: Minor (new method) - -Analysis Phase: -Documentation to update: -- docs/ats/user-guides/transfer-restrictions.md (multi-sig section) -- docs/ats/user-guides/freeze-tokens.md (freeze reason parameter) -- docs/ats/developer-guides/sdk-integration.md (batch transfer examples) - -[Proceeds with documentation updates...] - -Update Phase: -โœ“ Updated user guides with multi-sig approval section -โœ“ Updated freeze documentation with reason parameter -โœ“ Added batch transfer code examples to SDK guide - -Summary: -โœ“ Updated 3 documentation files -โœ“ Documented breaking change with migration notes -โœ“ Added code examples for new features - -CHANGELOG Suggestions (Manual Update Required): - -๐Ÿ“ packages/ats/contracts/CHANGELOG.md -Type: Major (breaking change) -Current version: 2.0.0 โ†’ Suggested: 3.0.0 -Suggested entry: -### Major Changes -- e0a3f03: Multi-signature approval required for restricted transfers - - BREAKING CHANGE: Transfer approval flow changed - Migration: Update your transfer flows to include approval step - -### Minor Changes -- a1b2c3d: Add optional reason parameter to freeze methods - -๐Ÿ“ packages/ats/sdk/CHANGELOG.md -Type: Minor -Current version: 2.1.0 โ†’ Suggested: 2.2.0 -Suggested entry: -### Minor Changes -- c4d5e6f: Add batchTransfer method for efficient multi-recipient transfers -``` - -### Example 3: Update docs based on accepted ADR - -``` -User: /update-docs --adr 0002 - -Claude: -I'll update the documentation for ADR-0002: Adopt GraphQL for Mass Payout API. - -Discovery Phase: -โœ“ Found ADR: docs/references/adr/0002-adopt-graphql-api.md -โœ“ Status: โœ… Accepted -โœ“ Scope: Mass Payout (Backend) -โœ“ Decision: Replace REST API with GraphQL using Apollo Server -โœ“ Consequences: - - More flexible queries for frontend - - Breaking change for existing API consumers - - New dependencies (Apollo Server, GraphQL) - -Review CHANGELOGs: -โœ“ Read apps/mass-payout/backend/CHANGELOG.md (current version: 1.5.0) -โœ“ Change type: Major (breaking API change) - -Analysis Phase: -Documentation to update: -- docs/mass-payout/developer-guides/backend/architecture.md (add GraphQL layer) -- docs/mass-payout/developer-guides/backend/index.md (update API section) -- docs/mass-payout/getting-started/full-setup.md (new GraphQL playground URL) -- docs/mass-payout/api/rest-api/index.md (deprecation notice + migration guide) -- docs/mass-payout/api/graphql/ (NEW: create GraphQL API documentation) - -[Proceeds with documentation updates...] - -Update Phase: -โœ“ Updated architecture docs with GraphQL layer diagram -โœ“ Added GraphQL schema documentation -โœ“ Created migration guide from REST to GraphQL -โœ“ Updated getting started with GraphQL playground URL -โœ“ Added deprecation notices to REST API docs - -Summary: -โœ“ Updated 5 documentation files -โœ“ Created new GraphQL API documentation section -โœ“ Added migration guide for breaking change -โœ“ Updated architecture diagram with GraphQL layer - -CHANGELOG Suggestions (Manual Update Required): - -๐Ÿ“ apps/mass-payout/backend/CHANGELOG.md -Type: Major (breaking change) -Current version: 1.5.0 โ†’ Suggested: 2.0.0 -Suggested entry: -### Major Changes -- b3c4d5e: Migrate from REST to GraphQL API (ADR-0002) - - BREAKING CHANGE: REST API endpoints deprecated, will be removed in v3.0.0 - - Migration Guide: - - Use GraphQL endpoint at /graphql instead of /api - - See docs/mass-payout/api/graphql/ for new schema - - REST endpoints remain available but are deprecated - -Manual Steps Needed: -- [ ] Update CHANGELOG using suggestion above -- [ ] Test GraphQL examples in documentation -- [ ] Verify GraphQL playground URL is correct -- [ ] Add GraphQL schema visualization diagram -- [ ] Update frontend integration examples -- [ ] Confirm deprecation timeline with team -``` - ---- - -## Special Cases - -### No Implemented EPs or Accepted ADRs Found -If no implemented EPs or accepted ADRs are found, check recent commits with feature additions and architectural changes. Suggest: -- Creating an EP retroactively for implemented features -- Creating an ADR retroactively for architectural decisions made -- Updating docs based on commit analysis only - -### Multiple Scopes Affected -If a feature affects multiple scopes (e.g., both ATS and Mass Payout), update documentation in all affected areas and all relevant CHANGELOGs. - -### Breaking Changes -If the EP or commits indicate breaking changes: -- Add prominent warning boxes in affected documentation -- Create migration guides in documentation -- In CHANGELOG suggestions, recommend "Major Changes" category -- Suggest incrementing major version (e.g., 2.0.0 โ†’ 3.0.0) -- Include migration path in suggested CHANGELOG entry - -### CHANGELOG Already Has Entry -If the CHANGELOG already has an entry for the feature: -- Note that it's already documented -- Skip CHANGELOG suggestions for this feature -- Inform user that CHANGELOG is up to date - -### Missing CHANGELOG Files -If a package doesn't have a CHANGELOG: -- Note in the summary that CHANGELOG is missing -- Suggest creating one using Changesets format -- Recommend starting with version from package.json - -### New Architecture Patterns (from ADRs) -When ADRs introduce new architectural patterns: -- **Priority**: ADRs often have higher documentation priority for developer guides -- Update architecture overview documents first -- Add mermaid diagrams showing new patterns/layers -- Update developer guides with pattern explanation and examples -- Update getting started if prerequisites/setup changed -- Document in CHANGELOG as Minor or Major depending on impact -- If breaking change, provide migration guide from old to new pattern - -### ADRs with Infrastructure Changes -If an ADR changes infrastructure (databases, deployment, CI/CD): -- Update getting started guides -- Update system requirements -- Update deployment documentation -- Add migration/upgrade guides -- Update environment configuration examples - ---- - -## Configuration - -This skill looks for the following: - -**Enhancement Proposals:** -- Location: `docs/references/proposals/*.md` -- Status patterns: `Implemented`, `๐Ÿš€ Implemented` - -**Architecture Decision Records:** -- Location: `docs/references/adr/*.md` -- Status patterns: `Accepted`, `โœ… Accepted` - -**Documentation Structure:** -``` -docs/ -โ”œโ”€โ”€ ats/ -โ”‚ โ”œโ”€โ”€ intro.md -โ”‚ โ”œโ”€โ”€ getting-started/ -โ”‚ โ”œโ”€โ”€ user-guides/ -โ”‚ โ”œโ”€โ”€ developer-guides/ -โ”‚ โ””โ”€โ”€ api/ -โ”œโ”€โ”€ mass-payout/ -โ”‚ โ”œโ”€โ”€ intro.md -โ”‚ โ”œโ”€โ”€ getting-started/ -โ”‚ โ”œโ”€โ”€ user-guides/ -โ”‚ โ”œโ”€โ”€ developer-guides/ -โ”‚ โ””โ”€โ”€ api/ -โ””โ”€โ”€ references/ - โ””โ”€โ”€ proposals/ -``` - ---- - -## Notes - -- This skill creates or updates documentation files but does NOT commit them automatically -- Always review generated documentation before committing -- Screenshots and diagrams referenced in docs need to be added manually -- Code examples should be tested before finalizing -- Internal links should be verified after updates -- The skill follows existing documentation style and conventions - ---- diff --git a/.gitignore b/.gitignore index 49e1d0e662..b291650985 100644 --- a/.gitignore +++ b/.gitignore @@ -133,15 +133,15 @@ asset-tokenization-studio.iml # IntelliJ Idea /.idea/ -# AI files +# AI files โ€” local agent workspaces are gitignored. +# AGENTS.md (root) plus its CLAUDE.md / GEMINI.md symlinks are committed. +# Skills live under .agents/skills/ and are committed. +# Personal overrides live in *.local.md (e.g. CLAUDE.local.md) and stay local. .kiro/ -.claude/* -!.claude/skills/ -.claude/skills/* -!.claude/skills/solidity-natspec/ +.claude/ +.gemini/ .opencode/ -CLAUDE.md -AGENTS.md +*.local.md .tasks/ diff --git a/.prettierignore b/.prettierignore index 298b1cb5ec..a9ecb9ae23 100644 --- a/.prettierignore +++ b/.prettierignore @@ -44,4 +44,8 @@ gas-report.txt .env* # Documentation -Smart Contracts Audit Report.pdf \ No newline at end of file +Smart Contracts Audit Report.pdf + +# Symlinks to AGENTS.md โ€” prettier refuses to format symbolic links +CLAUDE.md +GEMINI.md \ No newline at end of file diff --git a/.scripts/agents-setup.sh b/.scripts/agents-setup.sh new file mode 100755 index 0000000000..ef814f6b1b --- /dev/null +++ b/.scripts/agents-setup.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +# Self-heal Claude Code skill wiring from .agents/skills/ into .claude/. +# Idempotent โ€” safe to run on every `npm install` via the prepare hook. +set -euo pipefail + +[[ -d .agents/skills ]] || exit 0 + +mkdir -p .claude/commands .claude/skills + +shopt -s nullglob +for skill_dir in .agents/skills/*/; do + [[ -f "${skill_dir}SKILL.md" ]] || continue + name="$(basename "$skill_dir")" + ln -sfn "../../.agents/skills/${name}/SKILL.md" ".claude/commands/${name}.md" + ln -sfn "../../.agents/skills/${name}" ".claude/skills/${name}" +done diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..e9e9a5626d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,343 @@ +# AGENTS.md + +This file provides guidance to AI coding agents when working with code in this repository. + +## Project Overview + +**Asset Tokenization Studio (ATS)** is a monorepo for designing, deploying, and operating tokenized financial assets (equities, bonds) on the **Hedera network**, plus a **Mass Payout** framework for batch payment distributions. + +- **License:** Apache-2.0 +- **Node.js:** v20.19.4+ (ATS), v24.0.0+ (Mass Payout backend) +- **npm:** v10.9.0+ +- **Package manager:** npm workspaces (no pnpm/yarn) + +## Monorepo Layout + +``` +packages/ + ats/ + contracts/ # Solidity smart contracts (Hardhat, diamond pattern, ERC-1400/ERC-3643) + sdk/ # TypeScript SDK (Hexagonal Architecture, DDD, CQRS) + mass-payout/ + contracts/ # Solidity payout contracts (Hardhat) + sdk/ # TypeScript SDK for payout flows + eslint-config/ # Shared ESLint config (@hashgraph/eslint-config) +apps/ + ats/web/ # React 18 dApp for asset management + mass-payout/ + backend/ # NestJS + PostgreSQL API + frontend/ # React + Chakra UI admin panel + docs/ # Docusaurus documentation site +``` + +## Build & Development Commands + +### Full Setup + +```bash +npm run setup # Install deps + build everything +npm run ats:setup # ATS only (contracts + SDK + web) +npm run mass-payout:setup # Mass Payout only +``` + +### Build + +```bash +npm run ats:build # Build ATS contracts โ†’ SDK โ†’ web +npm run ats:contracts:build # Contracts only (needs NODE_OPTIONS='--max-old-space-size=8192') +npm run ats:contracts:compile # Solidity compilation only (hardhat compile) +npm run ats:sdk:build # SDK only +npm run mass-payout:build # Build all Mass Payout modules +``` + +### Run Dev Servers + +```bash +npm run ats:web:dev # ATS web app dev server +npm run mass-payout:frontend:dev # Mass Payout frontend dev +npm run mass-payout:backend:dev # Mass Payout backend (NestJS) +npm run ats:contracts:local:hardhat # Local Hardhat node +``` + +### Lint & Format + +```bash +npm run lint # All linting (JS + Solidity) +npm run lint:fix # Auto-fix all +npm run ats:lint:sol # Solhint for ATS contracts +npm run format # Prettier (all files) +npm run format:check # Prettier check only +``` + +## Testing + +### ATS Contracts (Hardhat + Chai) + +```bash +# All contract tests +npm run ats:contracts:test + +# Single test file +cd packages/ats/contracts && npx hardhat test test/contracts/integration/layer_1/hold/hold.test.ts + +# Parallel execution +npm run ats:contracts:test:parallel + +# Scripts tests (unit + integration) +npm run ats:contracts:test:scripts +npm run ats:contracts:test:scripts:unit +npm run ats:contracts:test:scripts:integration + +# Coverage +npm run ats:contracts:test:coverage +``` + +### ATS SDK (Jest) + +```bash +npm run ats:sdk:test +# Single test +cd packages/ats/sdk && npx jest path/to/test.ts +``` + +### ATS Web (Vitest/Jest) + +```bash +npm run ats:web:test +``` + +### Mass Payout + +```bash +npm run mass-payout:test +npm run mass-payout:contracts:test +npm run mass-payout:sdk:test +``` + +## Architecture + +### Smart Contracts โ€” Diamond Pattern (EIP-2535) + +Contracts use the **Diamond pattern** with modular facets organized in layers: + +- **Layer 1 (core):** accessControl, cap, clearing, controlList, corporateAction, ERC1400, ERC3643, freeze, hold, kyc, lock, nonce, pause, snapshot, ssi, totalBalance, externalPause, externalControlList, externalKycList, protectedPartition +- **Layer 2 (financial):** bond, equity, security, adjustBalance, interestRate, kpi, nominalValue, proceedRecipient, scheduledTask +- **Layer 3 (jurisdiction-specific):** bondUSA, equityUSA, transferAndLock + +Key contracts: + +- `contracts/factory/` โ€” Factory contracts for deploying new security tokens +- `contracts/domain/` โ€” Domain-specific logic and storage +- `contracts/infrastructure/` โ€” Diamond proxy and resolver infrastructure + +### SDK โ€” Hexagonal Architecture + +``` +src/ + port/in/ # Input ports (API interfaces per domain: equity, bond, factory, role, kyc...) + port/out/ # Output ports (external integrations) + app/usecase/ # Use cases split into command/ and query/ (CQRS) + app/service/ # Application services + domain/context/ # Domain models and contexts + core/ # Shared kernel +``` + +Uses **tsyringe** for dependency injection. + +### Ethers v6 + +This project uses **ethers v6**. Key patterns: + +- `contract.target` (not `contract.address`) +- Native `bigint` (not `BigNumber`) +- `ethers.ZeroAddress` / `ethers.ZeroHash` (not `ethers.constants.*`) +- `signer.signTypedData(...)` (not `_signTypedData`) + +### Test Structure (Contracts) + +``` +test/ + contracts/ + integration/ + layer_1/ # Tests per facet (hold, lock, erc3643, freeze, etc.) + layer_2/ # Bond, equity, scheduled tasks tests + factory/ # Factory deployment tests + resolver/ # BusinessLogicResolver tests + resolverProxy/ + scripts/ # Deployment script tests (unit + integration) + fixtures/ # Shared test fixtures +``` + +Tests use Hardhat's `loadFixture` for efficient state snapshotting. + +## Deployment + +```bash +# Deploy to local Hardhat node +npm run ats:contracts:deploy:local + +# Deploy to Hedera networks +npm run ats:contracts:deploy:hedera:testnet +npm run ats:contracts:deploy:hedera:mainnet + +# Upgrade existing deployment +npm run ats:contracts:upgrade:configs +npm run ats:contracts:upgrade:tup # Transparent Upgradeable Proxy +``` + +Environment files: copy `.env.example` โ†’ `.env` in each package/app directory. + +## Commit Conventions + +- **Conventional Commits:** `(): ` +- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` +- Scopes: `ats:contracts`, `ats:sdk`, `ats:web`, `mp:backend`, `mp:frontend`, `mp:contracts`, `mp:sdk` +- **DCO sign-off required:** `git commit --signoff -S -m "..."` +- **GPG signature required** for pushes +- **Changesets required** for package changes: `npm run changeset` + +### Git Hooks (Husky) + +- `pre-commit` โ€” lint-staged +- `commit-msg` โ€” commitlint + auto-adds DCO sign-off +- `pre-push` โ€” blocks without DCO + GPG + +## PR Guidelines + +- Target the integration branch (**`develop`** or **`development`** depending on the active workflow), not `main` +- Changeset file required (bypass with labels: `no-changeset`, `docs-only`, `chore`, `hotfix`) +- CI runs tests only for changed modules + +## AI Agent Integration + +This project uses the [AGENTS.md](https://agents.md/) convention for agent context and the [Agent Skills](https://agentskills.io/) standard for shared automation. + +### Structure + +``` +AGENTS.md # Root context for any AI agent (this file) +CLAUDE.md # Symlink โ†’ AGENTS.md (committed, for Claude Code) +GEMINI.md # Symlink โ†’ AGENTS.md (committed, for Gemini CLI) +.agents/ + skills/ # Agent Skills (agentskills.io standard) + / + SKILL.md # Required: metadata + instructions + scripts/ # Optional: executable code + references/ # Optional: documentation + assets/ # Optional: templates, resources +packages/ + ats/contracts/AGENTS.md # ATS Solidity contracts (Diamond, ethers v6) + ats/sdk/AGENTS.md # ATS TypeScript SDK (hexagonal, CQRS) + eslint-config/AGENTS.md # Shared ESLint preset + mass-payout/contracts/AGENTS.md # Mass Payout Solidity contracts + mass-payout/sdk/AGENTS.md # Mass Payout TypeScript SDK +apps/ + ats/web/AGENTS.md # ATS dApp (React + Vite + Chakra UI) + mass-payout/backend/AGENTS.md # Mass Payout NestJS API (PostgreSQL) + mass-payout/frontend/AGENTS.md # Mass Payout admin panel (React + Chakra) + docs/AGENTS.md # Docusaurus documentation site +``` + +Agent-specific workspaces (`.claude/`, `.gemini/`, โ€ฆ) are **local-only** (gitignored) โ€” each agent generates them on session start. Only two committed concessions exist for cross-agent compatibility: `CLAUDE.md` and `GEMINI.md` at the repo root are kept as **symlinks to `AGENTS.md`**, so every agent reads the same source of truth without duplication. + +### How It Works + +1. **`AGENTS.md`** (root) is the single source of truth for project context โ€” any agent reads it. +2. **Skills** live in `.agents/skills//SKILL.md` following the [Agent Skills spec](https://agentskills.io/specification). They are auto-discovered by most compatible agents (Gemini CLI, OpenAI Codex, Cursor, VS Code, GitHub Copilot, etc.). +3. **Package- and app-level `AGENTS.md`** provide context scoped to a specific module. Every workspace under `packages/` and `apps/` ships one โ€” start there before reading the root file when working inside a single module. + +### Agent Skills Format + +Each skill is a directory under `.agents/skills/` containing a `SKILL.md` with YAML frontmatter: + +```yaml +--- +name: skill-name # Required. Lowercase a-z + hyphens. Must match directory name. +description: > # Required. What the skill does and when to use it. + Describe exactly when this skill should trigger. +license: Apache-2.0 # Optional. +compatibility: "" # Optional. Environment requirements. +metadata: # Optional. Arbitrary key-value pairs. + author: example-org + version: "1.0" +--- +# Skill Instructions + +Step-by-step instructions for the agent... +``` + +**Rules:** + +- `name`: 1-64 chars, lowercase `a-z` + hyphens, no leading/trailing/consecutive hyphens, must match directory name +- `description`: 1-1024 chars, should include keywords that help agents identify relevant tasks +- Keep `SKILL.md` under 500 lines โ€” move detailed content to `references/` files +- Progressive disclosure: agents load metadata at startup, full instructions only when activated + +### Agent Setup on Init + +When starting a session, each agent must self-configure based on its own requirements: + +**Claude Code** โ€” Reads `CLAUDE.md` (shipped as a symlink to `AGENTS.md`) for project context. Skills must additionally be symlinked into the local-only `.claude/commands/` directory for slash command support: + +```bash +mkdir -p .claude/commands +for skill in .agents/skills/*/SKILL.md; do + name="$(basename "$(dirname "$skill")")" + ln -sf "../../.agents/skills/$name/SKILL.md" ".claude/commands/$name.md" +done +``` + +**Gemini CLI** โ€” Reads `GEMINI.md` for foundational mandates. The repo ships `GEMINI.md` as a symlink to `AGENTS.md` so the contexts cannot drift. + +**OpenAI Codex / Cursor / VS Code / Others** โ€” No setup needed. These agents discover `.agents/skills/` natively. + +## Technical Standards & Conventions + +### Smart Contracts (Diamond Pattern) + +- **Solidity:** `^0.8.0`, max 120 chars/line, `SCREAMING_SNAKE_CASE` for constants, `_privateVar` for internal state. +- **Ethers v6:** Use `contract.target` (not `.address`), `bigint` (not `BigNumber`), `ethers.ZeroAddress`, `ethers.ZeroHash`, and `signer.signTypedData(...)`. + +### SDK (Hexagonal Architecture) + +- **DI:** `tsyringe` (`reflect-metadata` required). +- **CQRS:** Commands for writes, Queries for reads. + +### TypeScript Imports (project-wide) + +Applies to every TS / TSX file in the monorepo (contracts scripts/tests, SDK, web, mass-payout): + +- **Cross-module:** use TypeScript path aliases (`@scripts/...`, `@contract-types`, `@test`, `@core`, `@app/...` โ€” see each package's `tsconfig.json`). +- **Same-module:** use relative paths (`./sibling`, `../sibling`). +- **Never import from a module's own barrel (`index.ts`)** โ€” causes circular dependencies. Re-export from the barrel, but consume internal siblings via relative paths only. + +### Git & Commits + +- **Conventional Commits:** `(): `. +- **DCO Sign-off:** Every commit **MUST** include `Signed-off-by` (`git commit --signoff`). +- **GPG Signature:** Every commit **MUST** be GPG-signed (`git commit -S`). + +### Available Skills + +- `update-docs` โ€” Update project documentation based on recent commits +- `solidity-natspec` โ€” Produce and validate audit-ready NatSpec on `.sol` files. Auto-triggers when any contract under `packages/ats/contracts/**` is created or modified, or on explicit request (`/solidity-natspec [path]`) for a full pass + +### Notes + +- When running contract tests, always compile first if `artifacts/` is missing +- Use `NODE_OPTIONS='--max-old-space-size=8192'` for contract compilation and web builds +- The SDK requires `NODE_OPTIONS=--max-old-space-size=16384` for test runs +- Ethers v6 is used throughout โ€” never use v5 patterns (`BigNumber`, `contract.address`, `_signTypedData`) +- Commits require DCO sign-off (`--signoff`) and GPG signature (`-S`). Do not skip hooks with `--no-verify` + +## Local Overrides + +Personal, untracked notes live in `*.local.md` files at the repo root. Each agent's loader follows the `@import` lines below and silently skips any file that does not exist, so contributors can keep private rules without diverging from the tracked source of truth. + +- `AGENTS.local.md` โ€” shared overrides loaded by every agent +- `CLAUDE.local.md` โ€” Claude Code-specific overrides +- `GEMINI.local.md` โ€” Gemini CLI-specific overrides + +@AGENTS.local.md +@CLAUDE.local.md +@GEMINI.local.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/README.md b/README.md index eb503a7377..b74c128fc5 100644 --- a/README.md +++ b/README.md @@ -307,6 +307,22 @@ Each submodule provides additional test options (unit, e2e, coverage). - WalletConnect for dApp integration - Custodian libraries: Dfns, Fireblocks, AWS KMS +## AI Agent Integration + +This project uses the [AGENTS.md](https://agents.md/) convention for agent context and the [Agent Skills](https://agentskills.io/) open standard for shared automation skills. + +``` +AGENTS.md # Project context for any AI agent +.agents/ + skills/ # Agent Skills (agentskills.io standard) + update-docs/SKILL.md # Update docs based on recent commits +packages/ + ats/contracts/AGENTS.md # Contract-specific agent context + ats/sdk/AGENTS.md # SDK-specific agent context +``` + +No agent-specific directories are committed. Each agent reads `AGENTS.md` and self-configures on session start. Skills in `.agents/skills/` are auto-discovered by compatible agents (Gemini CLI, OpenAI Codex, Cursor, VS Code, GitHub Copilot, and others). To add a new skill, create `.agents/skills//SKILL.md` following the [spec](https://agentskills.io/specification). + ## Continuous Integration The project uses separate GitHub Actions workflows for different components: diff --git a/apps/ats/web/AGENTS.md b/apps/ats/web/AGENTS.md new file mode 100644 index 0000000000..3f427c4271 --- /dev/null +++ b/apps/ats/web/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md โ€” ATS Web (dApp) + +React 18 dApp for managing tokenized assets on top of the ATS SDK. Built with **Vite** + **Chakra UI**. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `ats:web:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run ats:web:dev # Dev server (Vite) +npm run ats:web:build # Production build +npm run ats:web:test # Vitest / Jest tests +npm run ats:lint # ESLint (workspace-wide) +npm run ats:format # Prettier (workspace-wide) +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd apps/ats/web +npm run dev # Dev server (Vite) +npm run build # Production build +npm run test # Vitest / Jest tests +npm run lint # ESLint +npm run format # Prettier +``` + +## Scope + +- End-user UI for issuers, custodians, and operators interacting with ATS securities. +- Consumes `@hashgraph/asset-tokenization-sdk` (workspace) for all on-chain logic. + +## Conventions + +- React 18 + TypeScript, Chakra UI for styling, i18next for i18n. +- **State management:** Zustand (no Redux). +- **Routing:** React Router v6. +- **Tests:** Jest + React Testing Library + snapshot suite. Use `npm run ats:web:test:update` to refresh snapshots after intentional UI changes. +- **Imports:** absolute paths via `tsconfig.json` `paths` aliases โ€” no `../../../` chains. See root `AGENTS.md` ยง TypeScript Imports. +- Wallet integrations: MetaMask, WalletConnect, Hedera-native via the SDK. +- Build memory: `NODE_OPTIONS='--max-old-space-size=8192'` if the build OOMs. diff --git a/apps/ats/web/CLAUDE.md b/apps/ats/web/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/ats/web/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/ats/web/GEMINI.md b/apps/ats/web/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/ats/web/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md new file mode 100644 index 0000000000..c446baa51e --- /dev/null +++ b/apps/docs/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md โ€” Documentation Site + +**Docusaurus** site that serves as the public documentation hub for Asset Tokenization Studio. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `docs:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run docs:start # Local dev server with hot reload +npm run docs:build # Production build (static site) +npm run docs:serve # Serve the built site locally +npm run docs:clean # Clear Docusaurus cache and build output +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd apps/docs +npm run start # Local dev server with hot reload +npm run build # Production build (static site) +npm run serve # Serve the built site locally +npm run clean # Clear Docusaurus cache and build output +``` + +## Scope + +- User-facing docs: getting started, architecture overviews, API references, agent integration guide. +- Source content lives under `docs/` at the repo root, surfaced through this Docusaurus app. + +## Conventions + +- Markdown / MDX content; respect existing sidebar structure in `sidebars.js` (or equivalent config). +- Cross-link to package-level `AGENTS.md` files when documenting agent behaviour, do not duplicate. +- Keep examples in sync with the SDK โ€” outdated snippets are worse than missing ones. diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/docs/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/docs/GEMINI.md b/apps/docs/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/docs/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/mass-payout/backend/AGENTS.md b/apps/mass-payout/backend/AGENTS.md new file mode 100644 index 0000000000..6d86266821 --- /dev/null +++ b/apps/mass-payout/backend/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md โ€” Mass Payout Backend + +NestJS API backing the Scheduler Payment Distribution flow. Persists state in **PostgreSQL** via TypeORM. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `mass-payout:backend:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run mass-payout:backend:build # Build NestJS app +npm run mass-payout:backend:test # Jest tests +npm run mass-payout:lint # ESLint (workspace-wide) +npm run mass-payout:format # Prettier (workspace-wide) +``` + +Or from inside this package, run the unprefixed scripts (includes dev-only `start:dev` watch mode): + +```bash +cd apps/mass-payout/backend +npm run start # Run in production mode +npm run start:dev # Watch mode (dev-only) +npm run build # Build NestJS app +npm run test # Jest tests +npm run lint # ESLint +npm run format # Prettier +``` + +## Scope + +- Orchestrates batch payouts, exposes REST/HTTP endpoints, and persists schedules and runs. +- Consumes `@hashgraph/mass-payout-sdk` (workspace) to interact with the on-chain contracts. + +## Conventions + +- NestJS modules + TypeORM entities. Migrations live alongside the app โ€” do not edit the DB schema by hand. +- Requires Node v24.0.0+ (per root `AGENTS.md`). +- Copy `.env.example` โ†’ `.env` for local runs. diff --git a/apps/mass-payout/backend/CLAUDE.md b/apps/mass-payout/backend/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/mass-payout/backend/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/mass-payout/backend/GEMINI.md b/apps/mass-payout/backend/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/mass-payout/backend/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/mass-payout/frontend/AGENTS.md b/apps/mass-payout/frontend/AGENTS.md new file mode 100644 index 0000000000..337d8fc6b3 --- /dev/null +++ b/apps/mass-payout/frontend/AGENTS.md @@ -0,0 +1,36 @@ +# AGENTS.md โ€” Mass Payout Frontend + +Admin panel for the Scheduler Payment Distribution service. React + **Chakra UI**. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `mass-payout:frontend:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run mass-payout:frontend:dev # Dev server +npm run mass-payout:frontend:build # Production build +npm run mass-payout:frontend:test # Tests +npm run mass-payout:lint # ESLint (workspace-wide) +npm run mass-payout:format # Prettier (workspace-wide) +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd apps/mass-payout/frontend +npm run dev # Dev server +npm run build # Production build +npm run test # Tests +npm run lint # ESLint +npm run format # Prettier +``` + +## Scope + +- UI for operators to schedule, monitor, and audit payout runs. +- Talks to `apps/mass-payout/backend` over HTTP; does not call contracts directly. + +## Conventions + +- React + TypeScript + Chakra UI, mirroring `apps/ats/web` styling stack. +- i18n via i18next (locale files under `src/locales/` if/when added). diff --git a/apps/mass-payout/frontend/CLAUDE.md b/apps/mass-payout/frontend/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/mass-payout/frontend/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/apps/mass-payout/frontend/GEMINI.md b/apps/mass-payout/frontend/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/apps/mass-payout/frontend/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/docs/references/guides/ai-agent-integration.md b/docs/references/guides/ai-agent-integration.md new file mode 100644 index 0000000000..4ef6127d70 --- /dev/null +++ b/docs/references/guides/ai-agent-integration.md @@ -0,0 +1,126 @@ +--- +id: ai-agent-integration +title: AI Agent Integration +sidebar_label: AI Agent Integration +--- + +# AI Agent Integration + +This project uses two open standards to provide consistent context and automation to AI coding agents: + +- **[AGENTS.md](https://agents.md/)** โ€” A standard file for giving AI agents project context (build commands, architecture, conventions) +- **[Agent Skills](https://agentskills.io/)** โ€” A standard format for reusable agent capabilities (`SKILL.md` files) + +These standards are supported by Claude Code, Gemini CLI, OpenAI Codex, Cursor, VS Code, GitHub Copilot, and many others. + +## Directory Structure + +``` +AGENTS.md # Root context โ€” any AI agent reads this +CLAUDE.md # Symlink โ†’ AGENTS.md (committed, for Claude Code) +GEMINI.md # Symlink โ†’ AGENTS.md (committed, for Gemini CLI) +.agents/ + skills/ # Agent Skills (agentskills.io standard) + update-docs/ + SKILL.md # Skill definition with YAML frontmatter + solidity-natspec/ + SKILL.md +packages/ + ats/contracts/AGENTS.md # ATS Solidity contracts (Diamond, ethers v6) + ats/sdk/AGENTS.md # ATS TypeScript SDK (hexagonal, CQRS) + eslint-config/AGENTS.md # Shared ESLint preset + mass-payout/contracts/AGENTS.md # Mass Payout Solidity contracts + mass-payout/sdk/AGENTS.md # Mass Payout TypeScript SDK +apps/ + ats/web/AGENTS.md # ATS dApp (React + Vite + Chakra UI) + mass-payout/backend/AGENTS.md # Mass Payout NestJS API (PostgreSQL) + mass-payout/frontend/AGENTS.md # Mass Payout admin panel + docs/AGENTS.md # Docusaurus documentation site +``` + +Agent-specific directories (`.claude/`, `.gemini/`, etc.) are **not committed** โ€” they are local-only workspaces each agent generates on session start. The only committed concession is the pair of root symlinks `CLAUDE.md` and `GEMINI.md` pointing to `AGENTS.md`, so every agent reads the same source of truth without duplication. + +## How It Works + +### 1. Context Files (`AGENTS.md`) + +The root `AGENTS.md` contains everything an agent needs to understand the project: + +- Monorepo layout and package relationships +- Build, test, lint, and deploy commands +- Architecture overview (diamond pattern, hexagonal SDK, CQRS) +- Coding conventions (ethers v6, commit format, etc.) + +Package- and app-level `AGENTS.md` files provide additional context scoped to that module. Every workspace under `packages/` and `apps/` ships one โ€” agents working inside a single module should read the local file first, then the root for cross-cutting context. + +### 2. Skills (`.agents/skills/`) + +Skills follow the [Agent Skills specification](https://agentskills.io/specification). Each skill is a directory with a `SKILL.md` file containing YAML frontmatter: + +```yaml +--- +name: skill-name +description: What this skill does and when to use it. +--- +``` + +Required fields: `name` (lowercase, hyphens only, must match directory name) and `description`. + +Skills in `.agents/skills/` are **auto-discovered** by most compatible agents โ€” no manual configuration needed. + +**Current skills:** + +| Skill | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `update-docs` | Update project documentation based on recent commits | +| `solidity-natspec` | Produce and validate audit-ready NatSpec on `.sol` files. Auto-triggers on any contract under `packages/ats/contracts/**`, or via `/solidity-natspec`. | + +### 3. Agent Self-Configuration + +Each agent reads `AGENTS.md` on session start and configures itself: + +| Agent | `.agents/skills/` discovery | Extra setup needed | +| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ | +| Gemini CLI | Native | None โ€” reads `GEMINI.md` (committed symlink to `AGENTS.md`) | +| OpenAI Codex | Native | None | +| Cursor | Native | None | +| VS Code (Copilot) | Native | None | +| GitHub Copilot | Native | None | +| Claude Code | Not native | Reads `CLAUDE.md` (committed symlink to `AGENTS.md`); skills must be linked into `.claude/commands/` on init | + +For Claude Code, `CLAUDE.md` is already provided as a symlink in the repo; the agent additionally creates the local-only `.claude/commands/` symlinks on session start using the snippet documented in `AGENTS.md`. + +## Adding a New Skill + +1. Create the skill directory: + +``` +.agents/skills/my-skill/ + SKILL.md +``` + +2. Write `SKILL.md` following the [spec](https://agentskills.io/specification): + +```markdown +--- +name: my-skill +description: What this skill does and when to use it. +--- + +# My Skill + +Instructions for the agent... +``` + +3. Compatible agents will discover it automatically on next session start. + +## Adding a New Agent + +No repo changes needed. If the agent supports AGENTS.md or Agent Skills, it works out of the box. If the agent needs specific config (like Claude's symlinks), add setup instructions to the "Agent Setup on Init" section in `AGENTS.md`. + +## Best Practices + +- **Keep `AGENTS.md` as the single source of truth** โ€” No duplication across agent-specific files +- **Follow the [Agent Skills spec](https://agentskills.io/specification)** โ€” Use proper `name` and `description` frontmatter +- **No agent-specific directories committed** โ€” Agents self-configure at runtime; only the `CLAUDE.md` and `GEMINI.md` root symlinks to `AGENTS.md` are committed +- **Package- and app-level `AGENTS.md`** โ€” Every workspace under `packages/` and `apps/` ships one with its quick reference, scope, and conventions; root context covers the cross-cutting parts diff --git a/docs/references/index.md b/docs/references/index.md index f8dc8b59df..4b09bde149 100644 --- a/docs/references/index.md +++ b/docs/references/index.md @@ -10,6 +10,7 @@ Technical references and guides for the Asset Tokenization Studio project. ## Contents -### [Guides](./guides/ci-cd-workflows) +### Guides -Additional technical guides and references. +- [CI/CD Workflows](./guides/ci-cd-workflows) โ€” Automated CI/CD pipeline documentation +- [AI Agent Integration](./guides/ai-agent-integration) โ€” How AI coding agents are configured in this project diff --git a/package.json b/package.json index 7d9eeaa6b1..948d2cb6ee 100644 --- a/package.json +++ b/package.json @@ -47,7 +47,8 @@ "format:staged:check": "prettier --check", "pre-commit": "lint-staged", "commitlint": "commitlint --edit", - "prepare": "husky", + "prepare": "husky && bash .scripts/agents-setup.sh", + "agents:setup": "bash .scripts/agents-setup.sh", "changeset": "changeset", "changeset:version": "changeset version && npm install --package-lock-only && npm run format", "changeset:publish": "changeset publish", diff --git a/packages/ats/contracts/AGENTS.md b/packages/ats/contracts/AGENTS.md new file mode 100644 index 0000000000..5796f5d938 --- /dev/null +++ b/packages/ats/contracts/AGENTS.md @@ -0,0 +1,70 @@ +# AGENTS.md โ€” ATS Contracts + +Solidity smart contracts for the Asset Tokenization Studio. Uses **Hardhat** + **ethers v6** + **Chai**. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `ats:contracts:*` / `ats:lint:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run ats:contracts:compile # Compile contracts +npm run ats:contracts:test # All contract tests +npm run ats:contracts:test:parallel # All tests in parallel +npm run ats:contracts:test:coverage # Coverage +npm run ats:lint:sol # Solhint +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd packages/ats/contracts +npm run compile # Compile contracts +npm run test # All contract tests +npm run test -- test/contracts/integration/layer_1/hold/hold.test.ts # Single test +npm run lint:sol # Solhint +npm run size # Contract sizes +``` + +## Architecture + +**Diamond pattern (EIP-2535)** with facets in three layers: + +| Layer | Purpose | Facets | +| ----- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| L1 | Core token features | accessControl, cap, ERC1400, ERC3643, freeze, hold, kyc, lock, pause, snapshot, nonce, clearing, controlList, corporateAction, ssi, totalBalance, externalPause, externalControlList, externalKycList, protectedPartition | +| L2 | Financial instruments | bond, equity, security, adjustBalance, interestRate, kpi, nominalValue, proceedRecipient, scheduledTask | +| L3 | Jurisdiction-specific | bondUSA, equityUSA, transferAndLock | + +- `contracts/factory/` โ€” Factory + factory proxy for deploying securities +- `contracts/domain/` โ€” Storage structs and domain logic +- `contracts/infrastructure/` โ€” Diamond proxy, resolver, upgradeability (TUP) + +## Solidity Conventions + +- Solidity `>=0.8.0 <0.9.0` +- Max line length: 120 chars +- Double quotes for strings +- `CONSTANT_NAME` for constants (SCREAMING_SNAKE_CASE) +- `_privateVar` leading underscore for private/internal state +- `functionName` mixedCase for functions +- OpenZeppelin v4.9.x for base contracts + +## Testing Conventions + +- Tests use `loadFixture` from `@nomicfoundation/hardhat-network-helpers` +- Ethers v6 patterns: `contract.target`, native `bigint`, `ethers.ZeroAddress` +- Event parsing: use `contract.interface.parseLog()` on `receipt.logs` +- Test organization mirrors facet structure in `test/contracts/integration/` +- Deployment script tests in `test/scripts/` (unit + integration) +- **`confirmations: 0`** for Hardhat and instant networks โ€” anything higher hangs deploys for minutes +- **No magic strings or numbers in tests** โ€” use the shared `@test` constants (`TEST_ADDRESSES`, `TEST_NETWORKS`, `TEST_CONFIG_IDS`, etc.). Don't introduce new hardcoded literals +- **Full-length hex strings** for `bytes32`, addresses, and tx hashes โ€” no shorthand +- **Path aliases** (`@scripts/infrastructure`, `@contract-types`, `@test`) for cross-module imports; relative paths inside the same module โ€” see root `AGENTS.md` ยง TypeScript Imports + +## Domain Notes + +### Bond โ€” Coupon System + +- A coupon schedule is auto-created during deployment when `firstCouponDate > 0` โ€” `_setFixedCoupons` derives the schedule from `couponFrequency` ร— maturity. +- Adding a coupon manually after deployment uses `setCoupon` and requires the `CORPORATE_ACTION_ROLE`. +- Coupon facets live under `contracts/domain/asset/coupon/` and the `coupon` L2 facet. diff --git a/packages/ats/contracts/CLAUDE.md b/packages/ats/contracts/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/ats/contracts/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/ats/contracts/GEMINI.md b/packages/ats/contracts/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/ats/contracts/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/ats/sdk/AGENTS.md b/packages/ats/sdk/AGENTS.md new file mode 100644 index 0000000000..51916b2848 --- /dev/null +++ b/packages/ats/sdk/AGENTS.md @@ -0,0 +1,51 @@ +# AGENTS.md โ€” ATS SDK + +TypeScript SDK for the Asset Tokenization Studio. Uses **Jest** for testing. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `ats:sdk:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run ats:sdk:build # Build ESM + CJS +npm run ats:sdk:test # All tests (Jest, runInBand) +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd packages/ats/sdk +npm run build # Build ESM + CJS +npm run test # All tests (Jest, runInBand) +npm run test -- path/to/file.test.ts # Single test +npm run lint # ESLint +npm run format # Prettier +``` + +## Architecture โ€” Hexagonal + DDD + CQRS + +``` +src/ + port/in/ # Input ports โ€” domain-specific interfaces + # account, bond, equity, factory, kyc, role, security, + # scheduledTask, event, management, network, etc. + port/out/ # Output ports โ€” external system adapters + app/ + usecase/ + command/ # Write operations (CQRS command side) + query/ # Read operations (CQRS query side) + service/ # Application services, orchestration + domain/context/ # Domain models, value objects, aggregates + core/ # Shared kernel, base classes +``` + +- **DI container:** tsyringe (`reflect-metadata` required) +- **Dual build:** ESM (`build/esm/`) + CJS (`build/cjs/`) +- Depends on `@hashgraph/asset-tokenization-contracts` (workspace dependency) + +## Key Integrations + +- Hedera SDK (`@hashgraph/sdk`) +- WalletConnect (`@hashgraph/hedera-wallet-connect`, `@reown/appkit`) +- Custodians: Dfns, Fireblocks, AWS KMS via `@hashgraph/hedera-custodians-integration` +- MetaMask (`@metamask/detect-provider`) diff --git a/packages/ats/sdk/CLAUDE.md b/packages/ats/sdk/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/ats/sdk/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/ats/sdk/GEMINI.md b/packages/ats/sdk/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/ats/sdk/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/mass-payout/contracts/AGENTS.md b/packages/mass-payout/contracts/AGENTS.md new file mode 100644 index 0000000000..2cde725b01 --- /dev/null +++ b/packages/mass-payout/contracts/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md โ€” Mass Payout Contracts + +Solidity contracts for the **Scheduler Payment Distribution** flow. Uses **Hardhat** + **ethers v6**. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `mass-payout:contracts:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run mass-payout:contracts:build # Compile contracts +npm run mass-payout:contracts:test # Hardhat tests +npm run mass-payout:contracts:compile # Solidity compilation only +npm run mass-payout:lint # Solhint (workspace-wide) +npm run mass-payout:format # Prettier (workspace-wide) +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd packages/mass-payout/contracts +npm run build # Compile contracts +npm run test # Hardhat tests +npm run lint # Solhint +npm run format # Prettier +``` + +## Scope + +- Batch payment distribution contracts orchestrated by the Mass Payout SDK / backend. +- Independent from ATS contracts โ€” no diamond facets here, simpler standalone contracts. + +## Conventions + +- Solidity `>=0.8.0 <0.9.0`, ethers v6 patterns (`contract.target`, `bigint`, `ethers.ZeroAddress`). +- Same NatSpec house style as ATS: see the root `solidity-natspec` skill. diff --git a/packages/mass-payout/contracts/CLAUDE.md b/packages/mass-payout/contracts/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/mass-payout/contracts/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/mass-payout/contracts/GEMINI.md b/packages/mass-payout/contracts/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/mass-payout/contracts/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/mass-payout/sdk/AGENTS.md b/packages/mass-payout/sdk/AGENTS.md new file mode 100644 index 0000000000..9a396c13e8 --- /dev/null +++ b/packages/mass-payout/sdk/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md โ€” Mass Payout SDK + +TypeScript SDK that drives the Scheduler Payment Distribution contracts. + +## Quick Reference + +All commands are exposed at the **monorepo root** with the `mass-payout:sdk:*` prefix โ€” see root `AGENTS.md` ยง Build & Development Commands: + +```bash +npm run mass-payout:sdk:build # Build the SDK +npm run mass-payout:sdk:test # Jest tests +npm run mass-payout:lint # ESLint (workspace-wide) +npm run mass-payout:format # Prettier (workspace-wide) +``` + +Or from inside this package, run the unprefixed scripts: + +```bash +cd packages/mass-payout/sdk +npm run build # Build the SDK +npm run test # Jest tests +npm run lint # ESLint +npm run format # Prettier +``` + +## Scope + +- Wraps the Mass Payout contracts with high-level use cases (schedule payouts, batch distribution). +- Consumed by `apps/mass-payout/backend` and `apps/mass-payout/frontend`. + +## Conventions + +- Ethers v6 only (no `BigNumber`, `_signTypedData`, `contract.address`). +- Workspace dependency on `@hashgraph/mass-payout-contracts` for typed contract bindings. diff --git a/packages/mass-payout/sdk/CLAUDE.md b/packages/mass-payout/sdk/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/mass-payout/sdk/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/mass-payout/sdk/GEMINI.md b/packages/mass-payout/sdk/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/packages/mass-payout/sdk/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md