name: kanban-local
description: Local markdown-file kanban for toy and personal projects. No server, no PostgreSQL, no auth — all state lives in KANBAN.md in the project root. Use for solo/small projects where the remote kanban board is overkill. Auto-trigger when KANBAN.md exists and user says "태스크 추가", "add task", "칸반 보여줘", "다음 할 일", "task list", or similar task-management phrases. Sub-commands: init, list, add, move, done, show, edit, refine, run, rm, stats.
kanban-local
로컬 KANBAN.md 한 파일로 모든 태스크 상태 관리. 원격 DB, 인증, 서버 불필요.
Safety principles: read ../kanban/principles.md — mandatory, not optional.
When to Use
- 토이 프로젝트, 개인 실험 레포 — SQLite 칸반이 과한 경우
- KANBAN.md가 있는 디렉터리에서 태스크 관련 요청이 오는 경우
- 사용하지 말 것: 팀 공유, 멀티-프로젝트 통합 뷰,
/kanban-run 에이전트 파이프라인 필요 시 → /kanban 사용
KANBAN.md 파일 포맷
파일은 상단: 보드 개요, 하단: 태스크 상세 두 섹션으로 구성된다.
---
project: <name>
last_id: 0
updated: YYYY-MM-DD
---
## todo
## doing
## review
## done
---
<!-- details -->
보드 개요 — 태스크 라인 포맷
- #001 [high] Task title · tag1,tag2
#NNN: 3자리 zero-padded ID[high|med|low]: 우선순위· tags: 옵션, 쉼표 구분
완료 태스크는 strikethrough:
- ~~#004~~ [low] ~~Completed task~~ · 2026-05-23
상세 블록 포맷 (<!-- details --> 아래)
### #001 · Task title
priority: high · tags: feat · created: 2026-05-23 · status: todo
**Goal**
What needs to happen.
**Acceptance Criteria**
- [ ] Criterion 1
---
각 상세 블록은 ---로 닫는다.
Commands
/kanban-local init [name]
현재 디렉터리에 KANBAN.md 생성.
KANBAN.md가 이미 있으면 현재 상태 표시 후 중단.- 프로젝트 이름: 인자 제공 시 사용, 없으면
basename $(pwd).
- Write 툴로 빈
KANBAN.md 생성 (frontmatter + 4개 섹션 헤더 + <!-- details -->).
- "KANBAN.md created for project
<name>." 확인.
초기 KANBAN.md 템플릿:
---
project: <name>
last_id: 0
updated: <YYYY-MM-DD>
---
## todo
## doing
## review
## done
---
<!-- details -->
/kanban-local 또는 /kanban-local list
보드 현황 표시.
- Read 툴로
KANBAN.md 읽기.
- 각 섹션(
## todo, ## doing, ## review, ## done)에서 태스크 라인 파싱.
- 아래 형식으로 출력:
## 📋 <project> — Kanban
| ID | Status | Pri | Title | Tags |
|------|--------|------|--------------------------------|-------------|
| #003 | doing | high | Currently working on this | feat,api |
| #001 | todo | high | Task title one | feat |
| #002 | todo | med | Another task | bug |
표시 순서: doing → review → todo → done (done은 최근 5개만). 빈 섹션은 "(empty)" 표시.
/kanban-local add <title>
새 태스크 추가.
- frontmatter의
last_id를 읽고 +1 → 새 ID (3자리 zero-pad, 예: 007).
- AskUserQuestion으로 확인:
- 우선순위: high / med(기본) / low
- 태그: 쉼표 구분 (선택)
- Goal/설명: 1–2문장 (선택, 없으면 "(TBD)")
## todo 섹션 마지막에 태스크 라인 추가:
- #NNN [<priority>] <title> · <tags>
<!-- details --> 아래에 상세 블록 추가:
### #NNN · <title>
priority: <p> · tags: <tags> · created: <YYYY-MM-DD> · status: todo
**Goal**
<description>
---
- frontmatter의
last_id와 updated 업데이트.
- "Added #NNN: → todo." 확인.
/kanban-local move <ID> <status>
태스크를 다른 열로 이동.
유효한 status: todo | doing | review | done
- Read 툴로
KANBAN.md 읽기.
- 모든 섹션에서
- #NNN 또는 - ~~#NNN~~ 라인 탐색.
- 현재 섹션에서 해당 라인 제거.
done으로 이동 시: strikethrough 적용 (~~#NNN~~ [pri] ~~title~~), 날짜 추가 ( · YYYY-MM-DD).done에서 다른 상태로 이동 시: strikethrough 제거, 날짜 제거.- 대상 섹션 마지막에 라인 추가.
- 상세 블록의
status: <old> → status: <new> 업데이트.
- frontmatter
updated 업데이트.
- "#NNN moved: → ." 확인.
/kanban-local done <ID>
/kanban-local move <ID> done 단축키.
/kanban-local show <ID>
태스크 상세 블록 표시.
KANBAN.md에서 ### #NNN · 헤딩 탐색.- 해당 헤딩부터 다음
--- 전까지 출력.
/kanban-local edit <ID>
태스크 필드 수정.
show로 현재 상태 표시.- AskUserQuestion으로 수정할 필드 확인 (제목, 우선순위, 태그, goal, 수락 기준).
- Edit 툴로 상세 블록 수정.
- 보드 개요 라인도 변경사항에 맞게 수정 (제목/우선순위/태그 변경 시).
- frontmatter
updated 업데이트.
/kanban-local refine <ID>
구조화된 요구사항 인터뷰 — /kanban-refine의 경량 버전.
대상: todo 상태 태스크. doing/review 상태면 경고 후 진행 여부 확인.
절차:
① show로 현재 상세 블록 읽기.
② 아래 차원에서 갭 분석:
- WHAT: 정확히 무엇을 만들거나 바꾸는가?
- WHY: 어떤 문제를 해결하는가?
- SCOPE: 포함/제외 범위는?
- ACCEPTANCE: 완료를 어떻게 판단하는가?
- EDGE CASES: 에러 상태, 경계 조건?
③ AskUserQuestion으로 인터뷰 (1라운드 최대 4개 질문, 최대 2라운드).
- 이미 명확한 항목은 묻지 않음.
- 사용자가 "충분해", "enough" 하면 조기 종료.
④ 상세 블록을 아래 템플릿으로 재작성:
### #NNN · <title>
priority: <p> · tags: <tags> · created: <date> · status: <status>
**Goal**
1–2문장: 무엇을, 왜.
**Scope**
- IN: ...
- OUT: ...
**Requirements**
1. 구체적이고 테스트 가능한 요구사항
2. ...
**Acceptance Criteria**
- [ ] 검증 가능한 기준 1
- [ ] ...
**Edge Cases**
- 에지 케이스 (있는 경우만)
---
내용 없는 섹션은 생략.
⑤ 정제된 내용을 사용자에게 보여주고 AskUserQuestion:
- "Approve & save" → Edit 툴로 저장
- "Edit more" → 인터뷰 재개
- "Cancel" → 변경 폐기
⑥ 저장 시 frontmatter updated 업데이트.
/kanban-local run <ID>
태스크를 실제로 수행하면서 KANBAN.md에 진행 기록을 남긴다.
에이전트 파이프라인 없이 Claude가 직접 구현하고, 상세 블록에 작업 로그를 기록하는 방식.
절차:
① KANBAN.md 읽기 → show <ID>로 상세 블록 확인.
- 상태가
todo가 아니면 현재 상태를 알리고 진행 여부 확인.
② 태스크를 doing으로 이동.
③ 실제 작업 수행.
④ 작업 완료 후 상세 블록 마무리.
⑤ 태스크를 done으로 이동.
- 보드 개요 라인: strikethrough 적용 + 날짜 추가.
- 상세 블록
status: doing → status: done.
- frontmatter
updated 갱신.
⑥ 완료 요약 출력:
✅ #NNN done — <title>
산출물: <파일 경로 또는 결과 요약>
Log 작성 원칙:
- 평범한 진행("파일 생성함")은 쓰지 않는다.
- 남길 가치가 있는 것만: 설계 결정, 트레이드오프, 막혔다가 해결한 지점, 다음 태스크가 알아야 할 사실.
- 한 줄로 충분하면 한 줄만.
중단/실패 처리:
/kanban-local stats
상태별 태스크 수 요약.
KANBAN.md 읽고 각 섹션의 태스크 라인 수 집계.- 출력:
## Stats — <project>
todo: N · doing: N · review: N · done: N · total: N
/kanban-local rm <ID> 또는 /kanban-local remove <ID>
태스크 삭제.
- AskUserQuestion으로 삭제 확인.
- 보드 개요에서 해당 라인 제거.
- 상세 블록(
### #NNN ·부터 다음 ---까지) 제거.
- frontmatter
updated 업데이트.
last_id는 변경하지 않음 (ID 재사용 금지).
파일 조작 규칙
- 항상 Read 툴로
KANBAN.md 읽은 후 수정.
- 수정은 Edit 툴로 타겟 변경. bash
sed/awk 사용 금지.
init 시에만 Write 툴 사용.- 모든 변경 후 frontmatter의
updated 날짜 갱신.
last_id는 단방향 증가만 — 삭제된 태스크 ID 재사용 금지.- 태스크 라인 구분:
- #NNN 또는 - ~~#NNN~~ 패턴.
- 상세 블록 구분:
### #NNN · 헤딩부터 다음 ---까지.
Auto-trigger 조건
KANBAN.md가 현재 디렉터리에 있고 아래 표현이 오면 /kanban-local 자동 활성화:
- "태스크 추가", "칸반 보여줘", "다음 할 일", "할 일 목록"
- "add task", "task list", "show board", "what's next"
