KaibanJS/CLAUDE.md

Bit-Bot-Team — AI development team

This repo holds the orchestration for an autonomous AI development team that works a Notion Kanban backlog. Marius is the Product Manager (a human). The AI fills two roles, run as Claude Code commands:

• /plan — Planner (interactive, daytime): turns raw backlog ideas into fully-specified, ready-to-build tickets, asking Marius for missing info.
• /develop — Developer (autonomous, nightly): picks the top Ready ticket, implements it, writes tests, updates docs, and opens a PR.

Notion board (the single source of truth)

Everything lives on the Bit-Bot-Team Notion page. Use the Notion MCP tools (fetch, search, query-data-sources, update-page, create-comment) to read and write it.

Entity	ID
Bit-Bot-Team page	38210a5f51bd80dfa314ee42da639b95
Projects data source	collection://aeb682c0-b41b-4540-ac56-6ea43f5c0f14
Backlog data source	collection://6199f872-e2df-4e00-9add-450cf9712dc1

Projects schema

One row per application. The developer agent reads this to know where and how to build.

• Name, Status (Active/Paused/Archived)
• Repo — local path to the project folder (e.g. ~/Github/my-app)
• Default Branch — e.g. main
• Tech Stack — languages, frameworks, conventions the agent MUST respect
• Description — what the app is and who it's for
• Auto Commit — if checked, Developer commits directly to the default branch; if unchecked, Developer opens a PR for review (default for new projects)

Local-first development: All repos live in ~/Github/<ProjectName> on your Mac. Each folder contains code, docs, tests, everything for that project. The Developer agent works locally on your machine during iteration; we'll migrate to cloud infrastructure once the system is proven.

Backlog schema

The Kanban board. One row per ticket, related to a Project.

• Name — short title to distinguish tickets (for Marius)
• Feature Description — user story / feature narrative (what, for whom, why)
• Project (relation), Priority (P0–P3), Type (Feature/Bug/Chore/Docs)
• PR — pull request URL the developer fills in (or commit SHA if Auto Commit)
• Status — the workflow column (see below)

Status workflow

Inbox → Refining → Needs Info → Ready → In Progress → In Review → Done
                       ↑___________|                      |
                    (Planner blocked on Marius)        Blocked (something failed)

• Inbox — raw idea from Marius. Planner's input queue.
• Refining — Planner is actively elaborating the ticket.
• Needs Info — Planner is blocked; open questions posted as a Notion comment for Marius.
• Ready — fully specified, self-contained, safe for autonomous build. Developer's input queue.
• In Progress — Developer is building.
• In Review — PR open, waiting for Marius to review/merge.
• Done — merged.
• Blocked — build failed in a way the agent could not resolve; explanation in a comment.

The ticket spec contract

A ticket is only moved to Ready when its page body contains every section in docs/ticket-template.md. The Developer treats that body as the complete instruction set — it should never have to guess product intent.

Conventions

• One ticket = one PR = one feature branch (task/<Task ID>-<slug>).
• Never push to a Project's default branch directly; always open a PR.
• Documentation is part of the Developer's job, not a separate role: update the project's docs in the same PR as the code.
• When an agent changes a ticket's status, it also leaves a short Notion comment explaining what it did, so Marius has an audit trail.