Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (48 loc) · 2.89 KB

AGENTS.md

File metadata and controls

67 lines (48 loc) · 2.89 KB
Raw

Agent Guidelines

Repo

  • Standalone TypeScript package for the put.io CLI
  • Main code lives in src/*; layer rules in Architecture
  • Durable docs live in docs/*; release wiring in Distribution
  • Consumer-facing skills live in skills/*
  • Contributor setup and validation in Contributing

Commands

Primary:

  • pnpm exec vp run verify

Focused:

  • pnpm exec vp run check
  • pnpm exec vp run build
  • pnpm exec vp run test
  • pnpm exec vp run coverage
  • pnpm exec vp run check:dead-code
  • pnpm exec vp run skills:lint
  • pnpm exec vp run smoke:pack: writes the report to .artifacts/smoke-packed-install.json
  • pnpm exec vp run build:sea then pnpm exec vp run verify:sea

Runtime proofs:

  • ./dist/bin.mjs describe
  • ./dist/bin.mjs whoami --fields auth --output json

Worktrees

Run pnpm exec vp install, pnpm exec vp config, then pnpm exec vp run verify.

Development Guidance

  • Keep README.md user-facing. Put contributor workflow in CONTRIBUTING.md, architecture in docs/*, and consumer usage patterns in skills/*.
  • Keep command modules thin and move shared behavior into internal Effect-native helpers and services.
  • Prefer Effect, services, layers, Schema, and tagged errors over ad hoc control flow.
  • Treat JSON output as the machine contract and terminal output as a separate adapter layer.
  • Update docs when flags, command behavior, or architecture boundaries change.
  • When the public CLI surface or agent-facing setup flow changes, update README.md and skills/putio-cli/SKILL.md together so the copy-paste prompt and consumer guidance stay aligned.
  • Keep docs free of volatile metrics.

Effect

This repository uses the Effect TypeScript library. The installed version's own guide is node_modules/effect/AGENTS.md; consult it for the APIs the change touches, and search node_modules/effect/src for anything it does not cover.

Testing

  • Prefer in-process tests unless the process boundary is the behavior under test.
  • Add command-path coverage when the @effect/cli boundary changes.
  • Prove command-surface changes with the built binary.
  • Finish in-scope edits, guardrails, and fixes without pausing; ask before publishing, credential-bearing release or SEA builds, and live writes against shared accounts.

Skills

  • skills/* is for reusable consumer-facing skills, not repo onboarding.
  • skills/putio-cli/SKILL.md is the router; surface-specific detail lives in the matching reference file.
  • skills/putio-cli/agents/openai.yaml is the Codex picker display and default-prompt metadata; keep it aligned with the skill frontmatter.
  • Refresh the skill and its references in the same change whenever describe.version, commands, output, auth, or automation change in a way consumers need to know.
  • CLAUDE.md should remain a symlink to this file.