Kanban 튜토리얼

Hermes Kanban 시스템의 4가지 사용 사례를 통해 브라우저에서 열린 대시보드와 함께 설계되었습니다. 아직 Kanban Summary을 읽지 않은 경우, 거기에서 시작하세요 - 이것은 당신이 무슨 일을 알고, 실행, 할당, 및 파견자는.

설치하기

hermes kanban init           # optional; first `hermes kanban <anything>` auto-inits
hermes dashboard             # opens http://127.0.0.1:9119 in your browser
# click Kanban in the left nav

대쉬보드는 ** You**를 위한 가장 편안한 장소로 시스템의 볼 수 있습니다. 에이전트 노동자 파견자는 대시보드 또는 CLI를 볼 수 없습니다. 전용 kanban_* toolset (kanban_show, kanban_complete, ..., ..., ..., ..., ..., ..., .... 모든 세 개의 표면 - 대시 보드, CLI, 노동자 도구 - SQLite DB (~/.hermes/kanban.db 기본 보드에 대한, ~/.hermes/kanban/boards/<slug>/kanban.db 나중에 생성하는 어떤 보드에 대한), 그래서 각 보드는 변화가 온 울타리의 측면이 일관성이 없습니다.

이 튜토리얼은 전체 default 보드를 사용합니다. 여러 개의 고립 된 큐 (프로젝트 / 재포 / 도메인 당 하나)를 원한다면, 개요에서 Boards (multi-project)를 참조하세요. - 동일한 CLI / 대쉬보드 / 작업자 흐름은 보드 당 적용되며, 물리적으로 다른 보드에서 작업을 볼 수 없습니다.

튜토리얼을 통해, 코드 블록 라벨링 bash 명령은 you 실행입니다. 코드 블록 레테르를 붙인 # worker tool calls는 도구 통화로 만들어진 모델이 방출되는 것입니다 - 여기에 표시되어 있으므로 루프 엔드 투 엔드를 볼 수 있으므로 자신을 실행하지 않습니다.

한 눈에 널

6개의 란, 오른쪽으로 좌측:

• Triage- 원시 아이디어, 스펙터는 누구나 그들에 작동하기 전에 spec을 살 것입니다. 을 클릭합니다**✨ 지정** 모든 삼기 카드에 버튼 (또는 실행 hermes kanban specify <id> / /kanban specify <id> 채팅에서) auxiliary LLM은 전체 사양으로 하나의 라이너를 돌려 (고용, 접근, 수용 기준) 하나 샷에서 todo로 승진. 어떤 모델이 auxiliary.triage_specifier에서 config.yaml 아래에서 실행합니다.
• Todo — 생성하지만 의존성에 대기, 또는 아직 할당되지.
• Ready — 청구에 대한 배정 및 대기.
• 진행 - 작업자는 작업이 활발합니다. "Lanes by profile" 에 (기본값), 할당에 의해이 열 하위 그룹 그래서 당신은 각 노동자가하는 것을 한 눈에 볼 수 있습니다.
• Blocked — 노동자는 인간 입력 또는 회로 차단기를 위해 물었다.
• 완료 — 완료.

상단 바는 검색, 임계인 및 할당자를위한 필터를 가지고 있으며 Lanes by profile toggle과 Nudge dispatcher 버튼을 사용하여 daemon의 다음 간격을 기다리는 대신 한 파견 진드기를 실행합니다. 모든 카드를 클릭하면 오른쪽에 서랍을 엽니다.

플랫 뷰

프로파일 레인이 noisy 인 경우, toggle "Lanes by profile" off 및 In Progress 컬럼은 청구 시간으로 주문 한 단일 평면 목록으로 축소합니다

· 클래스를 가진 보드

스토리 1 - 솔로 dev shipping a feature

당신은 기능을 구축하고 있습니다. Classic flow: 디자인 schema, 구현 API, 쓰기 테스트. 부모→child 종속을 가진 3개의 일.

SCHEMA=$(hermes kanban create "Design auth schema" \
    --assignee backend-dev --tenant auth-project --priority 2 \
    --body "Design the user/session/token schema for the auth module." \
    --json | jq -r.id)

API=$(hermes kanban create "Implement auth API endpoints" \
    --assignee backend-dev --tenant auth-project --priority 2 \
    --parent $SCHEMA \
    --body "POST /register, POST /login, POST /refresh, POST /logout." \
    --json | jq -r.id)

hermes kanban create "Write auth integration tests" \
    --assignee qa-dev --tenant auth-project --priority 2 \
    --parent $API \
    --body "Cover happy path, wrong password, expired token, concurrent refresh."
``API` 에는 `SCHEMA` 의 부모로서 `tests` 는 `API` 의 부모로서 `SCHEMA` 는 `ready` 에서 시작합니다. 다른 두는 `todo`에 부모가 완료 될 때까지 앉아. 이것은 그것의 일을 하는 신뢰성 촉진 엔진입니다 — 다른 노동자는 시험이 시험할 때까지 시험 쓰기를 선택할 것입니다.

다음 파견자 진드기 (60s by default, or right if you hit**Nudge dispatcher**) `backend-dev` 프로필은 env의 `HERMES_KANBAN_TASK=$SCHEMA`와 함께 작업자로 향합니다. 여기서 worker의 tool-call 루프가 에이전트 내부와 같이 보입니다

```python
# worker tool calls — NOT commands you run
kanban_show()
# → returns title, body, worker_컨텍스트, parents, prior attempts, comments

# (worker reads worker_컨텍스트, uses terminal/file tools to design the schema,
#  write migrations, run its own checks, commit — the real work happens here)

kanban_heartbeat(note="schema drafted, writing migrations now")

kanban_complete(
    summary="users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); "
            "refresh tokens stored as sessions with type='refresh'",
    metadata={
        "changed_files": ["migrations/001_users.sql", "migrations/002_sessions.sql"],
        "decisions": ["bcrypt for hashing", "JWT for session tokens",
                      "7-day refresh, 15-min access"],
    },
)
``kanban_show` 기본값 `task_id` 에 `$HERMES_KANBAN_TASK`, 그래서 노동자는 자신의 ID를 알 필요가 없습니다. `kanban_complete`는 현재 `task_runs` 행에 요약 + 메타데이터를 작성하고, 실행 중인 작업을 닫고, `done`에 작업을 전환합니다. `kanban_db`를 통해 하나의 원자 힙합에서 모두합니다.

`SCHEMA`가 `done`를 보았을 때, 종속 엔진은 `API`를 `ready`로 자동으로 생성합니다. API worker, 그것을 픽업 할 때, `kanban_show()`를 호출하고 `SCHEMA`의 요약 및 메타데이터를 참조하여 부모 Handoff에 첨부합니다. 그래서 긴 디자인 doc을 다시 읽지 않고 스키마 결정을 알 수 있습니다.

보드에 완성 된 스키마 작업을 클릭하고 서랍은 모든 것을 보여줍니다:

· [Solo dev - 완료 스키마 작업 서랍](/img/kanban-tutorial/02-board-flat.png)

하단의 런 역사 섹션은 키 추가입니다. 하나의 시도: outcome `completed`, worker `@backend-dev`, 기간, 타임스탬프, 그리고 전체에서 핸드오프 요약. metadata blob (`changed_files`, `decisions`)는 이 부모를 읽는 어떤 다운스트림 노동자든지에 너무 저장됩니다.

터미널에서 같은 데이터를 언제든 검사할 수 있습니다. — 이 명령은 ****** 보드에서 볼 수 있으며, 노동자가 아닙니다

```bash
hermes kanban show $SCHEMA
hermes kanban runs $SCHEMA
# #  OUTCOME       PROFILE       ELAPSED  STARTED
# 1  completed     backend-dev        0s  2026-04-27 19:34
#     → users(id, email, pw_hash), sessions(id, user_id, jti, expires_at); refresh tokens...

스토리 2 — Fleet 농업

당신은 세 명의 노동자 (번역자, transcriber, 복사본)과 독립적 인 작업의 더미가 있습니다. 평행하고 눈에 보이는 진전을 만들기에 모든 3 풀기를 원합니다. 이것은 가장 간단한 kanban use-case 및 하나에 최적화 된 원래 디자인입니다.

작업 만들기:

for lang in Spanish French German; do
    hermes kanban create "Translate homepage to $lang" \
        --assignee translator --tenant content-ops
done
for i in 1 2 3 4 5; do
    hermes kanban create "Transcribe Q3 customer call #$i" \
        --assignee transcriber --tenant content-ops
done
for sku in 1001 1002 1003 1004; do
    hermes kanban create "Generate product description: SKU-$sku" \
        --assignee copywriter --tenant content-ops
done

게이트웨이를 시작하고 도보 — 그것은 임베디드를 호스트 같은 세 가지 전문가 프로필의 작업을 선택 kanban.db:

hermes gateway start

이제 보드를 content-ops (또는 "Transcribe")로 필터링하고 다음을 얻을 수 있습니다

2개의 transcribes는, 1개의 달리기, 다음 파견자 진드기를 기다리는 2개의 준비되어 있습니다. In Progress 컬럼은 프로파일 ("Lanes by profile"default)에 의해 그룹화되어 있으므로 혼합 목록을 스캔하지 않고 각 작업자의 활성 작업을 볼 수 있습니다. 파견자는 현재 하나가 완료되면 실행할 준비가 된 작업을 촉진합니다. 3개의 다에몬이 병렬에 있는 3개의 posee 수영장에 일하는 상태에서, 더 인간적인 입력 없이 전체적인 내용 큐 하수구.

**모든 이야기 1은 구조화 손전락에 대해 여전히 적용됩니다. ** 통화를 완료하는 번역기 노동자는 kanban_complete(summary="translated 4 pages, style matched existing marketing voice", metadata={"duration_seconds": 720, "tokens_used": 2100})를 방출합니다. 분석 및 이 일에 따라 어떤 다운스트림 작업에 유용합니다.

Story 3 - 리트리와 역할 파이프라인

Kanban이 평평한 TODO 목록을 통해 수익을 올릴 수 있는 곳입니다. PM은 spec을 작성합니다. 엔지니어가 그것을 구현합니다. 검토자는 첫 번째 시도를 거부합니다. 엔지니어가 변경 사항을 다시 시도합니다. 리뷰 작성자.

대시보드보기, auth-project에 의해 필터링:

· 다양한 기능에 대한 그림보기

한 번에 볼 수있는 3 단 체인: Spec: password reset flow (DONE, pm), Implement password reset flow (DONE, backend-dev), Review password reset PR (READY, 검토자). 각에는 정체성으로 바닥과 어린이에 녹색이 있습니다.

흥미로운 것은 구현 작업입니다, 그것은 차단되고 재생되기 때문에. 도구가 각 노동자의 모델이 호출 한 것처럼 보이는 전체 3 시약 choreography입니다

# --- PM worker spawns on $SPEC and writes the acceptance criteria ---
# worker tool calls
kanban_show()
kanban_complete(
    summary="spec approved; POST /forgot-password sends email, "
            "GET /reset/:token renders form, POST /reset applies new password",
    metadata={"acceptance": [
        "expired token returns 410",
        "reused last-3 password returns 400 with message",
        "successful reset invalidates all active sessions",
    ]},
)
# → $SPEC is done; $IMPL auto-promotes from todo to ready

# --- Engineer worker spawns on $IMPL (first attempt) ---
# worker tool calls
kanban_show()   # reads $SPEC's summary + acceptance metadata in worker_context
# (engineer writes code, runs tests, opens PR)
# Reviewer feedback arrives — engineer decides the concerns are valid and blocks
kanban_block(
    reason="Review: password strength check missing, reset link isn't "
           "single-use (can be replayed within 30min)",
)
# → $IMPL transitions to blocked; run 1 closes with outcome='blocked'

이제 (인간, 또는 별도의 작성자 프로파일) 블록의 이유를 읽고, 수정 방향이 명확하고, 대시보드의 "Unblock" 버튼에서 차단 - 또는 CLI / 슬래시 명령에서:

hermes kanban unblock $IMPL
# or from a chat: /kanban unblock $IMPL

파견자는 $IMPL를 ready로 돌려주고 다음 진드기에 backend-dev 노동자를 되돌아줍니다. 이 두 번째 스페인은 새로운 실행 같은 작업에:

# --- Engineer worker spawns on $IMPL (second attempt) ---
# worker tool calls
kanban_show()
# → worker_context now includes the run 1 block reason, so this worker knows
#   which two things to fix instead of re-reading the whole spec
# (engineer adds zxcvbn check, makes reset tokens single-use, re-runs tests)
kanban_complete(
    summary="added zxcvbn strength check, reset tokens are now single-use "
            "(stored + deleted on success)",
    metadata={
        "changed_files": [
            "auth/reset.py",
            "auth/tests/test_reset.py",
            "migrations/003_single_use_reset_tokens.sql",
        ],
        "tests_run": 11,
        "review_iteration": 2,
    },
)

구현 작업을 클릭합니다. 서랍 쇼 2 시도:

· 2개의 런닝으로 진행 작업 완료

• Run 1 - blocked 로 @backend-dev. 리뷰 피드백은 outcome에서 오른쪽에 앉아 있습니다. "password strength check missing, reset link isn't single-use (30min 이내 재생 가능)".
• Run 2 - completed 로 @backend-dev. 신선한 요약, 신선한 metadata.

각 실행은 task_runs에서 자신의 결과, 요약 및 메타데이터로 행입니다. Retry 역사는 개념적인 afterthought가 "latest state"작업의 상단에 레이어링되지 않습니다. 그것은 기본 표현입니다. 재시동 노동자가 작업을 열 때, build_worker_컨텍스트는 이전 시도를 보여줍니다, 그래서 두 번째 패스 노동자는 왜 첫 번째 패스를 차단하고 스크래치에서 재시동 대신 해당 특정 결과를 주소.

검토자는 다음을 선택합니다. 그들이 열릴 때 Review password reset PR, 그들은 참조:

· 리뷰터의 파이프 라인의 서랍보기

부모 링크는 완료된 구현입니다. Review password reset PR에 대한 리뷰 작성자의 worker spawns가 호출될 때 kanban_show()를 호출하면, 반환된 worker_컨텍스트에는 부모의 가장-recent-completed-run Summary + metadata가 포함되어 있습니다. 검토자는 "added zxcvbn strength check를 읽습니다. 초기 토큰은 이제 단일 사용"이며, diff를 찾고 전에 손으로 변경된 파일 목록이 있습니다.

스토리 4 - 회로 차단기 및 충돌 복구

진짜 노동자는 실패합니다. 자격 증명, OOM 살인, 일시적인 네트워크 오류. 파견자는 방위의 2개의 선이 있습니다: 회로 차단기 그 후에 자동 구획 N 연속 실패 그래서 보드는 영원히 thrash하지 않습니다, ** crash detection** 그것은 작업자가 PID가 TTL이 만료되기 전에 갔다 작업을 다시 인용.

회로 차단기 - 영구적 인 전망 실패

AWS_ACCESS_KEY_ID가 프로필 환경에서 설정되지 않기 때문에 작업자가 살 수 없는 배포 작업:

hermes kanban create "Deploy to staging (missing creds)" \
    --assignee deploy-bot --tenant ops

파견자는 노동자를 spawn로 삼는다. 스페인은 실패 (RuntimeError: AWS_ACCESS_KEY_ID not set). 파견자는 주장을 방출, 실패 카운터를 증가, 그리고 다시 다음 진드기를 해제. 세 연속 실패 후 (기본 failure_limit), 회로 여행: 작업은 blocked로 이동하여 outcome gave_up. 인간이 차단할 때까지 더 많은 retries 없습니다.

블록 작업을 클릭합니다:

· Circuit 차단기 - 2 spawn_failed + 1 준_up

error 필드에 동일한 오류로 세 번 실행합니다. 첫번째 두는 spawn_failed (레트리블), 세 번째는 gave_up (terminal)입니다. 위의 이벤트 로그는 전체 순서를 보여줍니다: created → claimed → spawn_failed → claimed → spawn_failed → claimed → gave_up입니다.

터미널에:

hermes kanban runs t_ef5d
# #   OUTCOME        PROFILE        ELAPSED  STARTED
# 1   spawn_failed   deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 2   spawn_failed   deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 3   gave_up        deploy-bot          0s  2026-04-27 19:34
#       ! AWS_ACCESS_KEY_ID not set in deploy-bot env

Telegram / Discord / Slack이 유선되면, gave_up 이벤트에 게이트웨이 알림 화재가 표시되지 않고 정전에 대해 듣습니다.

충돌 복구 - worker dies mid-flight

때때로 스페인은 성공하지만 노동자 과정은 나중에 죽는다 - segfault, OOM, systemctl stop. 파견자는 kill(pid, 0)를 투표하고 죽은 pid를 감지합니다. 청구 릴리즈는 __HMES_TOKEN_00002__로 돌아갑니다. 다음 틱은 신선한 노동자에게 제공합니다.

씨앗 데이터의 예는 메모리에서 실행 된 마이그레이션입니다

# Worker claims, starts scanning 2. rows, OOM kills it at ~2.
# Dispatcher detects dead pid, releases claim, increments attempt counter
# Retry with a chunked strategy succeeds

서랍은 가득 차있는 2 면제 역사를 보여줍니다:

· 크래시 및 복구 - 1 크래시 + 1 완료

실행 1 - crashed, 과 오류 OOM kill at row 2. (process 99999 gone). 실행 2 - completed, 와 "strategy": "chunked with LIMIT + WHERE id > last_id" 메타데이터. Retrying worker는 컨텍스트에서 1 실행의 충돌을보고 더 안전한 전략을 선택했습니다. 메타데이터는 미래의 관찰자 (또는 postmortem Writer)에 분명하게 만듭니다. 변경 사항.

Structured handoff - 왜 summary와 metadata 문제

위의 모든 이야기에서, 노동자는 끝에서 kanban_complete(summary=..., metadata=...) 호출. 그것은 장식이 아닙니다 - 작업 흐름의 단계 사이에 기본 손전등 채널입니다.

작업 B에 노동자가 스패딩하고 호출 할 때 kanban_show(), worker_context 그것은 다시 포함:

• B'sprior attempts (이전 실행: outcome, 요약, 오류, 메타데이터) 그래서 재부팅 노동자는 실패한 경로를 반복하지 않습니다.
• Parent task results — 각 부모의 경우, 가장 알맞은 완료된 run's Summary and metadata — so downstream workers see why and how upstream work was done.

이것은 "dig through comments and the work output"무늬가 평평한 kanban 시스템. PM은 spec의 metadata에 합격 기준을 쓰고, 엔지니어의 노동자는 부모 handoff에서 구조적으로 보입니다. 그들이 ran 및 얼마나 많은 통과 테스트 엔지니어 기록, 그리고 검토자의 노동자는 diff를 열기 전에 손에 목록이 있다.

Bulk-close 가드는 이 데이터가 실행되기 때문에 존재합니다. hermes kanban complete a b c --summary X (You, from CLI)는 거절됩니다. 세 가지 작업에 동일한 요약을 복사하는 것은 거의 항상 잘못됩니다. handoff 플래그가 여전히 일반적인 "나는 관리자 작업의 더미를 완료"예를 들어 작동하지 않는 대량. 도구 표면은 모든에서 대량 변형을 노출하지 않습니다. kanban_complete는 항상 동일한 이유를 위해 단일 task-at-a-time입니다.

현재 실행중인 작업 검사

Completeness - 여기에는 여전히 비행에서 작업 서랍 (스토리 1에서 API 구현, backend-dev에 의해 주장하지만 아직 완료되지):

· 클래스, 백라이트 작업

상태는 Running입니다. 능동 실행은 outcome active와 ended_at와 Run History 섹션에서 나타납니다. 이 노동자가 죽거나 배운 경우, 파견자는 적절한 결과와 함께이 실행을 닫고 다음 주장에 새로운 것을 열어 - 시도 행은 결코 사라지지 않습니다.

다음 단계

• 칸반 개요 - 전체 데이터 모델, 이벤트 어휘, CLI 참조.
• hermes kanban --help - 모든 서브콤맨드, 모든 플래그.
• hermes kanban watch --kinds completed,gave_up,timed_out - 전체 보드의 라이브 스트림 터미널 이벤트.
• hermes kanban notify-subscribe <task> --platform telegram --chat-id <id> - 특정 작업이 완료되면 게이트웨이를 핑합니다.