BloxClips project map

Repositories

Repository	Base	Responsibility	Typical verification
Bloxclips-backend	dev	API, Prisma, funding, payouts, authorization, scheduling	package-defined tests, integration tests, typecheck/build, Prisma validation
BloxClips-frontend	dev	Next.js UI and Whop embed	package-defined tests, lint, typecheck/build
metric-scraper	main	Crawlee queue consumer and platform extraction	pnpm test, pnpm typecheck, pnpm build; tracking fixture provenance when applicable

Repository scripts remain authoritative. The doctor and gate scripts discover the package manager and available scripts instead of assuming all commands exist.

Helper aliases for Treehouse leases: backend -> Bloxclips-backend/, frontend -> BloxClips-frontend/, metric-scraper -> metric-scraper/. Base refs are origin/dev, origin/dev, and origin/main respectively.

Repository skills and the compact workspace router replace historical outer architecture as the active navigation path. After acquisition attach shared skill context with treehouse-bloxclips context ALIAS --task TASK.

Roles

• Primary planner: owns decomposition, architecture, financial/security decisions, sequencing, and final synthesis.
• Researcher: read-only fact finding.
• Worker: one packet, one repository, and one Treehouse lease. The worker edits, tests, and commits only inside the leased worktree, never in a primary checkout and never in an ad-hoc worktree.
• Reviewer: independent read-only diff review.
• Human: authorizes scope changes, merges, deployment, production changes, invoices, and payouts.

Workflow

1. Run focused local ./scripts/bloxclips-status --compact (or --write for a saved snapshot). Cached tracking refs are not live freshness.
2. Resolve collisions with dirty worktrees, existing PRs, and in-progress issues.
3. Create a packet with ./scripts/bloxclips-task new <id> <repo> <slug>.
4. Fill every required field and validate it with ./scripts/bloxclips-task check <file>.
5. Acquire a Treehouse lease with ./scripts/treehouse-bloxclips acquire <backend|frontend|metric-scraper> --task <packet-id> (one lease per task packet; concurrent tasks on the same repository each pass their own --task and get different worktrees/branches) and verify containment. All edits, tests, and commits happen inside the leased worktree; never create an ad-hoc worktree (bloxclips-worktree create is disabled) and never edit a primary checkout.
6. Give the worker only the packet and relevant repository context.
7. Run ./scripts/bloxclips-gate <leased-worktree-path> from the Treehouse-leased worktree.
8. Request an independent reviewer.
9. Update the packet handoff. Open a PR when the current task authorizes it; merging still requires explicit authorization.

Cost control

Use a strong model once for decomposition and once for final review. Delegate only packets small enough to verify mechanically. Do not make agents repeatedly rediscover the project: the status snapshot and packet carry the required state. Do not run multiple agents on the same uncertainty. Escalate when architecture or policy is unresolved.