Skip to content

bikidsx/comp / .agents/skills/new-feature-setup

new-feature-setup

Verified

Use when starting a new feature, Linear ticket, or bugfix in this repo — establishes the branch + worktree + env + DB + dev-server conventions so the work is immediately ready to code without fighting infra. Triggers on "start a new feature", "spin up a worktree", "begin ticket", "new branch".

New Feature Setup (comp monorepo)

Overview

This repo has a lot of infrastructure pre-wired into git worktree add. Use it. Don't reinvent env copying, database setup, or dependency install flows in every new session.

When to Use

  • User says "start a new feature", "spin up a worktree for X", "begin this Linear ticket", "new branch for …"
  • Before running bun install / bun run db:generate manually in a new directory
  • Before copying .env files around by hand

When NOT to Use

  • User is editing an existing worktree (already set up)
  • Infra repair / debugging of the hook itself (read .githooks/README.md instead)

Workflow

1. Create the worktree from origin/main

cd /Users/mariano/code/comp   # must be the MAIN clone, not another worktree
git fetch origin main
git worktree add .worktrees/<short-slug> -b <branch-name> origin/main
  • For Linear tickets, use Linear's suggested branch name (mariano/<ticket-slug>).
  • For infra / chore work, use mariano/<short-descriptive-name> or chore/<topic>.
  • The <short-slug> on the worktree path should match the branch's suffix (it becomes the Postgres DB slug after tr '-' '_').

2. Let the hook do everything else

git worktree add fires the post-checkout hook at .githooks/post-checkout, which runs synchronously:

  1. Creates compdev_<slug> Postgres database (isolated per worktree)
  2. Links .env* files from the main clone (copies the ones with DATABASE_URL, rewriting it to the isolated URL; symlinks the rest so API keys auto-propagate)
  3. Runs bun install, applies Prisma migrations, regenerates clients

Do not run any of these by hand. If the hook logs a failure, diagnose and fix at the source — don't paper over with a manual install.

Skip toggles (rare):

  • SKIP_WORKTREE_DB=1 — share the main comp DB (drift risk; only for read-only worktrees)
  • SKIP_WORKTREE_SETUP=1 — skip install + migrate + generate (for a "just files" worktree)
  • SETUP_WORKTREE_WITH_BUILD=1 — also run bun run build (adds minutes; only when you need the built artifacts)

3. Start the dev server — coordinate with the "active worktree" rule

Trigger.dev's trigger dev CLI cannot be isolated per worktree. Running bun run dev in multiple worktrees stomps on task registration.

  • One active worktree runs bun run dev (full stack with trigger dev).
  • All other worktrees run:
    bun run --filter '@trycompai/app' dev:no-trigger    # Next.js only
    bun run --filter '@trycompai/api' dev:no-trigger    # NestJS only
    
  • Non-active worktrees need a different PORT to avoid collision — add PORT=3001 (or 3334, etc.) to the worktree's .env.local. .env.local is not symlinked and stays per-worktree.
  • When swapping which worktree is active, kill the old full bun run dev first so task registration is clean.

4. Code the feature

Standard repo conventions apply (see AGENTS.md). Highlights:

  • TDD for any non-trivial change (superpowers:test-driven-development)
  • Brainstorm before building new UX (superpowers:brainstorming)
  • Plans + subagent-driven execution for multi-step work
  • Run audit-design-system after any frontend component edit
  • Always run typecheck before declaring a change done (bunx turbo run typecheck --filter=<pkg>)

5. When done, clean up

Use the stale-worktree-cleanup skill when worktrees accumulate. It handles both git worktree remove and dropping the compdev_<slug> database in one pass. Never leave orphan databases — they pile up silently because git has no pre-worktree-remove hook.

Quick Reference

# Spin up a new worktree (does env + DB + install + migrate + generate automatically)
git worktree add .worktrees/<slug> -b mariano/<branch-name> origin/main

# Start dev — ONLY in the worktree you're actively iterating on
cd .worktrees/<slug>
bun run dev

# Start dev in a background worktree (no trigger dev, custom port via .env.local)
echo "PORT=3001" >> apps/app/.env.local
bun run --filter '@trycompai/app' dev:no-trigger

# Clean up when branch is done
# (use the stale-worktree-cleanup skill)

Red Flags

If you catch yourself doing any of these, stop — the hook should have handled it:

  • Running bun install manually in a new worktree
  • cp or ln -s to copy .env files into a worktree
  • Writing a script that "creates a database for my branch"
  • Running bun run db:migrate in a worktree right after creating it
  • Ignoring a failing bun run dev in two worktrees instead of swapping to dev:no-trigger

Common Mistakes

MistakeFix
Creating the worktree from another worktree instead of the main cloneAlways cd to /Users/mariano/code/comp first
Editing .env in a worktree and expecting it to propagateIf it's a symlink, yes; if it's a real copy (has DATABASE_URL), no. Check with ls -la.
Forgetting to bump PORT → two dev servers collidePut PORT=<free-port> in the worktree's .env.local
Running trigger dev in multiple worktreesSwitch to dev:no-trigger in all but one
Not cleaning up → orphan compdev_* databases piling upUse the stale-worktree-cleanup skill regularly
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall