Skip to content

AGENTS.md

Latest commit

 

History

History
193 lines (149 loc) · 9.39 KB

AGENTS.md

File metadata and controls

193 lines (149 loc) · 9.39 KB
Raw

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd prime for full workflow context.

Architecture in one line: Issues live in a local Dolt database (.beads/dolt/); cross-machine sync uses bd dolt push/pull (a git-compatible protocol), stored under refs/dolt/data on your git remote — separate from refs/heads/* where your code lives. .beads/issues.jsonl is a passive export, not the wire protocol.

See SYNC_CONCEPTS.md for the one-screen overview and anti-patterns (don't treat JSONL as the source of truth; don't bd import during normal operation; don't reach for third-party Dolt hosting before trying the default).

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work
bd dolt push          # Push beads data to remote

BEADS_DIR When Running bd Manually

Claude Code's SessionStart hook in .claude/settings.json already sets BEADS_DIR before invoking bd prime, so the automatic hook always targets this project's own .beads/ store. If this machine also has a global BEADS_DIR environment variable exported from the shell profile (pointing at a different project), any bd command you run manually in a terminal outside that hook will use the global value instead and may read/write the wrong store. If bd where ever reports a path outside this repo, run BEADS_DIR="$(pwd)/.beads" bd <command> explicitly, or unset the shell's global BEADS_DIR for this session.

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

  • scp - use -o BatchMode=yes for non-interactive
  • ssh - use -o BatchMode=yes to fail instead of prompting
  • apt-get - use -y flag
  • brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

  • Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
  • Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
  • Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

  1. File issues for remaining work - Create beads for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. Handle git/sync by active profile: 
    # Conservative/minimal/default: report status and proposed commands; wait for approval.
git status

# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
git push
git status
  5. Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

  • Explicit user or orchestrator instructions override this Beads block.
  • Do not commit or push without clear authority from the active profile or the current user request.
  • If a required sync or push is blocked, stop and report the exact command and error.

Beads Issue Tracker

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

  • Use bd for all task tracking; do not create markdown TODO lists.
  • Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
  • Keep persistent project memory in Beads via bd remember; do not create ad hoc memory files.

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Build & Test

SlotScope is a pnpm workspace pinned to Node 24.18.0 and pnpm 11.17.0 (corepack). All direct dependencies are exact versions — the deps:policy gate rejects ranges/tags.

corepack prepare pnpm@11.17.0 --activate
pnpm install --frozen-lockfile
pnpm --filter @slotscope/web exec playwright install chromium  # once, for e2e

pnpm format:check && pnpm lint && pnpm typecheck
pnpm test:unit        # vitest unit + property suites (needs Forge 1.5.1 for the cross-check)
pnpm fixtures:verify  # golden drift check; update ONLY via scripts/verify-fixtures.ts --update
pnpm test:e2e         # Playwright browser suites (builds + previews automatically)
pnpm build && pnpm build:check
pnpm benchmark:v0.1   # after pnpm build; hard 2000ms p95 gates
pnpm release:verify   # release evidence check

Agent-relay gates route these same commands: implementation = quality+unit, delivery = quality+unit+fixtures+build, full = +browser+release, plus a human-only clean-profile demo gate (see .agents/agent-relay/adapter.json).

Architecture Overview

Static React/Vite app; all compilation and execution is local (no application network requests). Full details: docs/architecture.md, ADRs in docs/adr/, honest cut-line in docs/limitations-v1.0.md.

  • packages/domain — locked solc environment, immutable normalized models, UTF-8/UTF-16 index, shared hex primitives
  • packages/compiler — web-worker solc (exact version or fatal), settings-aware Standard JSON, instruction/source-map decoding, normalize()
  • packages/layout — solc storageLayout → exact bigint slot/cell model
  • packages/executor — in-browser EVM worker (EthereumJS, Cancun), keyframe/delta trace, revert/event decode
  • packages/semantics — Layer-3 resolver: keccak-chain grounding → exact/inferred/unresolved
  • packages/lifecycle — generic worker-lifecycle client shared by compiler and executor
  • packages/session — share-URL schema v1/v2 + bounded codec, .slotscope.json
  • packages/challenges — challenge schema, runtime-derived answer validator, progress store
  • packages/ui — design tokens, focus ring, reduced-motion contract
  • packages/fixtures — public fixture corpus, goldens, manifests, Forge cross-check
  • apps/web — composition: CodeMirror editor, assembly pane, probe pane, cockpit bar, execute strip, sharing

Conventions & Patterns

  • Compiler output is the only truth: no Solidity reparsing, no heuristics; anything unexpandable renders as an honest typed span, never a guess.
  • solc reports UTF-8 byte offsets; the editor uses UTF-16 code units — always convert through Utf8IndexMap, never pass offsets directly.
  • Fixture goldens change only through the --update command in a reviewed commit (it prints a semantic diff); CI verifies and never updates.
  • Every animated state needs a persistent border/icon/text equivalent and must pass the keyboard + reduced-motion e2e suites.
  • Correctness/benchmark gates run with zero retries and are never optional.