diff --git a/.githooks/pre-commit b/.githooks/pre-commit index fe37fbe1..24d9c2cb 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Pre-commit hook — enforces Starfire codebase conventions. +# Pre-commit hook — enforces Molecule AI codebase conventions. # Install: git config core.hooksPath .githooks # # Checks run ONLY on staged files to keep commits fast. diff --git a/HANDOFF.md b/HANDOFF.md new file mode 100644 index 00000000..1c4e7a09 --- /dev/null +++ b/HANDOFF.md @@ -0,0 +1,176 @@ +# Handoff to fresh Claude Code session — Molecule AI / `molecule-monorepo` + +You're picking up where the previous session left off. The project just rebranded from "Starfire" (public hackathon repo) to "Molecule AI" (private commercial repo at `github.com/Molecule-AI/molecule-monorepo`). This handoff is the previous session's accumulated context — memory entries, operational rules, and current state. + +--- + +## 1. Who the user is + +- **Hongming Wang** — solo founder + automation engineer at a Vancouver renovation business (Reno Stars). Two GitHub accounts: `HongmingWang-Rabbit` (main) and `airenostars` (Reno Stars business). Same person. +- **Working style:** terse, direct. Wants you to get to the point. Doesn't like filler. Will tell you when you're being too cautious. +- **Dual hat:** founder of Molecule AI (this product) + customer of Molecule AI (uses `org-templates/molecule-dev/` and `org-templates/reno-stars/` to dogfood his own product against his renovation business). The reno-stars template = real revenue work. Treat with care. + +--- + +## 2. Project state right now (2026-04-13) + +### Repo identity +- **Public hackathon repo (frozen):** `github.com/ZhanlinCui/Starfire-AgentTeam` — BSL 1.1, still public, NOT archived yet. Will likely be archived once the new repo is fully validated. +- **New private commercial repo:** `github.com/Molecule-AI/molecule-monorepo` +- **Local path:** `/Users/hongming/Documents/GitHub/molecule-monorepo` +- **License:** BSL 1.1, Licensor "Molecule AI", auto-converts to Apache 2.0 on 2029-01-01. Additional Use Grant prohibits competing products in the "organizational control plane for heterogeneous AI agent teams" space. + +### Brand mapping (already done — do NOT redo) +| Old | New | +|---|---| +| `Starfire` / `starfire` / `STARFIRE` | `Molecule AI` / `molecule` / `MOLECULE` | +| `Agent Molecule` / `agent-molecule` | `Molecule AI` / `molecule` | +| `agent_molecule_status.py` | `molecule_ai_status.py` | +| `org-templates/starfire-dev/` | `org-templates/molecule-dev/` | +| `org-templates/starfire-worker-gemini/` | `org-templates/molecule-worker-gemini/` | +| `plugins/starfire-dev/` | `plugins/molecule-dev/` | +| `sdk/python/starfire_plugin/` | `sdk/python/molecule_plugin/` | +| `sdk/python/starfire_agent/` | `sdk/python/molecule_agent/` | +| Go module: `github.com/agent-molecule/platform` | `github.com/Molecule-AI/molecule-monorepo/platform` | +| MCP package: `@starfire/mcp-server`, binary `starfire-mcp` | `@molecule-ai/mcp-server`, binary `molecule-mcp` | +| Postgres DB: `agentmolecule` | `molecule` | +| Env vars: `STARFIRE_*` | `MOLECULE_*` (full rename, NO backward-compat shim) | + +**One name preserved intentionally:** `starfire-test-plugin` — that's a real external GitHub repo (`HongmingWang-Rabbit/starfire-test-plugin`) used to validate the github:// plugin install path. Do NOT rename references to it. + +### Verified green on the new repo (last verified ~30 min before this handoff) +- `cd platform && go test -race -count=1 ./...` — all packages +- `cd workspace-template && python3 -m pytest` — **1129 passed, 9 skipped, 2 xfailed** +- `cd sdk/python && python3 -m pytest` — **132 passed** +- `cd canvas && npm test -- --run` — **352 passed (18 files)** +- `cd canvas && npm run build` — clean +- `cd mcp-server && npm run build` — clean +- Platform server boots, `/health` returns `{"status":"ok"}` + +### Docker images +6 of 8 rebuilt fresh against the new repo: `workspace-template:base`, `:claude-code`, `:langgraph`, `:deepagents`, `:autogen`, `:hermes`. **`openclaw` and `crewai` may still be building when you start** — check `tail /tmp/molecule-build.log` and `docker images | grep workspace-template` to confirm. They're heavy (3-5 GB each, 5+ min builds). + +### Infra +- Old `starfire-agentteam-*` containers were stopped during migration. +- New infra is running: `docker compose -f docker-compose.infra.yml ps` should show postgres / redis / langfuse all healthy. +- All 21 migrations applied to the fresh `molecule` DB. +- DB has zero workspaces and zero secrets — fresh start. + +### Open PRs / issues +- **Open PRs on new repo:** 0 (just initial commit) +- **Open issues:** 0 +- **Open PRs on old public repo:** 0 (all resolved before migration) + +--- + +## 3. How the user works with you (the CEO's standing rules) + +These are accumulated feedback memories from prior sessions — read all of them, they're load-bearing. + +### Git workflow +- **Never push directly to `main`.** Always create a `feat/...`, `fix/...`, `chore/...` branch and PR. (One exception during the migration: the user explicitly OK'd direct pushes to the old repo's main for the housekeeping commits because we were about to leave that repo.) +- **Merge with `--merge` only.** Never `--squash`, never `--rebase`. Preserves commit attribution. +- **You MAY merge PRs autonomously** if you personally verified all of: (1) CI green, (2) line-level review clean, (3) design-philosophy fit, (4) security review clean, (5) actual full tests run by you (not "tests exist" — "I ran them just now and they passed"). Wait for CEO approval ONLY for noteworthy cases: ambiguous design call, irreversible migration, large blast radius, anything touching auth/billing/data deletion. +- **Never commit without explicit user approval** (separate from merge — refers to authoring commits in the working tree). +- **Loop "skip" must comment.** If hourly maintenance (the `/loop` skill) skips a PR, the FIRST skip per session must leave a PR comment with the specific blocker. Silent skips strand PRs indefinitely. + +### Testing discipline +- **Manual browser/E2E testing required**, not optional. Unit tests + green CI ≠ working feature. Use Chrome MCP (`mcp__claude-in-chrome__*`) or Playwright (canvas/playwright.config.ts is set up) for any UI-touching change. If both are unavailable, **STOP and report** — don't claim it's verified. +- **E2E tests must verify data flow**, not just UI structure. "Button exists" passes when the feature is broken. Test: create real data → wait → verify content renders. +- **Test long-lived state.** If a feature spawns a goroutine in a CRUD handler, write a test that triggers the spawn, cancels the spawning request context, then asserts the goroutine is STILL alive. Don't pass `c.Request.Context()` to long-lived goroutines. +- **Reload + restart before reporting "done."** After ANY platform Go change or canvas TypeScript change: rebuild → kill old → start new → manually verify on the running service. Telling the user "done" with a stale binary running has happened repeatedly and is unacceptable. + +### Architecture / philosophy +- **Multi-agent**, not single-agent. Per-workspace isolation. A2A for sibling communication. Memory as files. Runtime-agnostic plugins. Hierarchy-based access control (CanCommunicate in `registry/access.go`). +- **Always delegate through PM.** Never bypass hierarchy by sending A2A directly to Frontend Engineer / QA / Dev Lead. CEO → PM → team. This is the platform's value proposition; bypassing PM defeats the point. +- **Only PM mounts the repo.** PM gets `workspace_dir` bind-mount; all other agents get isolated Docker named volumes for `/workspace`. Don't set the global `WORKSPACE_DIR` env var. +- **Cross-reference new docs.** When adding a top-level doc under `docs/`, wire it into `PLAN.md` + `README.md` (+ `README.zh-CN.md` mirror) + `CLAUDE.md`. A doc not linked from those three is invisible to agents. +- **No native browser dialogs.** Never use `confirm()`, `alert()`, or `prompt()` in canvas code. Use the `ConfirmDialog` component at `canvas/src/components/ConfirmDialog.tsx`. + +### Operational discipline +- **Check provisioning failures.** If a workspace is stuck in "provisioning" >30s, run `docker logs ws-` and diagnose. Never report "still provisioning, will be online shortly" without verifying. +- **Monitor infra while team works.** When agents are delegated work, your job is infra monitoring (heartbeats, delegation chains, container health, activity logs) — not micromanaging their implementation. +- **Report monitoring findings.** Don't run silent background loops. After each check: brief summary. Even "13/13 online, no issues" is fine. Never `run_in_background` and forget. +- **Coordinate with PM.** Before significant work: A2A check-in with PM. After completing: share results so PM can update backlog and inform the team. +- **`.awareness/` is gitignored.** Local agent state, never tracked. Already covered by `.gitignore`. If you ever see `git ls-files .awareness/` return rows, `git rm --cached -r .awareness/` and commit. + +--- + +## 4. Operator PII situation (read this before doing anything with reno-stars) + +The `org-templates/reno-stars/` template was scrubbed of PII just before migration. Real values were replaced with env-var references: + +| Var | What it is | +|---|---| +| `OPERATOR_EMAIL` | Operator's contact email | +| `OPERATOR_PHONE` | Display only | +| `OPERATOR_TELEGRAM_ID` | Numeric Telegram user ID | +| `GADS_MCC_ID` | Google Ads MCC account | +| `GADS_CUSTOMER_ID` | Google Ads child account | +| `GCP_PROJECT_ID` | GCP project | +| `GSC_SERVICE_ACCOUNT` | Search Console reporter service account email | + +The user must set these as **global_secrets** via the canvas, API (`PUT /settings/secrets`), or MCP (`mcp__starfire__set_global_secret`) for the reno-stars org to work. The platform auto-injects every global_secret as a container env var. See `org-templates/reno-stars/OPERATOR_NOTES.md` for instructions. + +--- + +## 5. Things that are NOT done yet (what the user might ask you about next) + +1. **Set operator global_secrets in the new platform.** DB is fresh — zero secrets. Reno-stars won't function until these are populated. The values exist in the user's head / old DB / `org-templates/molecule-worker-gemini/.env`. +2. **Switch live Reno Stars business deployment to point at the new repo + new infra.** Old infra was stopped during migration. If the business automations were running there, they're down right now until you redeploy from the new repo. +3. **Archive the old public repo.** Up to the user when. Recommendation: leave public, archive with a "see new repo" notice once new repo is fully validated. +4. **Consider extracting a sanitized "Renovation Business" reference template** at `org-templates/examples/renovation-saas/` as a customer-facing starter kit. Optional product play discussed but not built. +5. **`openclaw` + `crewai` Docker images may still be rebuilding** — check status when you start. +6. **No CI configured yet on the new repo.** The old repo's GitHub Actions workflows should have copied over (`.github/workflows/`), but they reference the old repo URL in some places. Worth a quick audit. +7. **The `MEMORY.md` index in the previous session's auto-memory** lives at `~/.claude/projects/-Users-hongming-Documents-GitHub-Starfire-AgentTeam/memory/`. The new session under `~/.claude/projects/-Users-hongming-Documents-GitHub-molecule-monorepo/` will start fresh. Worth re-saving the load-bearing rules from §3 above as memory entries in the new project. + +--- + +## 6. Useful commands / paths in the new repo + +```bash +# Local repo +cd /Users/hongming/Documents/GitHub/molecule-monorepo + +# Build + test sweep +cd platform && go build ./... && go test -race ./... +cd workspace-template && python3 -m pytest -q +cd sdk/python && python3 -m pytest -q +cd canvas && npm test -- --run && npm run build +cd mcp-server && npm run build +bash workspace-template/build-all.sh # rebuild Docker images + +# Infra +bash infra/scripts/setup.sh # postgres + redis + langfuse + migrations +bash infra/scripts/nuke.sh # tear down (warn user — wipes volumes) + +# Run platform locally +cd platform && go run ./cmd/server # port 8080 + +# Run canvas +cd canvas && npm run dev # port 3000 + +# Health check +curl http://localhost:8080/health +``` + +--- + +## 7. The hourly maintenance loop (`/loop`) + +The previous session was running an hourly PR-triage + issue-pickup loop. The cron job (`63a71b1f`) was session-only and died when that session ended. If the user wants it on the new repo, they'll re-invoke `/loop` with the same prompt. + +The loop's full prompt is preserved in the conversation history. Key discipline rules baked in: +- STEP 0.5 ambiguity: when blocked, always **comment on the PR before skipping** (memory: `feedback_loop_skip_must_comment.md`) +- Use verified-merge (memory: `feedback_no_merge_pr.md`) — don't bottleneck on CEO approval if all 5 verification boxes are ticked +- Merge-commit only (memory: `feedback_merge_commits.md`) + +--- + +## 8. Recommended first 5 minutes when you start + +1. `cd /Users/hongming/Documents/GitHub/molecule-monorepo && git status && git log --oneline -3` — confirm clean state +2. `docker images | grep workspace-template` — confirm 8 fresh images (or report which still need rebuild) +3. `docker compose -f docker-compose.infra.yml ps` — confirm infra healthy +4. `curl -s http://localhost:8080/health` (if platform is running) or skip — platform may not be running unattended +5. Save the load-bearing feedback rules from §3 as memory entries in the new project's memory dir so they persist across sessions in this repo too diff --git a/canvas/public/molecule-icon.png b/canvas/public/molecule-icon.png index 54e53730..9d7ac051 100644 Binary files a/canvas/public/molecule-icon.png and b/canvas/public/molecule-icon.png differ diff --git a/canvas/src/app/icon.png b/canvas/src/app/icon.png index 54e53730..9d7ac051 100644 Binary files a/canvas/src/app/icon.png and b/canvas/src/app/icon.png differ diff --git a/docs/assets/branding/molecule-icon.png b/docs/assets/branding/molecule-icon.png new file mode 100644 index 00000000..9d7ac051 Binary files /dev/null and b/docs/assets/branding/molecule-icon.png differ diff --git a/docs/assets/branding/molecule-text-black.png b/docs/assets/branding/molecule-text-black.png new file mode 100644 index 00000000..9d7ac051 Binary files /dev/null and b/docs/assets/branding/molecule-text-black.png differ diff --git a/docs/assets/branding/molecule-text-white.png b/docs/assets/branding/molecule-text-white.png new file mode 100644 index 00000000..9d7ac051 Binary files /dev/null and b/docs/assets/branding/molecule-text-white.png differ