feat(cli): default to JSON output under AI coding agents

[dqn]

Summary

When an AI coding agent such as Claude Code, Codex, Cursor, or Gemini CLI runs tailor, commands default to JSON output and --help starts with guidance for the agent, even without the agent skill installed.

Output under an agent

Invocation	Output
tailor workspace list	JSON
tailor workspace list --json=false	table
TAILOR_JSON_OUTPUT=false tailor workspace list	table
POLITTY_NO_AGENT=1 tailor workspace list	table (detection off)
tailor tailordb erd export (CLI plugin)	unchanged: table unless --json or TAILOR_JSON_OUTPUT=true

Argument errors become JSON error envelopes, and a refused prompt names the detected agent and how to opt out. Without a detected agent, nothing changes.

Help preamble

$ CLAUDECODE=1 tailor workspace --help
AI coding agent detected:

• Unless --json=false or TAILOR_JSON_OUTPUT=false is set, commands that return structured results print JSON to stdout. Parse it instead of the table output, which is formatted for humans and may change.
• CLI plugin commands keep the table unless you pass --json or set TAILOR_JSON_OUTPUT=true.
• Pass --help-json to a command for machine-readable help.
• Full command reference: <install dir>/docs/cli-reference.md

Notes

• Scripts that an agent runs and that parse table output (for example tailor workspace list | grep) now get JSON; set TAILOR_JSON_OUTPUT=false for them.
• Detection follows politty's detectAgent() (the vercel/detect-agent spec). Some of its markers can be present outside an agent, such as COPILOT_GITHUB_TOKEN exported for a whole CI job, REPL_ID in Replit, or GOOSE_PROVIDER in a shell profile; those sessions also get JSON and lose prompts until they opt out.
• Under an agent, --help and --help-json still show --json with default false, because politty reads defaults before it detects the agent; the preamble states the actual default.
• The CLI records the agent in runMain's setup hook instead of adding a jsonByAgent option to createCommonArgs; plugins never record one, so they keep their output without a new public option.
• Stacked on fix(deps): update @politty/zod to 0.4.3 #2588.

[changeset-bot]

🦋 Changeset detected

Latest commit: f81dc08

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@tailor-platform/sdk	Minor
@tailor-platform/create-sdk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@tailor-platform/create-sdk

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/create-sdk@f81dc08

@tailor-platform/eslint-plugin-sdk

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/eslint-plugin-sdk@f81dc08

@tailor-platform/sdk

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk@f81dc08

@tailor-platform/sdk-plugin-frontend

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk-plugin-frontend@f81dc08

@tailor-platform/sdk-plugin-seed

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk-plugin-seed@f81dc08

@tailor-platform/sdk-plugin-setup

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk-plugin-setup@f81dc08

@tailor-platform/sdk-plugin-tailordb-erd

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk-plugin-tailordb-erd@f81dc08

commit: f81dc08

[github-actions]

📖 Docs Quality & Consistency Check

✅ Recommended Actions

None — docs are consistent with the implementation and contain no user-facing internal-detail leaks.

⚠️ Consistency Issues

No consistency issues found.

📝 Reader-Perspective Issues

No reader-perspective issues found.

🔍 Details

This PR adds AI coding agent detection to the CLI, defaulting to JSON output when an agent is detected. The following areas were checked for consistency and reader-perspective issues:

Areas Checked:

1. CLI Reference Documentation (packages/sdk/docs/cli-reference.md and cli-reference.template.md)

   • Lines 53-61: Documents agent detection behavior, JSON output defaults, opt-out mechanisms (--json=false, TAILOR_JSON_OUTPUT=false, POLITTY_NO_AGENT=1), and CLI plugin behavior
   • Lines 120-122: Documents that GitHub Actions annotations are suppressed under JSON mode, including when triggered by agent detection
   • Verified against implementation in packages/sdk/src/cli/main.ts (setup hook calling setJsonDefaultAgent(agent?.id)) and packages/sdk/src/cli/shared/args.ts (JSON default logic)
   • Result: Consistent ✓

2. Agent Help Message (packages/sdk/src/cli/main.ts lines 62-67)

   • agentHelp constant matches the PR description and is correctly passed to politty's runMain via the agentHelp option
   • Message correctly explains JSON output default, opt-out options, CLI plugin behavior, and references the CLI reference doc
   • Result: Consistent ✓

3. Agent Skill Documentation (packages/sdk/agent-skills/tailor/SKILL.md and skills/tailor/SKILL.md)

   • Lines 29-32: Updated to reflect that the CLI defaults to JSON when it detects an AI coding agent
   • Provides fallback guidance for undetected agents or CLI plugin commands
   • Result: Consistent ✓

4. Implementation Behavior

   • packages/sdk/src/cli/shared/args.ts:
     • requestedJsonModeSource() returns "agent" when agent is detected (line 268)
     • createCommonArgs() defaults --json to true when jsonDefaultAgent() !== undefined (line 450)
     • JSDoc at line 317 correctly notes that only the host CLI records an agent, not plugins
   • packages/sdk/src/cli/shared/logger.ts:
     • New JsonModeSource type includes "agent" (line 23)
     • jsonModeRemedy() provides appropriate opt-out guidance based on source (lines 32-50)
     • setJsonDefaultAgent() and jsonDefaultAgent() functions manage agent state (lines 551-562)
   • Tests in packages/sdk/src/cli/main.test.ts (lines 154-185) verify:
     • JSON output by default with detected agent
     • --json=false and TAILOR_JSON_OUTPUT=false override the default
     • POLITTY_NO_AGENT=1 turns detection off
     • Agent help appears in --help output only when agent is detected
   • Result: Consistent ✓

5. Reader-Perspective Review

   • All user-facing documentation (packages/sdk/docs/cli-reference.md and agent skills) describes the feature from the user's perspective
   • No SDK/Platform internal implementation details leaked (e.g., no mention of internal classes, parsers, or transport mechanisms)
   • POLITTY_NO_AGENT is appropriately documented as a user-facing control variable
   • The documentation focuses on user-observable behavior (what happens, how to control it) rather than implementation mechanics
   • Result: No issues ✓

Verification Summary:

• ✅ Documentation accurately describes agent detection behavior
• ✅ JSON output default is correctly documented for both host CLI and plugins
• ✅ Opt-out mechanisms (--json=false, TAILOR_JSON_OUTPUT=false, POLITTY_NO_AGENT=1) are clearly documented
• ✅ --env-file limitation is documented (values loaded via --env-file don't affect agent detection)
• ✅ Agent help message implementation matches documentation
• ✅ All changes maintain appropriate user-facing perspective without exposing internals

Re-run this check by adding the docs-check label to the PR.

---

[toiroakr]

LGTM