db-aeon/joshu-oss/ea-project-kanban

EA Project Kanban

Default for multi-step work. If a request has several steps, parallel lanes, timed follow-ups, or human-in-the-loop (owner approval, replies, judgment calls), run it on a dedicated Hermes board — not as a one-shot chat turn or rows in todo.md alone.

Kanban gives you durable state (ready / running / blocked / done), crash recovery, Hermes Admin visibility, and kanban_block when waiting on a person. Joshu action guard on sends is a common HITL gate — workers should expect kanban_block until approval clears.

Projects/<slug>/ holds a brief summary and file pointers — not a mirror of every card.

Layout: docs/executive-assistant.md · ${JOSHU_FILES_ROOT}/FILING.md

When to use Kanban (prefer this skill)

Skip Kanban for: single quick answers, one immediate send with no follow-up, inbox stub filing (ea-playbook), or automated meeting-mail scheduling (ea-scheduling).

Triggers

vs other EA skills

Kickoff flow

1. Clarify (minimal): goal, steps or waves, who/what is parallel, HITL gates (approvals, owner decisions), follow-up timing.
2. Filesystem under ${JOSHU_FILES_ROOT}/Projects/<slug>/:

• about.md — outcome, urgency; leave kanban_board / kanban_root_task null until step 5
• Supporting files as needed — e.g. recipients.md (outreach), brief.md (constraints for root card body)

1. Board project-<slug> (slug = folder slug, lowercase hyphens).

Create the board using one of these paths (check in order):

A) Joshu bridge MCP tools (preferred on Joshu boxes). mcp_joshu_connectors_project_kanban_ensure_board(projectSlug="<slug>", name="<Short title>") creates the board and returns db_path. Then mcp_joshu_connectors_project_kanban_create_triage_root(projectSlug="<slug>", title="...", body="...") for the root task (body from decomposition-template.md).

B) `kanban_create` / `kanban_list` tools if your profile has the kanban toolset (check your tool list before assuming they're absent — you may have them even when the CLI is missing).

C) Hermes CLI if on PATH and tools unavailable:

``bash hermes kanban boards create project-<slug> \ --name "<Short title>" # NOTE: workdir is set per-task on kanban create via --workspace dir:<path>, not on the board itself. ``

D) SQLite direct insert if none of the above are available (see references/kanban-sqlite.md).

Board slug must match project-<slug>.

1. Triage root card (when not created via MCP in step A) — no assignee, triage: true (CLI: --triage). Body from decomposition-template.md. Pass body text inline:

``bash # Body text is passed inline via --body (not a file path flag) BODY=$(cat /path/to/body.md) && hermes kanban create "Title" --triage --body "$BODY" ``

1. Update `about.md` frontmatter:

kanban_board: project-<slug>
kanban_root_task: <task_id from create>

Append one-line outcome under the title. Do not copy every child task into todo.md.

Worker execution (after decompose)

Child tasks run via dispatcher (kanban-worker + assignee profile, default default).

1. kanban_show() — read title, body, workspace
2. Work in $HERMES_KANBAN_WORKSPACE (project folder)
3. Outbound mail: `nylas_send_message` via Joshu connectors MCP — action guard = HITL; do not spin in chat; kanban_block(reason="awaiting owner approval", kind="needs_input") until send succeeds
4. Browser / sensitive UI: use joshu-browser when the step needs owner in the loop; then kanban_block(reason="awaiting owner — <action>", kind="needs_input") or kanban_complete with evidence in metadata
5. Complete: kanban_complete(summary=..., metadata={step, evidence})
6. HITL / waiting: the owner must decide, approve, or act → kanban_block(reason="awaiting owner — <decision or action>", kind="needs_input"). An external party must reply → kanban_block(reason="awaiting reply: <who and what>") without kind. Only kind="needs_input" gets a proactive nudge to the owner.
7. Follow-ups: prefer scheduled_at on create or parents deps (next wave after prior done)

Follow-ups and replies

• Timed follow-up: create or decompose wave-2 cards with scheduled_at (ISO8601) or parent links to wave-1 ids
• Reply received: comment on the relevant card; kanban_block follow-up until meeting worker logic applies — do not auto-send without reading the thread (read_file on mail mirror or gbrain)
• Milestones only in journal_YYYY-MM-DD.md and about.md summary — not per-card rows in todo.md

Hermes Admin

Owner can supervise at hermes-admin.<box>/ — pick board project-<slug> in the switcher.

Forbidden

• ea-sched-ingress / ea-scheduling boards for campaigns
• scheduling_* MCP tools
• triage creates on EA boards (Joshu bridge rejects them)
• Mirroring full Kanban backlog into todo.md
• kanban_create from workers to fan out unrelated work (orchestrator / decomposer handles fan-out)

Pitfalls

Tool order matters. On Joshu VPS boxes, prefer Joshu bridge MCP (step 3A) before CLI or SQLite. Do not waste retries on hermes kanban when project_kanban_* MCP tools are available.

`hermes` CLI not on PATH. If which hermes fails, fall through to kanban_* tools or SQLite (step 3D). Do not waste retries on the CLI.

`kanban_*` tools not in toolset. On Joshu jChat/voice (api_server), native kanban_* should be registered — use tool_search or kanban_list before assuming absence. On workers, prefer MCP (3A) when bridge tools fit. SQLite (3D) is worker-only last resort; never for ea-scheduling or owner chat mark-done flows.

SQLite db_path unknown. Board databases live at ~/.hermes/kanban/boards/project-<slug>/kanban.db. If the board hasn't been created yet, use mcp_joshu_connectors_project_kanban_ensure_board first, then locate the db from .meta.db_path.

ID collision on manual insert. Always query existing task IDs (SELECT id FROM tasks) and use secrets.token_hex(6) with a collision-check loop. Do not guess or increment hex values.

Task state can change between dispatch and startup. Always kanban_show first if the tool is available. If status is blocked or archived, stop — you shouldn't be running.

Body is JSON, not opaque text. The body column stores structured metadata (name, email, e1_sent, etc.) as serialized JSON. When reading body back, use json.loads() — do not treat it as plaintext.

Escalation

Surface to owner: bulk list unclear, legal/financial sensitivity, repeated send failures, action guard timeout.