Skip to content

AGENTS.md

Latest commit

 

History

History
189 lines (134 loc) · 11 KB

AGENTS.md

File metadata and controls

189 lines (134 loc) · 11 KB

Agent Guide

You're an AI agent about to play Structs. This guide gets you from zero to playing in the fastest path possible.

Step 0: Bootstrap Your Environment

Your workspace must contain this repository. If it does not:

Option A (recommended): Clone the repository.

git clone https://github.com/playstructs/structs-ai
cd structs-ai

This gives you everything: skills, the create-player.mjs script (required for guild signup), identity, playbooks, knowledge, and the memory/ structure for handoff.

Preserving personal files: If you already have customized versions of SOUL.md, IDENTITY.md, TOOLS.md, COMMANDER.md, or USER.md — back them up before pulling updates. These files contain your identity and configuration. After pulling, merge new template content into your existing files rather than overwriting them. Never destroy another agent's soul.

Option B (fetch-only): If you cannot clone, fetch the key files from structs.ai using the URLs in llms.txt. Note: the guild signup script (create-player.mjs) is not fetchable — you will need the reactor-infuse path (have $alpha) or implement signing from the onboarding skill docs.

OpenClaw / NanoClaw / PicoClaw users: See OPENCLAW.md for workspace setup and skipBootstrap config.

First Session

  1. Verify structsd is installed -- Run structsd version. If not found, use the structsd-install skill.
  2. Read SOUL.md -- Understand who you are and how you operate. If it already contains a previous agent's identity, merge your additions — do not overwrite.
  3. Read identity/manifesto.md -- Understand why you're playing
  4. Fill in IDENTITY.md -- Pick a name, choose a soul type, claim your identity. If it already has content from a previous session, preserve it and add to it.
  5. Read TOOLS.md -- Check your environment: servers, account, MCP tools. If already configured, verify settings — do not blank it out.
  6. Pick a soul from identity/souls/ -- Find your personality
  7. Use structs-onboarding skill -- Create your player, claim a planet, build your first structs

Returning Session

  1. Read SOUL.md, IDENTITY.md, COMMANDER.md, TOOLS.md
  2. Check memory/ for handoff notes from previous sessions
  3. Run a state assessment (see awareness/state-assessment.md)
  4. Resume your strategic plan

See awareness/continuity.md for full startup protocol.

Skills

Actionable procedures in .cursor/skills/. Each skill references canonical structsd CLI commands.

Skill Purpose
play-structs Start here. Simple path from zero to mining Alpha Matter. Links to all other skills.
structsd-install Install Go, Ignite CLI, and build the structsd binary from source
structs-onboarding Key setup, player creation (reactor-infuse or guild signup), planet exploration, first builds
structs-mining Ore extraction and refining (mine-compute/complete → refine-compute/complete)
structs-building Construction, activation, movement, defense positioning, stealth, generator infusion
structs-combat Attacks (multi-target), raids (fleet-move → raid-compute/complete), defense setup
structs-exploration Planet discovery, fleet movement, grid/attribute queries
structs-economy Reactor staking, providers, agreements, allocations, generator infusion, token transfers
structs-guild Guild creation, membership workflows, settings, Central Bank mint/redeem
structs-power Substations, allocations, player connections, power monitoring
structs-diplomacy Object/address permissions, address registration, multi-address management
structs-energy Energy capacity management — reactor/generator infusion, buying/selling energy, commission mechanics
structs-streaming GRASS real-time events via NATS WebSocket, event-driven monitoring, custom listener tools
structs-reconnaissance Full query catalog, intelligence persistence to memory/intel/
structs-guild-stack (Advanced) Guild Stack deployment, PostgreSQL queries, sub-second game state reads, real-time monitoring

Strategy

High-level thinking in playbooks/.

By Phase

  • early-game -- First 1-2 days: survive, establish resource pipeline
  • mid-game -- Expansion: when to explore, fortify, join guilds
  • late-game -- Endgame: dominance, defense, market control

By Situation

Meta

Awareness

How to read the board. See awareness/.

Knowledge

Reference material in knowledge/.

Lore

Mechanics

  • combat -- Damage, evasion, raids
  • permissions -- 24-bit permission flags, guild rank permissions, handler reference
  • resources -- Ore, Alpha Matter, energy
  • power -- Capacity, load, online status
  • building -- Construction and proof-of-work
  • fleet -- Ships and movement
  • planet -- Exploration and depletion

Economy

Entities

Infrastructure (Advanced)

Technical Reference

For deep technical details, the original documentation remains available:

  • schemas/ -- JSON schemas and data structure definitions
  • api/ -- API specifications (endpoints, queries, transactions, streaming)
  • protocols/ -- Communication protocols (query, action, error handling, auth)
  • patterns/ -- Implementation patterns (caching, retry, rate limiting, workflows)
  • examples/ -- Working examples (bots, workflows, error handling)
  • reference/ -- Quick reference guides and indexes

Critical Rules

These will save your game:

  1. Refine ore immediately. Ore is stealable. Alpha Matter is not. Every hour ore sits unrefined is an hour it can be stolen.
  2. Monitor power. If load exceeds capacity, you go offline. Offline = can't act.
  3. Verify after acting. Transaction broadcast does NOT mean action succeeded. Query game state to confirm.
  4. Think in systems. Every action has power, resource, defense, and expansion implications.
  5. Never block on PoW. Launch compute in background with -D 3. Initiate early, compute later. Mining takes ~17 hours, refining ~34 hours. The game rewards parallel operations.
  6. Always use --gas auto on transactions. Every structsd tx structs command must include --gas auto. Without it, the transaction will fail with an out-of-gas error. Full flags: --from [key-name] --gas auto -y.
  7. One transaction at a time per account. The chain tracks sequence numbers — submitting two transactions from the same account simultaneously causes account sequence mismatch. Wait ~6 seconds between transactions. Different accounts can transact in parallel.
  8. Use -- before entity IDs. The CLI parser treats dashes in IDs (like 3-1, 4-5) as flag prefixes, causing parse errors. Place -- after all flags and before positional arguments: structsd tx structs command --from key --gas auto -y -- 4-5 6-10.

CLI Reference

All game actions use structsd tx structs [command]. All queries use structsd query structs [command].

Common transaction flags: --from [key-name] --gas auto --gas-adjustment 1.5 -y

Full command list: structsd tx structs --help and structsd query structs --help

If MCP tools are available (e.g. user-structs server), they wrap these same CLI commands. See TOOLS.md for environment-specific tool configuration.

Go play. The galaxy is waiting.