# Bit-Bot-Team 🤖

An autonomous AI development team that works a Notion Kanban backlog. You are the
Product Manager; the AI plans and builds.

## How it works

```
        YOU (Product Manager)
              │  drop raw ideas into the backlog
              ▼
   ┌──────────────────────┐
   │  Notion: Bit-Bot-Team │   ← single source of truth (Projects + Backlog DBs)
   └──────────────────────┘
        │                    ▲
   Inbox│                    │ In Review (PR for you to merge)
        ▼                    │
   ┌─────────┐  Ready   ┌──────────┐
   │ /plan   │ ───────▶ │ /develop │
   │ Planner │          │Developer │
   └─────────┘          └──────────┘
   interactive, you      autonomous,
   answer its questions  runs nightly
```

- **You** drop one-line ideas into the **Inbox** column of the Backlog.
- **`/plan` (Planner)** — run it during the day. It elaborates each Inbox ticket into
  a full spec, inspects the real codebase, and asks you whatever it needs. Tickets it
  can fully specify become **Ready**; ones with open questions become **Needs Info**.
- **`/develop` (Developer)** — runs autonomously (e.g. nightly). It takes the top
  **Ready** ticket, builds it on a branch, writes tests, updates docs, opens a PR, and
  moves the ticket to **In Review** for you to merge.

## Setup (one time)

1. **Create a project folder.** For each app, create `~/Github/ProjectName` containing:
   - All source code
   - `docs/` — readme, architecture, setup instructions
   - Tests, build config, package.json (or equivalent)
   - Anything else the Developer needs to work on it

2. **Add your projects to Notion.** In the **Projects** database, add a row per app:
   - `Repo` = `~/Github/ProjectName` (the local path)
   - `Default Branch` = `main` (or your branch)
   - `Tech Stack` = languages, frameworks, key tools (e.g. "Node.js 18, React, Jest")
   - `Description` = what this app is
   - `Status = Active`

3. **Verify git + gh.** The Developer runs on your Mac and uses `git` + `gh` locally.
   Ensure both are authenticated for your repos.

4. That's it — the Notion databases and agent commands are ready to go.

## Daily loop

1. Add ideas to the **Inbox** (just a title is enough to start).
2. Run **`/plan`** — answer its questions; watch tickets move to **Ready** or
   **Needs Info**.
3. Let **`/develop`** run (manually or scheduled). Review the PRs it opens.
4. Merge → move the ticket to **Done**.

## Local-first iteration

**For now:** Run `/develop` manually on your Mac, or use `/loop` to cycle through
tickets while your machine is awake. All development happens locally on your
machine — quick feedback, instant debugging, full control.

> The Developer builds **one ticket per run** by default, so each PR stays small and
> reviewable. Bump the count via the command argument if you want more per run.

### Auto Commit mode (for quick iteration)

By default, the Developer opens a PR for each ticket (so you can review before merging).
If you want to iterate faster during experiments, check the **Auto Commit** box on a
Project to make the Developer commit and push directly to the default branch instead.
This skips the PR step — use it only for projects you're actively experimenting with.

To toggle: go to the **Projects** database, find your project, check/uncheck **Auto Commit**.

## Later: Cloud migration

Once you've validated the system (proven that Planner specs are good, Developer PRs
are solid, the workflow scales), migrate to cloud infrastructure:
- Move all `~/Github/ProjectName` repos to GitHub (if not already there).
- Switch to cloud agents via `/schedule` for true nightly autonomy.
- Cloud agents get the same dev flow — just running in the cloud instead of locally.

No changes needed to Notion, the tickets, or the agent logic — just the deployment
target.

## Files

| Path | What |
|---|---|
| `CLAUDE.md` | Shared context: board IDs, status workflow, conventions |
| `docs/ticket-template.md` | The Planner→Developer spec contract |
| `.claude/commands/plan.md` | The `/plan` Planner command |
| `.claude/commands/develop.md` | The `/develop` Developer command |

## Why not KaibanJS?

KaibanJS is a JS *framework* for building agent pipelines from scratch — its "kanban"
is internal agent state, not a backlog you manage. This setup reuses tools you already
have (Notion + Claude Code + GitHub) to get the same outcome with far less to build
and maintain.