feat: add machine-readable worktree creation for agents

[helizaga]

Summary

• add git gtr new --porcelain with stable path, branch, and hook_status records
• keep progress, warnings, and arbitrary hook output on stderr, and suppress success records on hook failure
• document a shell-native agent workflow and safety boundaries instead of adding a first-party MCP server
• update help, changelog, testing guidance, and generated Bash/Zsh/Fish completions

Why

This addresses the integration need raised in #67 without adding a long-running protocol server to the Bash CLI. Shell-capable agents can call git gtr directly and reliably parse the created worktree path.

Validation

• shellcheck bin/gtr bin/git-gtr lib/*.sh lib/commands/*.sh adapters/editor/*.sh adapters/ai/*.sh
• ./scripts/generate-completions.sh --check
• bats tests/hooks.bats — 36/36 passed
• bats tests/cmd_create_integration.bats — 18/18 passed
• bats tests/ — 552/553 passed; the remaining cmd_clean --merged uses nested registered worktree path failure reproduces unchanged on exact origin/main
• real git gtr disposable-repository smoke test verified strict stdout records, noisy-hook stderr isolation, returned path, and cleanup

Summary by CodeRabbit

• New Features

  • Added --porcelain output for git gtr new, providing stable machine-readable worktree, branch, and hook-status records.
  • Progress, hook messages, and incidental output are separated from structured results.
  • Interactive options are rejected in porcelain mode, and failed hooks prevent success records.

• Documentation

  • Documented porcelain usage, output behavior, hook statuses, safety guidance, and automation workflows.

• Chores

  • Updated Bash, Zsh, and Fish completions.

• Tests

  • Added coverage for output stability, escaping, hook handling, failures, and interactive-option validation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e738e59b-373e-4a7e-959d-bb3f051e317e

📥 Commits

Reviewing files that changed from the base of the PR and between 1a88124 and 91533fc.

📒 Files selected for processing (1)

• README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• README.md

---

Walkthrough

The PR adds --porcelain support to git gtr new. It emits escaped path, branch, and hook-status records, separates incidental output, reports hook outcomes, rejects interactive options, and documents and tests the interface.

Changes

Porcelain worktree creation

Layer / File(s)	Summary
Porcelain command contract lib/commands/create.sh, lib/commands/help.sh	git gtr new accepts --porcelain, emits escaped records through a dedicated descriptor, implies noninteractive confirmation, and rejects --editor and --ai.
Hook status and execution lib/hooks.sh, lib/commands/create.sh, tests/hooks.bats	Hook phases report none, ran, skipped-untrusted, or partial. Post-create hook output goes to stderr, and failures stop creation without success records.
Validation and adoption tests/cmd_create_integration.bats, README.md, docs/agent-usage.md, CHANGELOG.md, .github/instructions/testing.instructions.md, completions/*, scripts/generate-completions.sh	Tests cover output records, escaping, hook behavior, restrictions, and failures. Documentation and shell completions describe --porcelain.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Mergeability Score: 🔵 Low · up to 91533

The documented agent workflow still shows a command form that conflicts with the required public interface, which could mislead users or automation; the PR is otherwise mergeable with explicit owner follow-up to correct the example.

Sequence Diagram(s)

sequenceDiagram
  participant Agent
  participant git_gtr_new
  participant WorktreeCreation
  participant Hooks
  Agent->>git_gtr_new: run new --porcelain
  git_gtr_new->>WorktreeCreation: create worktree noninteractively
  WorktreeCreation->>Hooks: inspect and run post-create hooks
  Hooks-->>WorktreeCreation: return hook status
  WorktreeCreation-->>Agent: stable records on stdout
  Hooks-->>Agent: progress and hook output on stderr

Loading

Possibly related PRs

• coderabbitai/git-worktree-runner#163: Provides the .gtrconfig hook trust mechanism used for porcelain hook-status reporting.

Poem

A rabbit reads three records bright,
Path and branch in tabs aligned.
Hooks whisper softly to stderr,
While porcelain keeps stdout clear.
Safe worktrees bloom at dawn.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding machine-readable worktree creation for agents.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tommy/issue-67-agent-output

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/instructions/testing.instructions.md:
- Around line 26-28: Update the machine-readable creation command example to
invoke the documented git gtr interface instead of the repository-relative
./bin/gtr path, preserving all existing arguments and output behavior.

In `@README.md`:
- Around line 193-196: Update the --porcelain documentation to clarify that
path, branch, and hook_status records are emitted only when cmd_create completes
successfully; explicitly state that a failing post-create hook exits before
emitting any success records.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c41681fa-44d7-4bdf-b8a2-86a656bc6cac

📥 Commits

Reviewing files that changed from the base of the PR and between 214e49f and 1a88124.

📒 Files selected for processing (13)

• .github/instructions/testing.instructions.md
• CHANGELOG.md
• README.md
• completions/_git-gtr
• completions/git-gtr.fish
• completions/gtr.bash
• docs/agent-usage.md
• lib/commands/create.sh
• lib/commands/help.sh
• lib/hooks.sh
• scripts/generate-completions.sh
• tests/cmd_create_integration.bats
• tests/hooks.bats