SKILL.md

name: working-with-bug

description: Use when collaborating with humans using the bug CLI tool to track and resolve issues

Bug CLI Agent Collaboration

Overview

The bug CLI tool provides a dual API for issue tracking: - Human API (bug new, bug read, etc.): Lenient, interactive, designed for human use - Agent API (bug agent new, bug agent read, etc.): Strict, non-interactive, designed for automation

Core principle: Always use commands under bug agent when acting as an agent. These commands are non-interactive, require explicit flags, and use the agent identity created during bug init.

Check the version first: Run bug version (e.g. bug version 1.0.1) before starting work so you know which features are available in the installed binary. The version is embedded at build time from the version field in flake.nix.

Announce at start: “I’m using the bug-cli-agent skill to collaborate on this issue.”

Typical Collaboration Workflow

When a user asks you to work on a bug, follow this workflow:

Step 1: Read the Bug

Use bug agent read [bugID] to fetch the bug details and all existing comments (which may include a previously documented plan):

bug agent read abc1234

Important: Use bug agent read, not bug read. The agent version is non-interactive and returns structured output suitable for parsing.

Step 2: Create an Implementation Plan

REQUIRED SUB-SKILL: Invoke superpowers:writing-plans to create a comprehensive implementation plan.

Announce: "I'm using superpowers:writing-plans to create an implementation plan."

This will generate a detailed, bite-sized plan for resolving the bug.

Step 3: Document the Plan as a Comment

Save the plan to the bug by adding it as a comment. Plans should be written in raw markdown format:

bug agent comment abc1234 --message "## Implementation Plan

### Task 1: [Component Name]
**Files:**
- Create: path/to/file.ts
- Test: path/to/test.ts

**Step 1: Write the failing test**
[code example]

**Step 2: Run test to verify it fails**
Run: command
Expected: output"

For multi-line plans, the message flag accepts the full markdown content.

Step 4: Execute the Plan

When ready to implement:

Read the bug again to get the plan from the comments:
```
bug agent read abc1234
```
REQUIRED SUB-SKILL: Invoke superpowers:executing-plans to execute the plan task-by-task:
```
Announce: "I'm using superpowers:executing-plans to implement the documented plan."
```
Update the bug when work is complete with a summary of what was done using bug agent comment.
Do not close the bug until the user checks the implementation and tells you to do so. Then use:
```
bug agent close abc1234
```

Agent API Reference

All agent commands are non-interactive and require explicit flags. They use the agent identity (name: “agent”, created during bug init).

bug agent read [bugID]

Display a bug/issue and all its comments.

bug agent read abc1234

Output includes: - Title, ID (7-char prefix), Author, Creation date, Status, Labels - Parent (Parent: <7-char> - <title>, only if the issue has a parent) - Description (first comment) - All additional comments with their IDs

Use this to: - Fetch bug details for analysis - Retrieve documented plans from comments - Check current status before acting

bug agent new –title “…” [–message “…” | –stdin | –from-file ] [–parent ]

Create a new bug/issue as the agent.

# Using --message flag (simple strings)
bug agent new --title "CI Failure" --message "Build failed on commit abc123"

# Linking under a parent issue (short or full ID)
bug agent new --title "Subtask" --message "Details" --parent abc1234

# Using --stdin (pipe content)
echo "Build failed on commit abc123" | bug agent new --title "CI Failure" --stdin

# Using --from-file (read from file)
bug agent new --title "CI Failure" --from-file /tmp/description.md

Required flags: - --title: Issue title - One of the following for message content: - --message "...": Provide message as a command-line string - --stdin: Read message from standard input - --from-file <path>: Read message from a file

Optional flags: - --parent <bugID>: Link the new issue under a parent issue (short or full ID) (since v1.0.0)

Important: --message, --stdin, and --from-file are mutually exclusive. You must choose exactly one method to provide the message content.

Best practice for multi-line markdown content: Use --stdin or --from-file instead of --message. Long multi-line strings with markdown formatting often fail when passed as shell command-line arguments due to escaping issues.

Examples with HEREDOC and temp files:

# Using HEREDOC with --stdin
bug agent new --title "Complex Bug" --stdin << 'EOF'
## Description

This bug involves multiple steps:
1. First step
2. Second step

**Expected:** It should work
**Actual:** It fails with error
EOF

# Using a temp file for large content
cat > /tmp/bug_desc.md << 'EOF'
## Problem
Detailed markdown content here...

- List item 1
- List item 2
EOF
bug agent new --title "Complex Bug" --from-file /tmp/bug_desc.md

bug agent comment [bugID] [–message “…” | –stdin | –from-file ]

Add a comment to an existing bug.

# Using --message flag (simple strings)
bug agent comment abc1234 --message "Automated analysis complete"

# Using --stdin (pipe content)
echo "Analysis complete" | bug agent comment abc1234 --stdin

# Using --from-file (read from file)
bug agent comment abc1234 --from-file /tmp/comment.md

Required: Exactly one of the following for message content: - --message "...": Provide message as a command-line string - --stdin: Read message from standard input - --from-file <path>: Read message from a file

Important: --message, --stdin, and --from-file are mutually exclusive. You must choose exactly one method to provide the message content.

Examples with HEREDOC and temp files:

# Using HEREDOC with --stdin
bug agent comment abc1234 --stdin << 'EOF'
## Implementation Plan

### Task 1: [Component Name]
**Files:**
- Create: path/to/file.ts

**Step 1: Write the failing test**
[code example]
EOF

# Using a temp file for large content
cat > /tmp/progress.md << 'EOF'
## Progress Update

Completed the following:
- Item 1
- Item 2
EOF
bug agent comment abc1234 --from-file /tmp/progress.md

Use this to: - Document implementation plans - Add progress updates - Record findings or analysis results

bug agent edit [bugID] –title “…” [–message “…” | –stdin | –from-file ]

Edit an issue’s title and/or description.

# Edit title only
bug agent edit abc1234 --title "New Title"

# Edit message using --message flag (simple strings)
bug agent edit abc1234 --message "New description"

# Edit message using --stdin
echo "New description" | bug agent edit abc1234 --stdin

# Edit message using --from-file
bug agent edit abc1234 --from-file /tmp/new_desc.md

# Edit both title and message
bug agent edit abc1234 --title "New Title" --message "New description"

# Set the parent issue (only if none set)
bug agent edit abc1234 --parent def5678

Flags: - --title: New issue title (optional, but at least one flag must be provided) - One of the following for message content (optional): - --message "...": Provide message as a command-line string - --stdin: Read message from standard input - --from-file <path>: Read message from a file - --parent <bugID>: Parent issue short or full ID (optional, issues only; at least one of --title, message content, or --parent must be provided) (since v1.0.0)

Note: A parent link can only be added when the issue has none; parent links cannot be changed or removed afterwards. Links that would close a dependency cycle are rejected.

Important: When editing the message, --message, --stdin, and --from-file are mutually exclusive. You must choose exactly one method to provide the message content.

Examples with HEREDOC:

# Update description with HEREDOC
bug agent edit abc1234 --stdin << 'EOF'
## Updated Description

New details about this bug:
- Point 1
- Point 2
EOF

Note: When editing bugs, at least one of --title, a message option, or --parent must be provided.

bug agent edit [commentID] [–message “…” | –stdin | –from-file ]

Edit an existing comment.

# Using --message flag (simple strings)
bug agent edit def5678 --message "Updated comment text"

# Using --stdin (pipe content)
echo "Updated comment text" | bug agent edit def5678 --stdin

# Using --from-file (read from file)
bug agent edit def5678 --from-file /tmp/updated_comment.md

Important: - Comments have no title field. Only message options are accepted when editing a comment ID. - --message, --stdin, and --from-file are mutually exclusive. You must choose exactly one method to provide the message content.

Examples with HEREDOC:

# Update comment with HEREDOC
bug agent edit def5678 --stdin << 'EOF'
## Updated Analysis

New findings:
- Finding 1
- Finding 2
EOF

Tracking Epics and Subtasks with Parent Links (since v1.0.0)

Use --parent to group subtasks under a parent epic or tracking issue. In bug ls, children nest under their parent with tree markers (├─, └─).

Default sort is oldest first: within a parent, subtasks display top-to-bottom in creation order (oldest first, youngest last). Creation order therefore doubles as priority order when the user plans work with bug ls.

Recommended flow — parent first: 1. Create the parent epic first:

   bug agent new --title "Epic: checkout rewrite" --message "..."

Create each subtask in the order it should be addressed, highest priority first:
```
bug agent new --title "Step 1: ..." --message "..." --parent <epicID>
bug agent new --title "Step 2: ..." --message "..." --parent <epicID>
```
bug ls now lists Step 1 above Step 2 under the epic, so the user reads the plan top-down.

Alternative flow — children first: 1. Create the subtasks in the order they should be addressed. 2. Create the parent epic afterwards. 3. Link each child to the parent:

   bug agent edit <childID> --parent <epicID>

Because display order follows creation order, the first-created subtask still appears first.

Limits: a parent link can only be added when the issue has none; links cannot be changed or removed afterwards, and links that would close a dependency cycle are rejected.

bug agent open [bugID]

Open a closed bug/issue.

bug agent open abc1234

bug agent close [bugID]

Close an open bug/issue.

bug agent close abc1234

Use this when the issue is resolved.

bug agent rm [bugID]

Remove a bug/issue.

bug agent rm abc1234
bug agent remove abc1234

WARNING: This action is permanent.

Note: Individual comments cannot be removed. Use this to remove the entire issue.

bug version

Print the version of the installed bug binary.

bug version

Output: bug version <version> (e.g. bug version 1.0.1), matching the version field in flake.nix.

Use this to: - Check which features are available before starting work - Report the binary version when debugging unexpected behavior

Important Notes

Agent Identity

The agent identity is created during bug init with: - Name: “agent” - Email: “” (empty)

All bug agent commands use this identity. Do not attempt to create or modify the agent identity.

ID Formats

Bug IDs are 64-character hex strings. The CLI accepts shortened prefixes: - Short ID: First 7 characters (e.g., abc1234) - Full ID: Complete 64-character ID

Both formats work with all commands. Short IDs are preferred for convenience.

Working with a Repository in a Different Location

All commands accept a --repo flag:

bug agent --repo /path/to/repo read abc1234
bug agent --repo /path/to/repo comment abc1234 --message "Update"

By default, commands operate on the current directory (.).

Comment IDs vs Bug IDs

When editing: - Bug IDs (e.g., abc1234) refer to the entire issue - Comment IDs (e.g., def5678) refer to individual comments

The bug agent edit command automatically detects the type and behaves accordingly: - For bugs: accepts --title and/or --message - For comments: accepts only --message

Message Content Options

Agent commands that require message content (bug agent new, bug agent comment, bug agent edit) support three mutually exclusive methods for providing the message:

Option	When to Use	Example
`--message "..."`	Short, simple text without special characters	`bug agent new --title "Bug" --message "It broke"`
`--stdin`	Multi-line content, markdown, or piped input	`cat description.md \\| bug agent new --title "Bug" --stdin`
`--from-file <path>`	Large content already in a file	`bug agent new --title "Bug" --from-file /tmp/desc.md`

Important rules: 1. Mutually exclusive: You must use exactly one of --message, --stdin, or --from-file per command 2. Best practice for markdown: Use --stdin or --from-file for multi-line markdown content to avoid shell escaping issues 3. Error handling: If you specify multiple options, the command will fail with a clear error message explaining the conflict

HEREDOC patterns (recommended for agents):

# Pattern 1: Inline HEREDOC to stdin
bug agent comment abc1234 --stdin << 'EOF'
## Implementation Plan

### Task 1
- Step 1
- Step 2
EOF

# Pattern 2: Write to temp file first
plan_file=$(mktemp)
cat > "$plan_file" << 'EOF'
## Implementation Plan

### Task 1
- Step 1
- Step 2
EOF
bug agent comment abc1234 --from-file "$plan_file"
rm "$plan_file"

Complete Workflow Example

Scenario: User asks “Can you fix the bug with ID abc1234?”

# Step 1: Read the bug
bug agent read abc1234

# Output shows:
# Title: Memory leak in data processor
# Author: [email protected]
# Status: open
# Description: The data processor leaks memory when processing large files...

# Step 2: Invoke writing-plans skill
Announce: "I'm using superpowers:writing-plans to create an implementation plan."

# Step 3: Document the plan as a comment
bug agent comment abc1234 --message "## Fix: Memory leak in data processor

### Task 1: Add failing test
**Files:**
- Create: test/memory_test.go
- Test: TestMemoryLeak

**Step 1: Write failing test**
[code]

**Step 2: Verify test fails**
Run: go test -v ./test
Expected: FAIL: memory leak detected

### Task 2: Implement fix
..."

# Step 4: When ready to execute, read the bug again
bug agent read abc1234

# Step 5: Invoke executing-plans skill
Announce: "I'm using superpowers:executing-plans to implement the documented plan."

# Step 6: Add progress comments as needed
bug agent comment abc1234 --message "Task 1 complete: Added failing test in commit abc1234"

# Step 7: Close the bug when complete
bug agent close abc1234

Integration with Superpowers Skills

REQUIRED SUB-SKILLS:

superpowers:writing-plans - REQUIRED for creating implementation plans
- Creates bite-sized, detailed tasks
- Documents exact files, code, and verification steps
- Use when analyzing a bug before implementing
superpowers:executing-plans - REQUIRED for implementing documented plans
- Executes tasks in batches with review checkpoints
- Follows the plan exactly as documented in bug comments
- Use when implementing a plan previously documented on a bug

Error Handling

If a command fails:

Read the error message - it includes guidance on what to do next
Common issues:
- “agent identity not found” → Run bug init first
- “failed to resolve bug ID” → Check the ID is correct
- “title/message cannot be empty” → Ensure required flags are provided
Use bug agent read to verify the current state before retrying