# 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](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.