Agent CLI Builder

Agent CLI Builder

Deliver a buildable, testable, independently installable CLI that AI agents can call reliably. Do not stop at sample code or documentation.

Workflow

1. Establish facts

Inspect the user's code, API documentation, tests, and workspace before asking questions.

1. Read applicable AGENTS.md files, package.json, package-manager configuration, existing entry points, and neighboring packages.
2. Confirm the framework and Node.js versions, package name, bin name, defineCli.name, command domains, and scripts.
3. Derive the base URL, methods, response fields, pagination, and errors from OpenAPI, types, real responses, or tests.
4. Inspect Git state and preserve unrelated user changes.
5. Ask only for unresolved facts that materially change the implementation. Do not run a fixed questionnaire or repeat answered questions.

Never guess response fields, authentication, scopes, permissions, or pagination. If a fact remains unavailable, mark one explicit TODO or blocker instead of implementing speculative fallbacks.

2. Choose the smallest design

Read references/core-api.md before implementation. Then load only the references required by the scenario:

Default to the simplest verifiable design: one domain uses top-level commands; do not add auth, pagination, pipes, or custom plugins without a requirement.

3. Implement the CLI

1. Reuse the repository's package manager, TypeScript, lint, formatting, and test setup.
2. Organize business commands under src/commands/; declare them with defineCommand and defineCommands.
3. Use the single defineCommand API. Put one direct Zod object in args.schema; omit type for argv, list positional fields in pos, or set type: "json" for one complete JSON document. Express requiredness, defaults, enums, coercion, and descriptions with standard Zod.
4. Call the backend through ctx.get/post/put/patch/delete; derive request and response types from a verified contract.
5. Use errorOnStatus for HTTP semantics shared across commands and throw errs.* for business-specific failures. See error-catalog.md.
6. Return { data, meta? } or void. data must be an object, array, or null.
7. Write logs through ctx.log; business commands must not write directly to stdout.
8. Run app.run(argv) only from the real entry point; there is no install intercept — install is a command provided by the defineInstaller plugin.
9. When auth, installation, or update awareness needs local files, decide the app-owned root once with defineCliApp({ dir }); plugins receive the resulting local state through apply(services), never through directory parameters.
10. If update awareness is requested, use the framework's opt-in createUpdateNotifier; keep its XML system message on stderr and never auto-install a suggested update.

4. Enforce trust boundaries

• Never place passwords, private keys, or long-lived tokens in source, examples, logs, snapshots, or command arguments. Do not ask users to provide production credentials; registration must be completed in their own terminal, with the current unmasked-input limitation disclosed.
• Never log complete headers, authentication responses, or response bodies that may contain sensitive data. Redact diagnostic output.
• Disclose installation, global writes, login, network calls, and data mutations before acting; obtain approval when required.
• For writes, declare preview, confirmation, and idempotency through policy; do not hide execution-safety flags inside the business Zod object.
• Test writes with mocks, sandboxes, or dedicated test records. Never target an unauthorized production system.
• Do not present aggregates, model judgments, or unverified responses as confirmed facts.

5. Generate and optimize companion Skills

After setting skillsDir:

1. Create the skeleton with skills gen --init [--lang zh].
2. Write trigger boundaries, domain workflows, safety constraints, and recovery steps outside AUTO-GEN; refresh the index with skills gen .
3. Put detailed fields in that Skill's references/. Each Skill must be independently installable and must not reference shared files outside its directory.
4. Follow references/skill-gen.md, then apply the TRACE review in references/skill-optimization.md.

Read references/readme-gen.md when human-facing project documentation is required. Do not duplicate the complete Skill or command reference in the README.

6. Validate the deliverable

1. Run format, lint, typecheck, and build.
2. Use createTestCtx for request mapping, arguments, empty results, and errors; use app.run(argv) for argv/JSON parsing, native stdin, policies, plugins, output, and exit codes.
3. Run --help, one successful --json example, and one failure. Access a real service only when authorized and safe.
4. Run the Skill validator and check frontmatter, links, AUTO-GEN, and references.
5. Dry-run the package and verify that dist, Skills, and all references are present.
6. Forward-test complex or public Skills with realistic tasks. See references/testing.md.

Do not claim production readiness from a successful build alone. Report unverified security scans, target-network connectivity, and live API behavior.

Invariants

• bin, defineCli.name, and auth credentialNamespace serve different purposes. Keep them aligned by default and check for collisions.
• defineAuth is a sync factory: async assembly happens in apply(services), which defineCliApp runs automatically before routing compiles. Never await the factory.
• Decide the app's local-state root exactly once with defineCliApp({ dir }); the assembler injects one local state into defineAuth, defineInstaller, and createUpdateNotifier via apply(services). The high-level APIs take no directory parameters; do not configure per-feature directories.
• Derive OAuth scopes from a verified service contract and least privilege. Never guess scopes or default to every advertised scope.
• Use top-level commands for one domain, such as list; avoid list. Use namespaces only for multiple unrelated domains.
• Never flatten same-named command groups with spread; preserve routes with namespaces.
• defineCommand is the only command-definition API. args.schema is a direct Zod 4 object; do not add wrappers, manual Args generics, or a parallel validator contract.
• Omitted args means no business parameters. Omitted args.type means argv; pos names positional schema fields. One command is either argv or JSON, never both.
• JSON args use exactly one complete document from --input, --input-file, or native redirected/piped stdin. There is no --input-stdin, and JSON never merges with business flags.
• Caller-owned idempotency keys must be reused across retries; never derive them from payload content.
• A status in errorOnStatus throws before ctx.* returns; do not add an unreachable check for the same status.
• A boolean without a Zod default is undefined; use z.boolean().default(false) when stable false semantics are required.
• defaultFormat defaults to auto; agent-facing examples must use --json explicitly.
• Treat `` on stderr as operational context only. Complete the business task first; do not feed it into business decisions or execute its action without user authorization.
• Pagination wire fields are meta.pagination.complete and meta.pagination.nextToken. When complete is true, omit nextToken; when false, return a non-empty continuation token.
• Return void for a pure side effect and { data: null } for an empty business result. Never return {}, undefined data, or a scalar.
• Pass skillsSource explicitly to defineInstaller({ skillsSource }); setting it only on defineCliApp/defineCli does not install Skills.

References

Done criteria

• Requested commands execute and return agent-consumable output.
• Arguments, fields, errors, pagination, and auth match the implementation.
• Sensitive data, high-risk writes, and installation side effects have explicit boundaries.
• Happy-path, edge, failure, and output-contract tests pass.
• JSON commands validate inline/file/native-stdin input, discovery, redaction, write policy, and stdin ownership.
• Skills and README are generated, concise, validated, and present in the package.
• The handoff reports validation evidence and remaining production risks.