Guidance for coding agents (Claude Code, Codex, OpenCode, etc.) working in this repository.
- Public repository: assume all tracked content and diffs are public. Never commit secrets,
.envfiles, stored credentials, private URLs, or real production data. Reviewgit statusand the staged diff before committing. If private data appears, stop and alert a maintainer. - Dependency-light by design: the runtime has almost no dependencies. Do not add a dependency for something we already handle, and keep new dependencies justified. Prefer the standard library.
- Keep code simple: reuse existing primitives, keep a single source of truth, and avoid speculative abstractions. Add an interface only when it protects a real external or platform boundary (for example an agent adapter).
- TypeScript, Node 18+, ESM. Source in
src/, tests intests/(vitest). - The single source of truth for the version is
package.json(npm 3-part semver, tagsvX.Y.Z). There is deliberately no VERSION file; tooling that expects one (e.g. gstack's 4-digit scheme) reports false drift here — ignore it. - Use the
RunIoabstraction for testable I/O; fetch, spawn, and streams flow through it so unit tests can inject fakes (seetests/run.test.ts). - Do not add code comments unless they explain non-obvious decisions.
- Run
pnpm run typecheckandpnpm testbefore considering work done. - New commands: wire them through
src/args.ts→ theCliRequestunion insrc/types.ts→ dispatch insrc/run.ts→ui.tshelp text. Addtests/args.test.tsandtests/run.test.tscoverage.
Treat credential handling, key storage, --dry-run previews, and agent-profile isolation as
security-sensitive. API keys must be masked in all human and JSON output. Never write a plaintext
credential into a generated agent config.
Stay with the PR until CI and any automated review have finished. Poll checks, reviews, and review threads; address every actionable issue, push fixes, and repeat until no actionable feedback remains. Do not merge while checks are pending or review issues are unresolved.