docs: Plan spec for agent CLI ergonomics (bulk ops, output, sync)

[jlevy]

Summary

Adds a Draft planning spec, docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md, for improving tbd's CLI ergonomics for agents.

It grew out of observing agents drive tbd through brittle bash: for loops over issue IDs, 2>&1 | tail -1 on every command, hand-rolled echo "=== ... ===" progress headers, and a --no-sync ... ; tbd sync ritual. Each contortion maps to a missing tbd primitive.

What's in the spec

• Problem Catalog (P1–P9): the full set of common problems, each tied to the bash symptom it causes (single-target verbs, no select-and-act, untrusted output, no visible record, murky sync model, inline-quoting hazards, inconsistent arg conventions, no preview discipline, no "delivered-by-PR" provenance).
• Phase 1 — quick wins for the current release (additive, backward-compatible): variadic <ids...> on close/reopen/update/show; a bulk summary line + --json results array + accurate "unsynced changes" hint; --reason-file/stdin bodies; and an honest opt-in --sync.
• Phase 2 — broader follow-on: query-driven --where mutation (reusing the list filter grammar, with mandatory preview) and a tbd apply transaction file generalizing import.

Grounded throughout with file:line cites from the current command sources. One design decision is already resolved in the spec: keep stage-then-publish syncing, make it self-revealing via an unsynced-changes hint, and add opt-in --sync (no per-command auto-sync).

Notes

• Docs-only; no code changes. Status: Draft for review.
• Distinct from the existing plan-2026-06-03-tbd-agent-cli-guideline-improvements.md (that one improves the guideline about writing agent skills; this one changes tbd's runtime CLI behavior).
• Implementation will be tracked as tbd beads (epic + children) linked to this spec via --spec.

https://claude.ai/code/session_01P9jYZ7T6MCMCzLL2iJjn9b

---

Generated by Claude Code

[deepsource-io]

DeepSource Code Review

We reviewed changes in b156bfa...05573d7 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
Secrets		Jun 14, 2026 11:21p.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

[github-actions]

Coverage Report for packages/tbd

Status	Category	Percentage	Covered / Total
🔵	Lines	34.14%	2947 / 8630
🔵	Statements	34.03%	3056 / 8978
🔵	Functions	39.44%	465 / 1179
🔵	Branches	30.18%	1411 / 4675

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/tbd/src/cli/cli.ts	73.87%	34.09%	88.88%	73.87%	186-201, 205-216, 240-241, 246-250, 278, 297-298
packages/tbd/src/cli/commands/close.ts	2.17%	0%	0%	2.32%	31-117, 128-129
packages/tbd/src/cli/commands/create.ts	1.72%	0%	0%	1.72%	44-197, 214-220
packages/tbd/src/cli/commands/reopen.ts	1.96%	0%	0%	2.08%	33-131, 142-143
packages/tbd/src/cli/commands/update.ts	0.36%	0%	0%	0.41%	48-569, 587-595
packages/tbd/src/cli/lib/body-input.ts	68.42%	80.95%	50%	68.42%	32-36, 66-67
packages/tbd/src/cli/lib/bulk.ts	100%	92.85%	100%	100%
packages/tbd/src/cli/lib/context.ts	86.66%	73.07%	80%	86.66%	79, 99
packages/tbd/src/cli/lib/data-context.ts	25.42%	20.45%	35.71%	24.07%	97-102, 106-109, 123-171, 198-222, 238, 241-249, 265-266, 300-312
packages/tbd/src/utils/lockfile.ts	83.87%	74.07%	85.71%	84.48%	134-142, 162, 247

Generated in workflow #1032 for commit 05573d7 by the Vitest Coverage Report Action

[jlevy]

Senior Engineering Review

I reviewed PR #176 (f7f18b6) from the checked-out branch, including the new design spec and the surrounding CLI implementation paths it cites: close, reopen, update, show, import, output handling, command context, sync, locking, and the existing tryscript coverage. CI is green and the PR is docs-only, but I would revise the spec before using it as an implementation guide. The high-level direction is right: the current agent ergonomics pain is real, and a small additive Phase 1 is the right shape. The main issues are places where Phase 1 is less quick/safe than the spec currently implies.

Findings

1. [P1] --sync needs a tri-state CLI/context design before implementation.

   The spec makes Phase 1 --sync opt-in while keeping no per-command auto-sync. But the current global option surface only has --no-sync, and getCommandContext() stores sync: opts.sync !== false, which means the absence of --no-sync becomes true. If implementation simply adds sync behavior based on ctx.sync, every mutator will auto-sync by default, contradicting the resolved design.

   Relevant code/spec:

   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:204-211
   • packages/tbd/src/cli/cli.ts:66-73
   • packages/tbd/src/cli/lib/context.ts:37-48

   Suggested fix: explicitly specify a tri-state, for example syncMode: 'unspecified' | 'sync' | 'no-sync', or separate syncRequested from legacy noSyncRequested. Also decide whether --sync is global or per-mutator. Given the sync command performs network operations and uses the data-sync lock, I would also specify the lock boundary: apply all issue writes under one lock, release it, then run the existing sync path or call a shared internal helper without re-entering the same non-reentrant lock.

2. [P1] The unsynced-changes hint is not visible if Phase 1 literally reuses import's nudge.

   The spec repeatedly says to reuse the import nudge (Run tbd sync...). In code, that nudge is emitted through this.output.info(), which is only visible with --verbose or --debug; it is hidden in default text mode. That does not satisfy the goal of making the stage-then-publish model self-revealing.

   Relevant code/spec:

   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:197-200
   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:204-211
   • packages/tbd/src/cli/commands/import.ts:282-294
   • packages/tbd/src/cli/lib/output.ts:398-406

   Suggested fix: define a new visible-but-suppressible notice contract for unsynced changes. For example: default text mode prints one additional notice line unless --quiet or --json; JSON includes sync: { pending: true, hint: ... }; quiet remains silent. The current info() channel is not enough.

3. [P1] already-X skip semantics conflict with backward compatibility for reopen.

   The spec says single-ID behavior remains exactly as today, but also says already-X is a reported skip, not a failure. For close, this aligns with current idempotent behavior. For reopen, it does not: reopening an open issue currently throws and is covered by CLI golden tests as exit code 1.

   Relevant code/spec/tests:

   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:186-196
   • packages/tbd/src/cli/commands/close.ts:54-58
   • packages/tbd/src/cli/commands/reopen.ts:49-52
   • packages/tbd/tests/cli-crud.tryscript.md:579-588

   Suggested fix: resolve this in the spec. Options: keep single-target reopen failure unchanged and make "already-open" a bulk-only skip, or intentionally change reopen to idempotent and call out the backward-compatibility break. For a quick safe Phase 1, I would preserve single-target behavior and only summarize skips for bulk paths where the intent is batch completion.

4. [P2] show does not fit the Phase 1 mutator/output/sync contract.

   The spec includes show alongside close/reopen/update, but show is read-only, uses loadFullContext() without the write lock in steady state, and intentionally emits multi-line YAML/Markdown plus optional parent context. It does not share the bulk summary, unsynced hint, or --sync surface.

   Relevant code/spec:

   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:186-188
   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:242-257
   • packages/tbd/src/cli/commands/show.ts:107-188

   Suggested fix: split bulk show out of Phase 1 or give it a separate read-only design. A safe version might be tbd show A B C --json returns an array and text mode renders each issue with a delimiter. That is useful, but it is not part of the same "one-line success and one sync" implementation slice.

5. [P2] The update --status closed example bypasses close semantics.

   The spec's bulk update example uses tbd update A B C --status closed --add-label delivered. Current update simply assigns issue.status; it does not set closed_at or close_reason. close does. If agents learn to use update --status closed as a bulk close, issue data will be semantically incomplete.

   Relevant code/spec:

   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:189-192
   • packages/tbd/src/cli/commands/update.ts:82-90
   • packages/tbd/src/cli/commands/close.ts:65-70

   Suggested fix: remove that example or specify transition semantics for status changes. For Phase 1, I would keep bulk closure on close only and limit bulk update to field updates that do not have lifecycle side effects, unless status transition handling is deliberately added and tested.

6. [P2] The --quiet contract is internally inconsistent and conflicts with existing behavior.

   Current --quiet suppresses success output, and there is a golden test for a successful quiet create producing no output. The spec says quiet should "collapse multi-target output to a single line," while the testing section says "exactly one line (or nothing)." Those are materially different contracts.

   Relevant code/spec/tests:

   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:248-249
   • docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:276-277
   • packages/tbd/src/cli/lib/output.ts:378-386
   • packages/tbd/tests/cli-advanced.tryscript.md:443-448

   Suggested fix: keep --quiet as silent-on-success. Make default text mode the one-line human summary and --json the machine contract. This preserves existing behavior and still removes the need for 2>&1 | tail -1.

Phase 1 Scope Notes

I would tighten Phase 1 to the smallest ergonomic slice that is both safe and immediately useful:

• Variadic IDs for close and reopen, plus a carefully constrained bulk update
• Validate-all-then-apply for unknown IDs by default
• --ignore-missing as an explicit best-effort escape hatch
• Bulk JSON result shape with per-ID status and a summary
• Default text-mode one-line summary for multi-target writes
• Shared file/stdin body reader for --reason-file, --reason -, --description -, and --notes -
• Visible unsynced-change hint with explicit stream/suppression rules
• --sync only after the context tri-state and lock/network boundary are specified

I would defer bulk show unless it gets its own read-only behavior definition.

Phase 2 Notes

The Phase 2 ideas are directionally sound, especially tbd apply for mixed create/update/close batches. That said, --where currently depends on "the existing list filter grammar," but in code that grammar is an implementation-local ListOptions shape inside list.ts, not a reusable selector abstraction. Before building --where, the design should call out a selector module shared by list and mutators, with tests proving read and write selection match.

Relevant code/spec:

• docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md:215-223
• packages/tbd/src/cli/commands/list.ts:32-49
• packages/tbd/src/cli/commands/list.ts:191-259

For tbd apply, the instinct to generalize import is good, but it will need a real transaction/rollback story if it promises atomicity across create, update, close, ID mapping updates, parent child_order_hints, and sync. A failed write after mapping changes or parent hint updates could otherwise leave partial state.

Documentation Notes

The spec correctly identifies stale/incorrect sync docs, and implementation should update them in the same PR as Phase 1. There are multiple existing user-facing references that still describe --no-sync and auto_sync as real issue-write behavior:

• packages/tbd/docs/tbd-docs.md:805-827
• packages/tbd/docs/tbd-docs.md:1094-1098
• packages/tbd/docs/tbd-docs.md:1263-1267
• packages/tbd/docs/tbd-design.md:1608-1646
• packages/tbd/docs/tbd-design.md:2936-2961

The Phase 1 implementation plan mentions the manual and tbd prime, but the architecture/design doc should be included too, otherwise the repo will continue to carry contradictory sync semantics.

Testing Notes

The testing strategy is mostly right. I would add explicit tests for:

• --sync absent does not sync, --sync does sync, legacy --no-sync does not sync and is documented/no-op for issue writes
• lock boundary around bulk write plus sync, especially avoiding nested lock acquisition
• reopen already-open behavior for single-ID and bulk paths, once the spec resolves it
• update --status closed either being rejected in bulk or setting lifecycle metadata correctly
• default text vs --quiet vs --json output contracts
• stdin bodies for --reason -, --description -, and --notes -, including shell-sensitive text ($, backticks, quotes)

CI Status

Current PR checks are green: Ubuntu, macOS, Windows, Coverage & Lint, Benchmark, and DeepSource Secrets. I did not run local tests; this worktree has no installed node_modules, and the PR is docs-only.

Bottom Line

The design is worth pursuing, but Phase 1 needs a few decisions made explicit before implementation. The highest-risk pieces are sync flag semantics, visible unsynced hints, reopen compatibility, and excluding or separately designing bulk show. Tightening those would make the quick-win phase genuinely quick and reduce the chance of accidentally changing core CLI contracts while improving agent ergonomics.

[jlevy]

Thanks — this is a genuinely useful review. I verified each finding against the code and adopted all of them in 136d178 (spec revised; implementation next).

1. --sync tri-state + lock boundary — spec now mandates modeling intent as unspecified | sync | no-sync (so absence of --no-sync ≠ sync), plus a lock boundary: write all issues under one lock, release it, then run sync (no nested non-reentrant lock).
2. Visible unsynced hint — confirmed import's nudge is output.info() (verbose-only). Spec routes the hint through output.notice() (visible by default, suppressed by --quiet/--json); --json carries sync: { pending, hint }.
3. reopen compatibility — confirmed the cli-crud.tryscript.md exit-1 golden. Single-ID behavior is preserved exactly (close idempotent, reopen errors); already-X skips are bulk-only (2+ IDs).
4. Bulk show — pulled out of the mutator slice into a separate, optional read-only design (delimited text / --json array; no lock/summary/sync contract). Tracked separately.
5. update --status closed — removed from the bulk example; bulk closure goes through close only (since update doesn't set closed_at/close_reason); bulk update limited to side-effect-free fields.
6. --quiet — kept silent-on-success (preserves the quiet-create golden); default text = one-line summary, --json = machine contract.

Also folded in: Phase 2 --where now requires extracting a shared selector module from list.ts's impl-local ListOptions; tbd apply flags the transaction/rollback boundary; doc fixes extended to tbd-design.md (with the specific stale --no-sync/auto_sync locations); testing strategy expanded with your cases; default atomicity resolved to fail-closed + --ignore-missing.

Implementing the tightened slice next: variadic close/reopen + constrained bulk update, validate-all-then-apply, --ignore-missing, shared file/stdin reader, bulk JSON + one-line summary, visible hint — deferring --sync execution and bulk show per your scoping.

---

Generated by Claude Code