hq-feature

name	hq-feature
description	Manage cross-repo feature branches via ClaudeHQ. Start, commit, push, PR, merge, or abandon features spanning multiple repos. Triggers: hq feature, cross-repo feature, feature branch, hq-feature.
argument-hint	<subcommand> <feature-name> [options]

/hq-feature — Cross-Repo Feature Manager

Manages feature branches that span multiple repositories using the hq feature CLI in ~/Projects/ClaudeHQ/scripts/hq.

Usage

/hq-feature start <name> [--repos=A,B,C]
/hq-feature status <name>
/hq-feature commit <name> -m "message"
/hq-feature push <name>
/hq-feature pr <name> [--title "..."] [--body "..."]
/hq-feature merge <name> [--auto]
/hq-feature abandon <name>

Examples

/hq-feature start gpt-models-integration --repos=claude-config,GptModels
/hq-feature status gpt-models-integration
/hq-feature commit gpt-models-integration -m "add execution-backends"
/hq-feature push gpt-models-integration
/hq-feature pr gpt-models-integration --title "feat: GPT models integration"
/hq-feature merge gpt-models-integration
/hq-feature abandon gpt-models-integration

Execution Steps

1. Resolve CLI path

Check that the hq CLI exists:

ls ~/Projects/ClaudeHQ/scripts/hq

If missing, report: "ClaudeHQ not found at ~/Projects/ClaudeHQ/scripts/hq. Clone the repo first."

2. Parse arguments

Extract from the invocation:

• subcommand — one of: start, status, commit, push, pr, merge, abandon
• feature-name — positional arg after subcommand
• remaining flags — pass through verbatim (e.g. --repos=..., -m "...", --title "...", --auto)

If no subcommand or feature-name is provided, show the usage block above and stop.

3. Run the command

~/Projects/ClaudeHQ/scripts/hq feature <subcommand> <feature-name> [flags...]

Capture both stdout and stderr. Do not modify or filter the output.

4. Report output

Print the full output from the command to the user. If the exit code is non-zero, highlight the error clearly and suggest a fix if obvious (e.g. wrong repo name, missing feature state file).

Subcommand Reference

Subcommand	Args	What it does
start	<name> [--repos=A,B,C]	Creates feature/<name> branch in each listed repo. If --repos omitted, uses all registered projects.
status	<name>	Shows branch status, divergence, and dirty files across all repos in the feature.
commit	<name> -m "msg"	Stages and commits changes in all repos that have modifications on the feature branch.
push	<name>	Pushes feature/<name> to remote in all repos.
pr	<name> [--title "..."] [--body "..."]	Opens pull requests in all repos. Title defaults to feature name if omitted.
merge	<name> [--auto]	Merges the feature PRs. --auto enables auto-merge when checks pass.
abandon	<name>	Deletes the feature branch locally and remotely in all repos, removes state file.

Rules

• NEVER edit the hq script — only invoke it
• Pass flags through verbatim; do not rewrite or reorder them
• If commit message contains spaces, ensure it is quoted properly when building the command string
• For pr subcommand: if --title is not in the invocation, do NOT invent one — let hq use its default

Error Handling

• CLI not found → stop, report path and suggest cloning ClaudeHQ
• Feature state file not found → report the exact error from hq, suggest running start first
• Non-zero exit on commit with no changes → inform user there was nothing to commit (not an error)
• 3 consecutive failures → stop and report blocker

When NOT to Use

• Single-repo operations — use standard git/gh commands instead
• If the user only wants to inspect code without touching branches

Verification

• Command ran without error
• Output reported back in full
• No flags were silently dropped or modified