Sui architect

Skill first-mover-tw/sui-dev-agents/skills/sui-architect

Use when planning SUI Move architecture, generating technical specs, or designing object/module structure before writing code. Triggers on "design", "architect", "plan the contracts", "object model", "module structure", "how should I structure", or any SUI system design task. For new projects from scratch, use sui-full-stack (which calls this skill at Phase 1). For ecosystem tool/stack selection (Walrus vs IPFS, zkLogin vs Passkey), use sui-tools-guide.From its SKILL.md

Install

npx -y skills add first-mover-tw/sui-dev-agents --skill sui-architect

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

10.4 KB, as published. Nobody here has run it

SUI Architect

Transform ideas into complete SUI Move project architectures and specifications.

Overview

This skill guides you from a rough idea to a complete, well-documented architecture through:

Guided questioning (one question at a time)
Project type templates (DeFi, NFT, GameFi, DAO, etc.)
Best practice references from similar projects
SUI ecosystem tool integration suggestions
Comprehensive specification document generation

Quick Start

# Start architecture planning
sui-architect

# Or called by main orchestrator
sui-full-stack  # → Phase 1: Architecture

SUI Protocol 127 Architecture Considerations (shipped testnet v1.74.0; now mainnet v1.77.2 / P133)

When designing architectures, account for these recent platform changes:

Protocol Version 127 (shipped testnet v1.74.0; mainnet now v1.77.2 / P133) — enables always_advance_dkg_to_resolution (fixes P126), Ristretto255 group ops + Bulletproofs on testnet, timestamp-based epoch close on mainnet, gRPC SimulateTransaction accepts gas_price=0 (gasless tier).
Protocol Versions 131-133 (mainnet v1.77.2, live since 2026-08-13) — P131 framework_tx_context_mut_restrictions restricts system-package functions only (user packages unaffected); new ForwardingAddressRegistry system object (0x2::forwarding_address, ID 0xfa) is devnet-gated, not yet on mainnet. Move-authoring depth → see sui-developer's Protocol Updates section.
Data Access: gRPC (GA, backend/low-latency/streaming default), GraphQL RPC (GA, frontend/indexer/complex queries), JSON-RPC (shut off on public fullnodes since 2026-07-31, Quorum Driver disabled)
Address Balances (Mainnet, P125): Native address-held balances for supported coin types — PTBs can debit/credit them directly without manual coin select/split/merge. Additive, not a replacement: flows that take Coin<T> still need coin objects.
Gasless Stablecoin Transfers (Mainnet, P125, rolling out): Accumulator + coin reservations let users move USDC etc. without holding SUI for gas.
Display V2 (Activated): Display Registry (0xd) live on all networks — prioritized over legacy Display v1. Plan new projects around Display V2.
Balance API Split: coinBalance (fungible coins only) and addressBalance (all balance types)
Other platform/runtime notes (P126 + earlier rollouts): entry-fn signature check disabled & non-public entry fns can't take hot-potato-entangled args; TxContext flexible positioning (no longer must be last param); poseidon_bn254 on all networks; Adaptive Concurrency (Processor::FANOUT removed → ConcurrencyConfig); DeepBook explicit Move.toml dep (v1.47+); Address Aliases live on mainnet. Move-authoring depth → see sui-developer's Protocol 127 section.
SDK Naming: @mysten/sui (not @mysten/sui.js), Transaction (not TransactionBlock)

Core Workflow

Phase 1: Project Type Identification

Ask user about their project type:

What type of project are you building?
  A) DeFi (AMM, Lending, Staking, Derivatives)
  B) NFT (Marketplace, Gaming, Collectibles)
  C) GameFi (On-chain game logic, Asset management)
  D) DAO (Governance, Treasury, Voting)
  E) Infrastructure (Oracle, Bridge, Identity)
  F) Custom (Mixed or innovative type)

Then narrow down to specific sub-type based on selection.

Phase 2: Template Selection

Based on project type, load starter template with:

Module structure
Common objects/capabilities
Recommended SUI tools

Available templates: nft-marketplace, defi-amm, gamefi, dao, infrastructure

See templates/ for all available templates.

Phase 3: Requirements Exploration

Ask questions one at a time to refine architecture:

User roles and permissions
Core features needed
NFT/token standards (if applicable)
Payment methods
Storage strategy (on-chain, Walrus, IPFS)
Data access pattern (gRPC for current state, GraphQL for frontend queries, custom indexer for historical analytics/aggregation — see sui-indexer)
Upgradeability requirements
Emergency controls

Important: Ask ONE question at a time, wait for answer, then proceed.

Phase 4: Ecosystem Tool Integration

Suggest relevant SUI tools based on requirements:

Storage needed → sui-walrus
Authentication → sui-zklogin or sui-passkey
NFT trading → sui-kiosk
DEX integration → sui-deepbook
Name service → sui-suins
Cross-chain → sui-nautilus
Custom data pipeline / historical analytics → sui-indexer

For the latest integration patterns (e.g. transfer-policy implementation), use the sui-docs-query skill (Context7 MCP).

Phase 5: Best Practice References

For reference implementations and example projects, use the sui-docs-query skill (Context7 MCP) — e.g. "NFT marketplace example Kiosk".

Phase 6: Architecture Design Presentation

Present design in small sections (200-300 words each):

System Overview
Module Architecture
Data Structures
Core Functions
Permission System (Capabilities)
Event System
Error Handling
Security Considerations
Tool Integration Plan
Data Layer (gRPC vs GraphQL vs Custom Indexer — see decision table in sui-indexer)
Testing Strategy
Deployment Plan
Gas Optimization

After each section, ask: "Does this look good?"

Wait for confirmation before proceeding to next section.

Phase 7: Specification Document Generation

Generate comprehensive spec at:

docs/specs/YYYY-MM-DD-[project-name]-spec.md
docs/architecture/module-dependency.mmd
docs/architecture/data-flow.mmd
docs/security/threat-model.md
README.md

See examples.md for complete specification template.

Output Files

Main spec: docs/specs/YYYY-MM-DD-project-spec.md

Contains:

Executive Summary
Architecture Overview (with diagrams)
Module Design
Data Models
API Specification
Security Considerations
Integration Guide (SUI tools)
Testing Strategy
Deployment Plan
Appendix (references, versions)

Additional files:

docs/architecture/overview.md - High-level architecture
docs/architecture/module-dependency.mmd - Mermaid dependency diagram
docs/architecture/data-flow.mmd - Data flow diagram
docs/security/threat-model.md - Threat analysis
README.md - Project overview

Configuration

.sui-architect.json:

{
  "output_dir": "docs/specs",
  "templates": {
    "use_builtin": true,
    "custom_path": null
  },
  "validation": {
    "check_similar_projects": true,
    "query_latest_docs": true,
    "max_questions": 20
  },
  "docs": {
    "generate_mermaid": true,
    "generate_api_docs": true,
    "include_security_analysis": true
  }
}

Configuration options:

output_dir - Where to save spec documents
use_builtin - Use built-in templates (true) or custom
check_similar_projects - Query GitHub for similar implementations
query_latest_docs - Get latest SUI tool documentation
max_questions - Maximum questions to ask (prevents over-questioning)
generate_mermaid - Generate Mermaid diagrams
include_security_analysis - Include security threat model

Integration

Called By

sui-full-stack (Phase 1: Architecture planning)

Calls

sui-docs-query - Query latest SUI tool documentation and GitHub examples

Next Step

After architecture complete, suggest:

console.log("✅ Architecture and specification complete!")
console.log("Next: Ready to start development with sui-developer?")

Best Practices

Question Design

Good questions:

"What types of listings do you want?" (specific, actionable)
"How should royalties work?" (clear options)

Avoid:

"Tell me everything about your project" (too broad)
"Do you want features?" (vague)

Progressive Disclosure

Start broad (project type)
Narrow down (specific features)
Deep dive (implementation details)

Validation Points

After each section, check understanding:

"Does this match your vision?"
"Need to adjust anything?"

Don't proceed until user confirms.

Common Mistakes

❌ Asking too many questions at once

Problem: User overwhelmed, provides vague answers
Fix: Ask ONE question at a time, wait for answer before proceeding

❌ Not validating each section before proceeding

Problem: Architecture doesn't match user's vision, wasted rework
Fix: After each section (Overview, Modules, etc.), ask "Does this look good?"

❌ Skipping ecosystem tool integration suggestions

Problem: User reinvents features already available (Walrus, Kiosk, zkLogin)
Fix: Always query and suggest relevant SUI tools during Phase 4

❌ Generic template without customization

Problem: Spec doesn't reflect project's unique requirements
Fix: Use template as starting point, customize based on Q&A responses

❌ Missing security considerations section

Problem: Security vulnerabilities discovered late in development
Fix: Always include threat model and security analysis in spec

❌ Not checking similar projects on GitHub

Problem: Missed proven patterns, reinventing the wheel
Fix: Query GitHub for similar implementations, reference best practices

❌ Proceeding without clear project type

Problem: Wrong template selected, misaligned architecture
Fix: Phase 1 must complete successfully before Phase 2 template selection