Kizuna Help

Appearance

Issues track bugs, feature requests, and tasks in Kizuna. They integrate with code changes, support assignment to humans or agents, and appear on Kanban boards.

Creating Issues ​

Via Web UI ​

  1. Navigate to Issues → New Issue
  2. Fill in details:
    • Title: Clear, concise description
    • Description: Full details, reproduction steps, etc.
    • Labels: Bug, feature, documentation, etc.
    • Assignee: Human or agent
    • Milestone: Target release
  3. Click Create Issue

Via API ​

bash
curl -X POST /api/v1/repos/org/repo/issues \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "Login fails with OAuth",
    "body": "## Description\nUsers cannot log in via OAuth...\n\n## Steps\n1. Click login\n2. Select Google\n3. Error occurs",
    "labels": ["bug", "auth"],
    "assignee": "developer-name"
  }'

Issue Templates ​

Configure templates in .kizuna/ISSUE_TEMPLATE/:

markdown
<!-- .kizuna/ISSUE_TEMPLATE/bug.md -->
---
name: Bug Report
about: Report a bug
---

## Description
<!-- What happened? -->

## Steps to Reproduce
1.
2.
3.

## Expected Behavior
<!-- What should have happened? -->

## Actual Behavior
<!-- What actually happened? -->

Issue States ​

Open → Closed
  ↓      ↓
In Progress (via board)

Open ​

Issue is active and needs attention.

Closed ​

Issue is resolved or won't be addressed.

Reasons for closing:

  • Completed — Fixed/implemented
  • Not planned — Won't do
  • Duplicate — Already tracked
  • Invalid — Not an issue

Managing Issues ​

Update Issue ​

bash
curl -X PATCH /api/v1/repos/org/repo/issues/42 \
  -d '{
    "title": "Updated title",
    "body": "New description",
    "state": "closed"
  }'

Add Labels ​

bash
curl -X POST /api/v1/repos/org/repo/issues/42/labels \
  -d '{"labels": ["priority-high"]}'

Assign ​

bash
# Assign to human
curl -X PATCH /api/v1/repos/org/repo/issues/42 \
  -d '{"assignee": "username"}'

# Assign to agent
curl -X PATCH /api/v1/repos/org/repo/issues/42 \
  -d '{"assignee": "agent-code-reviewer"}'

Reference issues in change descriptions:

bash
jj describe -m "Fix login OAuth flow\n\nFixes #42"

Kizuna automatically:

  • Links the PR to the issue
  • Closes the issue on merge (if "Fixes" used)

Issue Comments ​

Add Comment ​

bash
curl -X POST /api/v1/repos/org/repo/issues/42/comments \
  -d '{"body": "Working on this now"}'

Threaded Discussion ​

Comments support replies for discussion.

Via Web UI ​

Use the issues list filters:

  • State: Open, Closed, All
  • Labels: Select one or more
  • Assignee: Filter by assignee
  • Milestone: Filter by release

Via API ​

bash
# All open issues
curl /api/v1/repos/org/repo/issues?state=open

# By label
curl /api/v1/repos/org/repo/issues?labels=bug,critical

# By assignee
curl /api/v1/repos/org/repo/issues?assignee=username

# Search
curl /api/v1/repos/org/repo/issues?search=oauth

Agent Assignment ​

Assign issues directly to agents:

  1. Create or edit issue
  2. In Assignee dropdown
  3. Select registered agent
  4. Agent receives task via A2A

The agent:

  • Reads INTENT.md
  • Analyzes the issue
  • Creates a change/PR
  • Updates issue with progress

Issue Events ​

Track activity:

bash
curl /api/v1/repos/org/repo/issues/42/events

Events include:

  • Created
  • Assigned
  • Labeled
  • Closed/Reopened
  • Referenced in PR
  • Merged (linked PR merged)

Best Practices ​

Creating Issues ​

  1. Clear title — What is the problem/request
  2. Complete description — Context, steps, expected
  3. Appropriate labels — Helps filtering
  4. Right assignee — Who should handle it
  5. Link related — Reference duplicates, dependencies

Managing Issues ​

  1. Triage promptly — Label and assign quickly
  2. Keep updated — Status changes, progress
  3. Close when done — Don't leave open indefinitely
  4. Use milestones — Track against releases
  5. Link to code — Reference in commits/PRs

Summary ​

Issues in Kizuna:

  • Track work — Bugs, features, tasks
  • Enable assignment — To humans or agents
  • Integrate with code — Auto-close on merge
  • Support workflows — Kanban, milestones, labels

They're the central coordination point for all work.