title: Bridge Lifecycle
created: ‘2026-07-09’
updated: ‘2026-07-09’
type: /wiki/Hyraxknot-Division/qa-review-checklist/

  • linear
  • kanban
  • lifecycle

Hyraxknot Division — Linear ↔ Hermes ↔ Kanban Bridge Lifecycle

Version: 1.0
Owner: Nei (bridge maintainer)
Last updated: 2026-07-01

1. Overview

The bridge connects Linear (source of truth) with Hermes Kanban (agent execution layer). Work begins in Linear, flows through the bridge into Kanban for agent execution, and results flow back to Linear.

Linear Issue ──→ Bridge Sync ──→ Kanban Card ──→ Agent Runs ──→ Linear Updated
                       ↑                                              │
                       └────────── Self-Healing Triage ───────────────┘

2. How a Linear Issue Becomes a Hermes Kanban Task

  1. Create an issue in Linear on the HYX team. Requirements:

    • Title should include a descriptive name
    • Required labels (see §3)
    • Correct project assignment (see §4)
    • Formatted description with ACs

  2. Bridge sync cycle (runs every 15 minutes) detects the agent-task label

  3. Bridge creates a corresponding Kanban card in the Hermes Kanban DB at ~/.hermes/kanban.db

  4. The card enters todo → ready status

  5. The Kanban dispatcher picks it up and spawns an agent session for the assigned profile

  6. The agent executes the task and writes results back

3. Required Issue Formatting

Labels

Label Purpose Required?
agent-task Signals the bridge: “this needs a kanban card” ✅ Required
type:* Task type: type:doc, type:implementation, type:spike, type:bug, type:qa, type:audit ✅ Required
area:* Domain area: area:workflow, area:skills, area:content, area:npc, etc. ✅ Recommended
🧿 sister-* Assignee label: 🧿 sister-tai, 🧿 sister-rei, 🧿 sister-nei, 🧿 sister-mai ✅ Required for agent tasks
🧿 josh Human task (not agent-routed) Optional

Label rules:

  • Only one 🧿 sister-* label per task — singular assignee
  • When passing a task to another sister, remove the old sister label and add the new one
  • agent-task must exist before the bridge will create a kanban card

Description

The description should include:

## Context
(why this task exists)

## Acceptance Criteria
- [ ] AC 1 ...
- [ ] AC 2 ...

## Evidence expected
(list of files, logs, or output to produce)

## Notes
(optional: constraints, risks, references)

State Flow

Backlog ──→ Todo ──→ In Progress ──→ Needs Review ──→ Done
                 ↓                      ↓
              Blocked <──── REWORK ────┘

4. Project Assignment Expectations

  • OpenRune Rev 239 — All OpenRune content: quests, skills, NPCs, zones, cache, ironman
  • Sister Systems — Division infrastructure: affinity, bridge, kanban, wiki, QA process
  • Hermes Ops — Gateway, webhooks, config, profiles, cron
  • Gestalt — Tai’s embodiment pipeline, avatar subsystems, animation
  • Bot Trajectory Pipeline — Training data, trajectory capture, ML pipeline
  • 2004Scape Guide Archive — 2004 era game guides
  • Knowledge and Docs — Wiki maintenance, skill authoring, onboarding
  • Division Map and HQ — Isometric HQ map, sprites, day/night

Issues without a project assignment will be flagged by self-healing triage (see §5).

5. Self-Healing Triage

The bridge scans for unformatted or unlabeled tasks during every sync cycle.

What triggers it

Any issue that:

  • Is not [EPIC], [GROUP], or [FEATURE] prefixed (those are structural)
  • Is missing the agent-task label
  • Or has no project assignment
  • Or is in a non-terminal state without proper formatting

What happens

  1. Bridge adds the needs-triage label
  2. Moves the issue to Triage workflow state
  3. Sends a batched notification to #linear Discord channel (max 5 per cycle to prevent floods)
  4. Nei picks up Triage issues and formats them properly

How needs-triage is removed

  • After a human or sister reviews the task and adds proper formatting (agent-task label, sections, etc.)
  • The next bridge sync sees agent-task present → removes needs-triage → creates the kanban card normally

6. Notification Routing

Where notifications go

Event Destination
Comment on issue #linear Discord channel
Status change #linear Discord channel
Triage flag #linear Discord channel (batched)
Status pings only Per-sister home channels

Why #linear

Consolidating Linear notifications into a single channel prevents:

  • Fragmented DMs that are easy to miss
  • Noise in work channels
  • Sister confusion about which channel to watch

7. Agent Replies on Linear

How sisters reply to comments

When a human comments on a Linear issue:

  1. The Linear webhook sends the event to the division server (POST /webhooks/linear)
  2. The server writes a notification file
  3. A reply handler picks it up and invokes the sister CLI
  4. The sister posts a contextual reply directly on Linear
  5. The reply includes <!-- agent:<sister> --> marker in the comment body

Loop prevention

The <!-- agent:<sister> --> marker is checked on every incoming webhook:

  • If the comment was posted by an agent (marker present) → the handler skips it
  • Only human comments trigger sister replies
  • This prevents infinite agent↔agent comment loops

8. Delegated Child Tasks

When an agent discovers that a task needs sub-tasks:

  1. Do not do it yourself — spawn follow-up tasks
  2. Use kanban_create with assignee set to the correct sister profile
  3. Always set parents=[current-task-id] to express dependency
  4. The child task won’t promote to ready until all parents are done
  5. Do not assign follow-up work to yourself — assign to the right specialist

Sister routing

Work type Assignee label Profile
Build/architecture 🧿 sister-tai tai
QA/review 🧿 sister-rei rei
Continuity/dashboard 🧿 sister-nei nei
Dispatch/support 🧿 sister-mai mai
Human review 🧿 josh (human)

9. Blocked Tasks

When a task cannot proceed:

  1. Move the issue to Blocked state in Linear
  2. Add a comment documenting the blocker and what’s needed
  3. The agent should call kanban_block(reason="...") so the board surfaces it
  4. The dispatcher will wait — do not guess or fabricate

Common blockers

  • Missing credentials or access
  • Unclear acceptance criteria
  • Depends on another task that is not Done
  • Requires a human decision you cannot infer

10. QA Review Gate

Before any implementation task moves to Done:

  1. The implementing sister/agent self-reviews using the QA Review Checklist
  2. The reviewing sister (default: Rei) runs the full checklist
  3. Verdict is posted as a comment:
    • PASS → Move to Done
    • PASS WITH FOLLOW-UP → Move to Done, link follow-up issue
    • REWORK → Return to In Progress with specific items
    • BLOCKED → Move to Blocked, document blocker

The verdict comment is the authoritative record that the task is complete.

11. Done / Rework / Blocked State Sync

Linear State Kanban Status Behavior
Done done Agent output is final; no further sync
Needs Review (with verdict REWORK) ready Task re-queued for the same assignee
Blocked blocked Task held; dispatcher won’t re-spawn
Canceled / Duplicate (no card) Bridge removes kanban card if one exists

12. Diagnosing Sync Failures

If a task didn’t sync:

  1. Does it have the agent-task label? (required)
  2. Does it have a 🧿 sister-* label? (required)
  3. Is it in the correct project?
  4. Check ~/.hermes/kanban.db for the card
  5. Check the bridge logs for errors
  6. Check Discord #linear for triage notifications

The bridge syncs every 15 minutes. If the issue was just created, wait for the next cycle.

Appendix: Quick Reference

Task lifecycle: Linear → Bridge (15min cycle) → Kanban → Agent → Result → Linear
Labels required: agent-task + type:* + 🧿 sister-*
Triage detection: missing labels → needs-triage → Triage state → #linear alert
Notifications: all Linear activity → #linear Discord channel
Sister replies: webhook → marker check → reply on Linear
QA gate: verbatim checklist → verdict → state change
previous Data Architecture next QA Review