Imported from KamranUllahAfaq/Orqivium (cli/src/commands/AGENTS.md). Install upstream with npx skills add KamranUllahAfaq/Orqivium --skill commands. Copyright stays with the author.

AGENTS.md — src/commands/

Per-command agent-optimized usage and structure guide.

Command folder convention

Every command is a folder. index.ts is the command class file. All related code — business logic, helpers, tests, and optional agent guide — colocates inside the folder. Subcommands are subfolders.

src/commands/
  <topic>/
    <verb>/
      index.ts        ← command class (extends OrqiviumCommand; the ONLY file the registry discovers)
      run.ts          ← optional behavior owner (not a command, invisible to the registry)
      handlers.ts     ← helpers
      guide.ts        ← agent guide string (optional)
      *.test.ts       ← tests
    <nested-verb>/    ← subcommand (e.g. auth/devices/list/)
      index.ts
    _shared/          ← intra-topic shared code (only when needed by 2+ siblings)
      <shared>.ts

The registry generator (pnpm tree:gen → src/commands/tree.generated.ts) discovers commands only via **/index.+(js|cjs|mjs|ts). All other files in command folders are invisible to the registry — add freely without glob exclusions. Folders prefixed with _ (e.g. _shared/, _strategies/) are excluded from registry discovery and from coverage checks.

Adding a new command

1. Create src/commands/<topic>/<verb>/index.ts extending OrqiviumCommand.
2. Keep small owner-local behavior in index.ts; extract sibling modules such as run.ts or handlers.ts when logic needs independent tests, reuse, or a clearer owner.
3. Run pnpm tree:gen to regenerate the command tree (also runs implicitly via prebuild/predev/pretest).
4. Run pnpm test to verify coverage.

Adding an agent guide

1. Create src/commands/<topic>/<verb>/guide.ts exporting a plain string:

   export const agentGuide = `
   WORKFLOW
     1. ...
   
   ERROR RECOVERY
     ...
   `

2. Import and assign in index.ts:

   import { agentGuide } from './guide.js'
   
   export default class MyCmd extends OrqiviumCommand {
     override agentGuide(): string {
       return agentGuide
     }
   }

3. The guide appears at the bottom of orqctl <cmd> --help automatically.
4. Agents call orqctl <cmd> --help to read both structural help and workflow guidance.

Shared utilities

Code used by two or more commands lives in src/<domain>/ (e.g. src/auth/, src/api/, src/errors/). Do not put broadly shared code inside a command folder. Intra-topic shared code (used only within one topic's commands) uses _shared/ within that topic folder.