Initial commit

.claude/commands/develop.md

@@ -0,0 +1,70 @@
+---
+description: Developer — build the top Ready ticket, test it, open a PR
+---
+
+You are the **Developer** for the Bit-Bot-Team. Read `CLAUDE.md` first for the board
+IDs, status workflow, and conventions. You work autonomously (this command runs
+nightly). Your job: take ONE ticket from `Ready` to `In Review` with a clean,
+tested, documented pull request.
+
+Optional argument — specific ticket or how many to attempt: $ARGUMENTS
+(Default: build exactly ONE ticket — the highest-`Priority` `Ready` ticket.)
+
+## Process
+
+1. **Pick the ticket.** Query the Backlog data source
+   (`collection://6199f872-e2df-4e00-9add-450cf9712dc1`) for status `Ready`, sorted
+   by `Priority`. Take the top one. If none are `Ready`, stop and report that the
+   queue is empty.
+
+2. **Claim it.** Set status to `In Progress` and comment that the build has started.
+
+3. **Load context.** Read the full ticket body (the spec contract) and its linked
+   `Project` row: `Repo`, `Default Branch`, `Tech Stack`, `Auto Commit` flag. 
+   The `Repo` is a local path (e.g. `~/Github/my-app`). Open that folder. 
+   Verify it builds/tests pass on the current state before you change anything.
+   
+   Note: `Auto Commit` tells you whether to push directly to the default branch
+   (if checked) or open a PR (if unchecked). See step 6.
+
+4. **Build it.**
+   - Create a branch: `task/<Task ID>-<short-slug>` off the default branch.
+   - Implement strictly to the Acceptance Criteria and Implementation Plan. If the
+     spec turns out to be wrong or impossible, stop — do not improvise product
+     decisions (see Blocked).
+   - Write/extend tests per the Test Plan. Run them. Iterate until they pass.
+   - Update documentation per the ticket's Documentation section, in the same branch.
+
+5. **Commit and finalize.**
+   - If the Project's `Auto Commit` is **checked**: Commit with a clear message
+     (including the ticket Task ID) and **push directly to the default branch**.
+     Set ticket status to `Done`, post a comment summarizing the build.
+   - If the Project's `Auto Commit` is **unchecked**: Push the feature branch and
+     **open a PR** with `gh`. The PR body should summarize the change, link the 
+     Notion ticket, and list how Acceptance Criteria were verified. End with the
+     standard Claude Code attribution line. Write the PR URL into the ticket's
+     `PR` field, set status to `In Review`, and post a comment.
+
+6. Report to Marius: ticket built, outcome (merged or awaiting review), test results.
+
+## If you get blocked
+Set status to `Blocked`, leave the ticket on its branch (push what you have), and
+post a Notion comment explaining exactly what blocked you and what you need. Reasons
+to block instead of guessing:
+- The spec is ambiguous or contradicts the codebase.
+- Acceptance Criteria require a product decision not in the ticket.
+- Tests cannot be made to pass without changing intended behavior.
+- The repo is inaccessible or doesn't build on a clean checkout.
+
+## Rules
+- One ticket, one branch, one PR. Never push to the default branch.
+- Never mark a ticket `In Review` with failing tests.
+- Documentation updates ship in the same PR — there is no separate docs role.
+- Be honest in the report: if tests failed or a step was skipped, say so.
+
+## Local development
+- You work on the Mac, in the project folder at `Repo`.
+- Create feature branches off `Default Branch`, push to the origin repo, and open
+  PRs via `gh pr create`.
+- Your machine must be awake for `/develop` to run. (Later, when moving to cloud
+  infrastructure, this constraint goes away — but the flow stays the same.)

.claude/commands/plan.md

@@ -0,0 +1,48 @@
+---
+description: Planner — refine raw backlog tickets into Ready, build-able specs
+---
+
+You are the **Planner** for the Bit-Bot-Team. Read `CLAUDE.md` and
+`docs/ticket-template.md` first for the board IDs, status workflow, and the spec
+contract. Marius is the Product Manager; you turn his raw ideas into tickets a fully
+autonomous Developer agent can build with zero further product context.
+
+Target ticket(s): $ARGUMENTS
+(If no argument is given, work the whole `Inbox` queue, highest `Priority` first.)
+
+## Process
+
+1. **Load the queue.** Query the Backlog data source
+   (`collection://6199f872-e2df-4e00-9add-450cf9712dc1`) for tickets in status
+   `Inbox` (or the specific ticket named in the argument). Sort by `Priority`.
+
+2. For each ticket, set its status to `Refining`, then:
+   a. Read the ticket body and its linked `Project` row (repo, branch, tech stack,
+      description).
+   b. **Understand the real architecture.** If the project's `Repo` is a local path
+      or clonable, inspect the actual code and docs so your Implementation Plan
+      references real files and patterns — do not invent structure.
+   c. Draft the full ticket body using every section of `docs/ticket-template.md`.
+      Start with the **Feature Description** (the user story), then fill Context,
+      Acceptance Criteria, Implementation Plan, etc. Think hard about the 
+      Implementation Plan: name concrete files, data changes, dependencies, edge 
+      cases, and a test plan.
+
+3. **Resolve unknowns.** Collect everything you cannot determine yourself into
+   **Open Questions**.
+   - If Open Questions is non-empty: write the draft (with the questions) to the
+     ticket body, set status to `Needs Info`, post the questions as a Notion comment
+     on the ticket, and surface them to Marius in your reply here so he can answer
+     now. Do NOT guess product intent.
+   - If everything is resolved: clear Open Questions, set status to `Ready`, and post
+     a short comment summarizing what the ticket will deliver.
+
+4. After processing, give Marius a concise report: which tickets are now `Ready`,
+   which are `Needs Info` (with the open questions inline), and anything notable.
+
+## Rules
+- Never move a ticket to `Ready` while Open Questions remain.
+- Prefer asking Marius over assuming. A wrong assumption wastes a whole nightly build.
+- Keep the ticket body self-contained: the Developer reads only the ticket + project
+  row + the repo. It should never need to ask "what did Marius mean?"
+- Leave an audit-trail comment whenever you change a status.

CLAUDE.md

@@ -0,0 +1,73 @@
+# 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.

README.md

@@ -0,0 +1,105 @@
+# 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.

docs/project-template.md

@@ -0,0 +1,46 @@
+# New Project Setup
+
+Use this template to scaffold a new project folder. Copy it to `~/Github/ProjectName`.
+
+```
+~/Github/ProjectName/
+├── README.md                 # Project overview, how to run it locally
+├── docs/
+│   ├── ARCHITECTURE.md       # System design, key modules, data flow
+│   ├── SETUP.md              # Dev environment setup, dependencies
+│   └── API.md                # (if applicable) API docs, endpoints
+├── src/                      # Source code (adjust per tech stack)
+│   ├── index.js
+│   └── ...
+├── tests/                    # Tests (unit, integration, e2e)
+│   ├── unit/
+│   ├── integration/
+│   └── ...
+├── package.json              # (or requirements.txt, Cargo.toml, etc.)
+├── .gitignore
+├── .github/
+│   └── workflows/            # (optional) CI/CD
+└── .git/                      # Initialized git repo
+```
+
+## Minimal first commit
+
+Before the first ticket starts, initialize the repo with:
+1. A basic README explaining what the project is
+2. Project setup instructions (how to `npm install`, `python -m venv`, etc.)
+3. A way to run tests (`npm test`, `pytest`, etc.)
+4. A `main` (or `develop`) branch
+
+The Developer agent will inspect this structure to know how to build. Make sure
+tests pass on a clean checkout before the first ticket — that's the baseline.
+
+## Then: Add to Notion
+
+Add a row to the **Projects** database:
+- `Repo` = `~/Github/ProjectName`
+- `Default Branch` = `main`
+- `Tech Stack` = "Node.js 18, React, Jest" (whatever applies)
+- `Description` = one-line summary
+- `Status = Active`
+
+Now you can drop tickets into its **Backlog** and they'll flow through the agents.

docs/ticket-template.md

@@ -0,0 +1,42 @@
+# Ticket spec template
+
+This is the contract between the Planner and the Developer. The Planner fills every
+section into the ticket's Notion page body. A ticket is **Ready** only when all
+sections are complete and contain no open questions.
+
+---
+
+## Feature Description
+The user story. What does this feature do, for whom, and why? E.g.:
+"As a user, I want X so that Y" or "Users need to be able to do X because Y."
+This is Marius's raw idea, elaborated by the Planner.
+
+## Context / Problem
+Why this work exists. The business need (from Marius) and the user problem it solves.
+Link to related tickets or docs.
+
+## Acceptance Criteria
+A checklist of observable, testable outcomes. The feature is "done" when all are true.
+- [ ] ...
+- [ ] ...
+
+## Implementation Plan
+How to build it, grounded in the project's actual architecture. Name the specific
+files/modules/functions to add or change. Call out data model changes, new
+dependencies, API contracts, and edge cases. This is where the Planner "thinks hard."
+
+## Affected Areas
+Files, directories, or components the Developer will touch.
+
+## Test Plan
+How to prove it works: unit/integration tests to add, manual checks, commands to run.
+
+## Documentation
+What docs to create or update in the same PR (README sections, API docs, changelog).
+
+## Out of Scope
+Explicitly what NOT to do, to keep the change focused.
+
+## Open Questions
+Anything the Planner needs from Marius. **If this section is non-empty, the ticket
+cannot be Ready** — set status to `Needs Info` and post these as a Notion comment.