Skip to content

AGENTS.md

Latest commit

 

History

History
78 lines (53 loc) · 2.72 KB

AGENTS.md

File metadata and controls

78 lines (53 loc) · 2.72 KB
Raw

Agent Guidelines

Development instructions for agents working on this repository.

Repo

  • Standalone TypeScript package for the put.io CLI
  • Main code lives in src/*
  • Durable docs live in docs/*
  • Consumer-facing skills live in skills/*

Start Here

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

Contributing explains when each focused check applies.

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. Effect guidance and inspectable source come from the installed package under node_modules/effect.

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.

Learning more about Effect

This repository uses the Effect TypeScript library.

Before writing any Effect code, first read node_modules/effect/AGENTS.md completely, and follow the links in the file when required.

If you need to learn more about particular Effect APIs and concepts that the guide doesn't cover, search through the source code in node_modules/effect/src.

Testing

  • Prefer in-process tests unless the process boundary is the behavior under test.
  • Add command-path coverage when the @effect/cli boundary changes.
  • Run repo guardrails before closing work, then prove important command-surface changes with the built binary.

Skills

  • skills/* is for reusable consumer-facing skills, not repo onboarding.
  • CLAUDE.md should remain a symlink to this file.