Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (62 loc) · 4.86 KB

AGENTS.md

File metadata and controls

83 lines (62 loc) · 4.86 KB
Raw

TokenDanceCode Agent Guide

TokenDanceCode is a local command-line Coding Agent / harness for personal developers. This worktree is the Rust rewrite branch. Keep the scope narrow and explicit: it is not a cloud platform, IDE plugin, marketplace, persistent team-agent system, or AgentHub replacement.

Repository

  • GitHub: TokenDanceLab/TokenDanceCode
  • Public packages: @tokendance/code-core, @tokendance/code-sdk, @tokendance/code-cli
  • Command: tokendance
  • Runtime: Rust 1.95+ for active code; Node.js/pnpm remains only for npm wrapper and legacy TS contract checks.
  • Package manager: Cargo first, pnpm 10+ for npm packaging scripts.
  • Primary shell target: Windows PowerShell

Workspace Rules

  1. This repository is independent from the TokenDance workspace root. Check and commit status inside this repository.
  2. Use repository-local .worktrees/ for isolated work. Do not create sibling worktrees outside the repo.
  3. Do not commit generated state: .env, .tokendance/, .worktrees/, virtualenvs, build outputs, caches, logs, or local transcripts.
  4. Keep public docs secret-free. Use placeholder keys such as your-api-key; never include real provider keys, local account details, private server paths, or production logs.
  5. If the root worktree is behind origin/master, do not treat missing files there as lost progress. Inspect origin/master or create a clean worktree from it first.
  6. Use rg / rg --files for repository search and file discovery. Fall back only when rg cannot answer the query.
  7. Parallel work should use repo-local worktrees and scoped ownership. Do not let two workers edit the same module family unless the coordinator explicitly owns the merge.

Product Boundary

TokenDanceCode focuses on:

  • interactive terminal Coding Agent sessions;
  • local repository reading, editing, shell execution, diff/review, task/todo, transcript, memory, resume, subagent, and worktree workflows;
  • provider-neutral runtime architecture with OpenAI Responses, OpenAI Chat Completions / TokenDance Gateway, and Anthropic-compatible Messages support;
  • AgentHub-consumable SDK facade, event mapping, remote approval bridge, and package manifest metadata.

Do not describe TokenDanceCode as:

  • a hosted service;
  • a team collaboration product;
  • an AgentHub replacement;
  • an IDE plugin;
  • a marketplace or plugin platform;
  • a production SaaS product with billing, accounts, dashboard, or cloud sync.

Documentation Rules

  • README.md is the public entry point: positioning, install, model configuration, commands, project structure, current maturity, and docs map.
  • docs/产品功能需求文档.md owns product requirements and non-goals.
  • docs/架构设计文档.md owns runtime boundaries and data flow.
  • docs/开发流程文档.md owns the current TypeScript development loop.
  • docs/端到端验收清单.md owns manual acceptance checks.
  • docs/并行推进计划.md owns maintainer workstream planning and the next candidate queue.
  • docs/并行执行状态.md is a public progress log with user-visible changes, merge commits, and verification summaries. Do not add agent IDs, private paths, token-bearing commands, or local operator runbooks.
  • If behavior changes, update the smallest complete set of README plus the owning docs in the same pass.

Current Development Baseline

  • Active branch: codex/rust-rewrite.
  • Release candidate branch: release/npm-first.
  • Current public status: Rust rewrite scaffold is not release-ready. Do not publish npm or GitHub releases until Rust release gates are implemented and verified.
  • Current AgentHub contract target: SDK manifest agenthub-sdk.v1, agent.stream schema version 2, and terminal failure frames via run.agent.result with success=false.
  • Current privacy boundary: project root .env is ignored and not loaded by default; examples must point users to controlled shell env, SDK env, or user-global ~/.tokendance/.env.

Next Work Queue

Use docs/rust-rewrite-architecture.md before launching broad workers. Current highest-value slices are:

  • core runtime parity: session, transcript, context builder, compact, hooks;
  • provider parity: OpenAI Responses, OpenAI-compatible Gateway, Anthropic-compatible Messages;
  • CLI parity: command registry, run --json, --stream-json, doctor/config/gateway/auth/session/transcript/quality;
  • SDK parity: AgentHub event mapping, approval bridge, OIDC helper, same-session guard;
  • npm release wrapper and privacy scan.

Verification

Use these from the repository root after code or docs changes:

cargo fmt --all -- --check
cargo test --workspace
cargo run -p tokendance-cli -- --version
cargo run -p tokendance-cli -- doctor --json
pnpm verify

npm publish --tag next is a separate manual release-owner action after version, package contents, dist-tag, npm login, and license intent are reviewed. Do not put publish into verification scripts.