Work Monorepo - Agent Guide

User: Ben Sima (ben.sima@parasail.io)

This directory contains multiple work repositories. When making changes, always specify which repo you’re targeting.

IMPORTANT: Always review code carefully after it has been written.

IMPORTANT: Always include a testing strategy for code.

Pre-Implementation Planning (REQUIRED)

Before writing ANY implementation code for a feature or significant change:

1. Identify code owners. Run git log --oneline -10 <file> on the files you plan to change. If someone other than Ben has been actively working on them, the feature MUST go through planning first.

2. Write a design brief. Create a short document (or Linear comment) covering:

   • What the feature does and why
   • Which files/modules it touches
   • The proposed approach
   • Any alternative approaches considered

3. Get sign-off before implementing. Post the design brief for review by the relevant code owner(s). Do NOT proceed to implementation until there is explicit agreement on the approach.

4. Only then implement. Once the approach is agreed upon, proceed with coding.

This applies to all PRs that touch code owned by other team members. Small bug fixes, doc changes, and changes to Ben’s own code are exempt.

Repository Overview

Quick Commands by Repo

app/ (Next.js)

pnpm dev          # Dev server
pnpm build        # Build
pnpm lint:fix     # Lint + fix
pnpm test         # Run tests

ocr_pipeline/ (Python/FastAPI)

source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload

parasail/ (Go/Bazel)

bazel run //:gazelle   # Update BUILD files
bazel build //...      # Build all
# Proto changes: $(git rev-parse --show-toplevel)/opt/bin/compile_protos

NOTE: Bazel is only used for some projects (Go/Java). For Python we use uv.

sales/ (Monorepo)

task do      # Run all checks
task format  # Format code
task build   # Build api + ui

tts-workflow-demo/ (Python)

uv sync
uv run uvicorn main:app --reload

resemble_inference/ (Docker)

docker build -f docker/Dockerfile -t resm-serve .
docker run --gpus 0 --env RESEMBLE_TOKEN=xxx -p 4999:4999 -t resm-serve

Cross-Repo Patterns

• TTS Services: oai_TTS_sidecar/, resemble_inference/, tts-workflow-demo/ share similar API patterns
• GitOps: dev1-sakura/ and saas-sakura/ are Flux-managed K8s configs
• Bazel repos: parasail/ and voice-workflow/ use same tooling conventions

Conventions

• Always check repo-specific AGENTS.md files for detailed guidance
• Use absolute paths when referencing files across repos
• When modifying infrastructure (sakura repos), consider both dev and prod
• Always use a patch-based workflow with git-brancheless, prefer 1 commit per PR
• Always use git-branchless commands like git sync, git submit -Fgithub and so on, over standard git commands
• Use the GitHub CLI gh when looking up PRs or comments.

Debugging Production Issues

When a service works locally but fails in production, follow this order:

1. Application logs first. Always check the service’s own logs before investigating infrastructure. Most issues are visible in startup logs, error logs, or framework diagnostic output (e.g., Spring Boot condition evaluation reports, Python tracebacks). Use kubectl logs, docker logs, or equivalent.

2. Verify the running artifact. Confirm the deployed image/version matches what you expect. Stale pods, failed rollouts, and cached images are common. Check kubectl get deploy -o jsonpath='{.spec.template.spec.containers[0].image}'.

3. Reproduce with the same artifact. If it works locally with source but fails in prod, try running the actual Docker image locally. Differences in base images, native dependencies, and environment variables are common root causes.

4. Don’t chase infrastructure until you’ve ruled out the application. Traefik routes, Helm values, secrets, and DNS are important but are rarely the cause when the service itself is returning application-level errors (e.g., Spring “No static resource”, Python 500s). An application-level 404 means the request reached the app — the problem is inside it.

5. Know your framework’s diagnostic tools. Spring Boot: --debug flag or CONDITIONS_EVALUATION_REPORT shows which beans and conditions failed. FastAPI/Uvicorn: startup logs show registered routes. Next.js: build output shows compiled routes.

6. Flag known anti-patterns when you see them in code. Don’t just note them — call them out as likely root causes. Examples: Spring @ConditionalOnBean on component-scanned classes (ordering not guaranteed), Python circular imports, missing native dependencies in minimal Docker images.

Task Management

• Use the linear CLI for issue/project tracking and updates
• Run linear --help to discover subcommands

Example: locate the livekit-parasail plugin issue and open it:

linear issue list --all-states --limit 0 --no-pager | rg -i "livekit|parasail"
linear issue view ENG-177

Multi-Agent / Subagent Usage

Use subagents for context-consuming tasks: researching a codebase, implementing well-specified tasks, reviewing code.

Pi supports RPC mode (pi --mode rpc --no-session) for programmatic orchestration via JSON-lines over stdin/stdout. See pi --help for details.

Available Parasail Models: