docs initial
This commit is contained in:
Daniil
@@ -0,0 +1,17 @@
|
||||
# Turbopack Dev Server Hang — @vidstack/react + Barrel Circular Import
|
||||
|
||||
**Applies when:** Next.js dev server hangs (290%+ CPU, 1GB+ RAM, no HTTP responses), or Turbopack enters infinite recompilation
|
||||
|
||||
Three contributing factors found:
|
||||
|
||||
1. **Barrel self-import in features/project**: `SubtitleRevisionStep.tsx` imports `TranscriptionEditor` from the barrel `@features/project` which re-exports `SubtitleRevisionStep` itself, creating a circular module evaluation chain. Fix: use direct subpath import.
|
||||
|
||||
2. **FSD violation features->widgets**: `SubtitleRevisionStep` imports `TimelinePanel` from `@widgets/`, violating FSD layer direction. Not a direct cause of hang but exacerbates module graph complexity.
|
||||
|
||||
3. **@vidstack/react internal dynamic imports**: The library uses 14+ dynamic `import()` calls internally. Combined with Turbopack's inability to create shared chunks between async chunks in dev mode (GitHub issue vercel/next.js#85119), this can cause pathological module duplication during HMR.
|
||||
|
||||
**Reproduction**: Issue is intermittent — most reliably triggered when editing files that import from `@vidstack/react` while the browser has the project wizard page open. Fresh server starts work fine.
|
||||
|
||||
**Quick fix**: Change `SubtitleRevisionStep.tsx` line 23 from `import { TranscriptionEditor } from "@features/project"` to `import { TranscriptionEditor } from "@features/project/TranscriptionEditor"`.
|
||||
|
||||
**Long-term**: Consider upgrading to Next.js 16.2+ which includes 200+ Turbopack fixes.
|
||||
@@ -0,0 +1,9 @@
|
||||
# oven/bun Base Image Has Existing Non-Root User
|
||||
|
||||
**Applies when:** adding non-root user to any Dockerfile that uses `oven/bun` as base image (Remotion service, or future Bun-based services).
|
||||
|
||||
- `oven/bun:1.3.10` ships with a `bun` user (UID 1000) and `bun` group (GID 1000).
|
||||
- Home directory is `/home/bun`, shell is `/bin/sh`.
|
||||
- Do NOT create a new `app` user with `groupadd`/`useradd` -- GID 1000 collision causes `groupadd: GID '1000' already exists` build failure.
|
||||
- Instead: `RUN chown -R bun:bun /app` then `USER bun`.
|
||||
- Verified: container runs as `uid=1000(bun) gid=1000(bun)`, `/app/out` is writable.
|
||||
@@ -0,0 +1,9 @@
|
||||
# cap_drop: ALL Breaks redis-alpine Startup
|
||||
|
||||
**Applies when:** adding Linux capability restrictions to Docker Compose services, especially Redis or any image that switches users at startup.
|
||||
|
||||
- `redis:7-alpine` entrypoint calls `gosu redis` to drop from root to the `redis` user.
|
||||
- `gosu` requires `SETUID` and `SETGID` capabilities to switch users.
|
||||
- `cap_drop: ALL` without `cap_add: [SETUID, SETGID]` prevents the user switch, causing immediate container exit.
|
||||
- The container logs show no error -- it just exits silently with code 1.
|
||||
- Decision (2026-03-24): removed all cap_drop/cap_add from both compose files. For a dev-only local stack, the complexity and debugging cost outweigh the security benefit. Revisit for production deployment with proper per-service capability analysis.
|
||||
@@ -0,0 +1,18 @@
|
||||
# Docker Infrastructure Audit Findings
|
||||
|
||||
**Applies when:** implementing any Docker fixes, setting up CI/CD, preparing for production deployment, or reviewing PRs that touch Dockerfiles or compose files.
|
||||
|
||||
- Backend `.dockerignore` is missing `.env` exclusion -- security risk for future `COPY . .` changes.
|
||||
- Backend `.gitignore` is missing `.env` exclusion -- latent secret leak risk.
|
||||
- MinIO image is unpinned (`minio/minio` with no tag) -- all others are pinned.
|
||||
- No resource limits on any service. Remotion needs 4GB+ for Chromium/FFmpeg renders.
|
||||
- Health checks exist only on `db` and `redis`. Missing on `minio`, `api`, `worker`, `remotion`.
|
||||
- API health check requires a `GET /api/health/` endpoint (may not exist yet -- needs backend team).
|
||||
- No restart policies on any service.
|
||||
- Both Dockerfiles run as root -- non-root user should be added to `prod` stages (dev stage has bind-mount permission complications).
|
||||
- `build-essential` is in the `base` stage, bloating the prod image by ~200MB. Move to `deps` stage only.
|
||||
- Remotion Dockerfile missing BuildKit apt cache mounts (backend has them, remotion does not).
|
||||
- Environment variables duplicated between `api` and `worker` (14 identical vars) -- use `x-backend-env` YAML anchor.
|
||||
- Worker is missing `JWT_SECRET_KEY` that API has.
|
||||
- No CI/CD pipeline exists at all -- zero automation.
|
||||
- No frontend Dockerfile -- needs `output: 'standalone'` in next.config.mjs first.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Docker Dev vs Prod Stage Split
|
||||
|
||||
**Applies when:** modifying the backend Dockerfile or docker-compose.yml, debugging import issues in containers, or setting up CI/CD image builds.
|
||||
|
||||
- Dockerfile has 4 stages: `base` (runtime only: ffmpeg) -> `deps` (build-essential + Python deps) -> `dev` (compose target) -> `prod` (CI/CD target).
|
||||
- `base` has only runtime deps (ffmpeg). `deps` adds build-essential for C extension compilation (psycopg2, etc.).
|
||||
- `dev` inherits from `deps` (has build-essential -- fine for dev). `prod` inherits from `base` (no build-essential) and copies the pre-compiled `.venv` from `deps` via `COPY --from=deps /app/.venv /app/.venv`.
|
||||
- The `dev` stage does NOT run `uv sync` for the project itself. It relies on `PYTHONPATH=/app` + bind-mounted source at `/app/cpv3`. This avoids the stale editable-install-vs-bind-mount conflict.
|
||||
- The `prod` stage uses `UV_LINK_MODE=copy` and `uv sync --frozen --no-dev` to create a fully self-contained image with code baked in.
|
||||
- `prod` stage runs as non-root user `app` (uid/gid 1000). Dev stage stays as root due to bind-mount permission complications.
|
||||
- `docker-compose.yml` targets the `dev` stage via `build.target: dev`.
|
||||
- For CI/CD, build the `prod` stage: `docker build --target prod -t cpv3-backend:prod .`
|
||||
- The `cpv3` project is declared as `source = { editable = "." }` in `uv.lock`. With `UV_LINK_MODE=copy`, uv creates a `.pth` editable finder that maps imports to `/app/cpv3`. In dev, the bind mount overlays this directory, making the installed copy irrelevant but not harmful. The `dev` stage eliminates this ambiguity entirely.
|
||||
- `watchfiles` CLI (from `uvicorn[standard]`) is used for worker auto-restart: `watchfiles --filter python 'dramatiq ...' /app/cpv3`.
|
||||
- OrbStack propagates filesystem events natively. Docker Desktop on macOS may need `WATCHFILES_FORCE_POLLING=true`.
|
||||
- Worker REMOTION_SERVICE_URL was fixed from `http://localhost:8001` to `http://remotion:3001`.
|
||||
@@ -0,0 +1,11 @@
|
||||
# MinIO Version Pinning and xl Meta Compatibility
|
||||
|
||||
**Applies when:** changing MinIO image tag, debugging MinIO startup failures, or resetting MinIO volumes.
|
||||
|
||||
- MinIO does NOT support downgrades. Once data is written by a newer version, older versions cannot read it.
|
||||
- The xl meta version is a storage format version embedded in MinIO's data files. Version 3 was introduced in 2025 releases.
|
||||
- Previous pin `RELEASE.2024-11-07T00-52-20Z` could not read xl meta v3 data written by a `latest` pull.
|
||||
- Current pin: `RELEASE.2025-09-07T16-13-09Z` -- the last free release on Docker Hub before MinIO stopped publishing (Oct 2025).
|
||||
- `curl` was removed from MinIO Docker images after `RELEASE.2023-10-25T06-33-25Z` (UBI micro base). Healthcheck must use `mc ready local` instead of `curl -f`.
|
||||
- If MinIO volume data is truly unrecoverable (corrupted, not just version mismatch), the nuclear option is `docker volume rm cpv3_minio` -- but this destroys all stored media files.
|
||||
- MinIO GitHub repo was archived Feb 2026. Future images may need to come from alternative sources (alpine/minio, self-build).
|
||||
@@ -0,0 +1,11 @@
|
||||
# Network Segmentation in Docker Compose
|
||||
|
||||
**Applies when:** modifying network topology, adding new services, debugging inter-service connectivity, or reviewing compose files.
|
||||
|
||||
- Two custom bridge networks: `db-net` (data stores) and `app-net` (application tier).
|
||||
- `db` and `redis`: only on `db-net` -- not reachable from app-net-only services.
|
||||
- `minio`: on both `db-net` and `app-net` -- accessible from all services including Remotion.
|
||||
- `api` and `worker`: on both `db-net` and `app-net` -- can reach data stores and be reached by Remotion.
|
||||
- Remotion service joins `cofee_backend_app-net` (external network) -- can reach `minio` and `api`/`worker`, but NOT `db` or `redis` directly.
|
||||
- Remotion compose references `REDIS_URL: redis://redis:6379/0` in its environment -- this will NOT resolve since `redis` is only on `db-net`. If Remotion needs Redis access, Redis must be added to `app-net` as well.
|
||||
- The old default network (`cofee_backend_default`) is no longer created. Any external references to it must be updated to `cofee_backend_app-net`.
|
||||
@@ -0,0 +1,22 @@
|
||||
## Decision: Docker infrastructure audit — prioritized remediation plan
|
||||
## Task: Comprehensive audit of all Dockerfiles and docker-compose files for security, performance, and best practices
|
||||
## Agents Involved: DevOps Engineer, Security Auditor (expertise applied from agent definitions)
|
||||
|
||||
## Context
|
||||
User requested full Docker audit. All 6 Docker files examined (2 Dockerfiles, 2 docker-compose.yml, 2 .dockerignore).
|
||||
|
||||
## Key Decisions
|
||||
- Non-root user: MUST add to both Dockerfiles before any production deployment — both confirmed running as uid=0
|
||||
- build-essential: Move to separate builder stage to cut backend image from 1.72GB to ~900MB-1GB
|
||||
- Resource limits: Required on all services, especially Remotion (4GB limit for Chromium+FFmpeg)
|
||||
- Environment anchor: Extract duplicated env vars between api and worker into x-backend-env YAML anchor
|
||||
- Network isolation: Remotion should NOT have direct DB/Redis access — segment into frontend/backend/rendering networks
|
||||
|
||||
## Conflicts Resolved
|
||||
- None (single-perspective audit, no inter-agent conflicts)
|
||||
|
||||
## Context for Future Tasks
|
||||
- Affects: cofee_backend/Dockerfile, cofee_backend/docker-compose.yml, remotion_service/Dockerfile, remotion_service/docker-compose.yml, both .dockerignore files, both .gitignore files
|
||||
- Depends on: Health endpoint implementation (Backend Architect + Remotion Engineer) for H3
|
||||
- Watch for: When implementing health endpoints, ensure they match the healthcheck paths defined in compose (GET /api/health/ for backend, GET /health for remotion)
|
||||
- Watch for: backend .gitignore still missing .env exclusion — fix ASAP
|
||||
@@ -0,0 +1,17 @@
|
||||
# Scroll Lag from backdrop-filter Overuse
|
||||
|
||||
**Applies when:** investigating scroll jank, GPU compositing issues, or paint storms on any page with many Card components
|
||||
|
||||
The /projects page had 73 elements with `backdrop-filter` causing massive GPU compositing on every scroll frame. Each `backdrop-filter: blur()` forces the GPU to sample and blur all pixels behind the element on every frame.
|
||||
|
||||
**Key sources removed:**
|
||||
- `body { background-attachment: fixed }` in global.scss — forces full repaint every scroll frame. Replaced with `body::before` pseudo-element using `position: fixed`.
|
||||
- `Card.module.scss` had `backdrop-filter: blur(16px) saturate(180%)` on every card — replaced with `color-mix()` solid background.
|
||||
- `ProjectCard.module.scss` `.statusBadge` had `backdrop-filter: blur(8px)` — removed.
|
||||
- `ProjectCard.module.scss` `.progressCircle::before` had `backdrop-filter: blur(2px)` — removed.
|
||||
|
||||
**Kept:** Header `backdrop-filter` (single element, important UX). Added `will-change: transform` to promote to own compositing layer.
|
||||
|
||||
**Added:** `content-visibility: auto` on `.projectList > *` to skip rendering off-screen cards.
|
||||
|
||||
**Method:** Element count via Chrome DevTools `$$('[style*=backdrop], *').filter(...)` and Performance panel paint profiling.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Docker Infrastructure Security Audit Findings
|
||||
|
||||
**Applies when:** reviewing Docker configurations, adding new services to docker-compose, creating production deployment configs, or auditing container security.
|
||||
|
||||
## Critical Issues (as of 2026-03-24)
|
||||
- `cofee_backend/.env` is tracked in git (committed in `0299949`). `.gitignore` has no `.env` entry.
|
||||
- `cofee_frontend/.env` is tracked in git (committed in `71b9749`). `.gitignore` only excludes `.env*.local`, not `.env`.
|
||||
- `cofee_backend/.dockerignore` does NOT exclude `.env` — secrets enter Docker build context.
|
||||
- `remotion_service/.gitignore` and `.dockerignore` correctly exclude `.env`.
|
||||
|
||||
## High Issues
|
||||
- Both Dockerfiles (backend + remotion) run as root — no `USER` directive, no `adduser`.
|
||||
- `docker-compose.yml` has hardcoded defaults: `JWT_SECRET_KEY=dev-secret`, `postgres/postgres`, `minioadmin/minioadmin`.
|
||||
- Redis has no authentication (`--requirepass` not set), exposed on host port 6379.
|
||||
- All ports bound to `0.0.0.0` (shorthand format), not `127.0.0.1`.
|
||||
|
||||
## Medium Issues
|
||||
- No network segmentation — all backend services on default bridge network.
|
||||
- No container resource limits (mem_limit, cpus).
|
||||
- No capability dropping (cap_drop: ALL).
|
||||
- MinIO image unpinned (`minio/minio` = latest). Other images pinned by tag, not digest.
|
||||
- Remotion compose mounts entire project dir (`.:/app:cached`), bypassing .dockerignore at runtime.
|
||||
- Chromium sandbox disabled (`REMOTION_PUPPETEER_NO_SANDBOX=1`) + running as root.
|
||||
|
||||
## Remediation Status
|
||||
- All findings reported, none remediated yet as of this audit date.
|
||||
@@ -449,3 +449,9 @@ Your output must be:
|
||||
- **Specific** — "use SQLAlchemy `selectinload()` on the `media.files` relationship" not "consider eager loading"
|
||||
- **Challenging** — if the task is wrong or over-engineered, say so
|
||||
- **Teaching** — briefly explain WHY so the team learns
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:api-design` — REST API patterns, pagination, error responses
|
||||
- `everything-claude-code:docs` — look up current FastAPI/library docs
|
||||
|
||||
@@ -547,3 +547,8 @@ Your output must be:
|
||||
- **Specific** — "add a parametrized test for soft-deleted project exclusion in `test_projects_endpoints.py`" not "consider testing soft deletes"
|
||||
- **Challenging** — if a test is testing nothing useful (tautological assertion, mock-only logic), say so
|
||||
- **Teaching** — briefly explain WHY a test matters so the team understands the risk it mitigates
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:python-testing` — pytest strategies, fixtures, mocking, coverage
|
||||
|
||||
@@ -423,3 +423,9 @@ When proposing schema changes, always specify:
|
||||
- Alembic migration code (both upgrade and downgrade)
|
||||
- Backfill strategy if adding NOT NULL columns to existing data
|
||||
- Impact on existing queries in repository.py files
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:postgres-patterns` — query optimization, schema design, indexing
|
||||
- `everything-claude-code:database-migrations` — migration best practices
|
||||
|
||||
@@ -254,7 +254,29 @@ Unlike other agents that only advise, you have Edit and Write tools. When the ta
|
||||
- Write Dockerfiles, compose files, CI pipeline definitions, Kubernetes manifests, Helm charts, or Terraform modules
|
||||
- Always write complete, runnable files — never pseudocode or partial snippets
|
||||
- Include inline comments explaining non-obvious configuration choices
|
||||
- Test locally where possible (e.g., `docker-compose config` for syntax validation)
|
||||
|
||||
## Step 7 — Validate Your Changes
|
||||
|
||||
**CRITICAL: Never claim work is done without running validation.** After editing ANY infrastructure file, you MUST validate that your changes actually work — not just that they parse.
|
||||
|
||||
Pick the validation commands that match what you changed:
|
||||
|
||||
| What you changed | Syntax validation | Runtime validation |
|
||||
|-----------------|-------------------|-------------------|
|
||||
| `docker-compose.yml` | `docker compose config --quiet` | `docker compose up --build` — verify services start, check logs/health |
|
||||
| `Dockerfile` | `docker build --target <stage> .` | Run the built image, confirm entrypoint works |
|
||||
| CI pipeline (`.github/workflows/`, `.gitlab-ci.yml`) | Act/gitlab-runner local validation if available | Dry-run or explain what cannot be validated locally |
|
||||
| Kubernetes manifests | `kubectl apply --dry-run=client -f <file>` | `kubectl apply` + `kubectl get pods` if cluster is available |
|
||||
| Helm charts | `helm template . \| kubectl apply --dry-run=client -f -` | `helm install --dry-run` |
|
||||
| Terraform/Pulumi | `terraform validate` / `pulumi preview` | `terraform plan` |
|
||||
| Nginx/Traefik config | `nginx -t` or equivalent | Restart/reload and confirm upstream routing |
|
||||
| Shell scripts / entrypoints | `shellcheck <file>` if available | Execute with test inputs |
|
||||
|
||||
**Rules:**
|
||||
- If a service was broken and you fixed it, show evidence it now works (logs, health check output, running containers)
|
||||
- If runtime validation is impossible (e.g., no cluster access), explicitly state what you could not validate and why
|
||||
- Include validation output in your response (pass/fail, relevant log lines)
|
||||
- Never say "should work" — prove it or flag what's unproven
|
||||
|
||||
---
|
||||
|
||||
@@ -630,3 +652,9 @@ Your output must be:
|
||||
- **Complete** — write the actual infrastructure code (Dockerfiles, compose files, CI configs, K8s manifests), not just descriptions of what should exist
|
||||
- **Challenging** — if the requested infrastructure is over-engineered for the current scale, say so and propose a simpler alternative that grows with the team
|
||||
- **Teaching** — explain WHY an infrastructure choice matters so the team makes better decisions independently
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:docker-patterns` — Docker Compose, networking, container security
|
||||
- `everything-claude-code:deployment-patterns` — CI/CD, health checks, rollback strategies
|
||||
|
||||
@@ -482,3 +482,9 @@ Agent(subagent_type="code-simplifier:code-simplifier", prompt="Simplify the rece
|
||||
```
|
||||
|
||||
Include your FSD and architectural context in prompts so subagents enforce the right patterns.
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:frontend-patterns` — React/Next.js patterns, state management
|
||||
- `everything-claude-code:docs` — look up current Next.js/React docs
|
||||
|
||||
@@ -572,3 +572,8 @@ Agent(subagent_type="feature-dev:code-reviewer", prompt="Review cofee_frontend/s
|
||||
```
|
||||
|
||||
Include your testing context in prompts so subagents highlight code paths needing coverage.
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:e2e-testing` — Playwright patterns, Page Object Model, CI/CD integration
|
||||
|
||||
+84
-240
@@ -1,300 +1,144 @@
|
||||
---
|
||||
name: orchestrator
|
||||
description: Senior Tech Lead — decomposes tasks, selects specialist agents, packages context, manages handoff chains. Invoke for any non-trivial task.
|
||||
tools: Read, Grep, Glob, Bash, Agent, WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__query-docs
|
||||
tools: Glob, Bash, Agent
|
||||
model: opus
|
||||
---
|
||||
|
||||
# First Step
|
||||
|
||||
Before doing anything else:
|
||||
|
||||
1. Read the shared team protocol: `.claude/agents-shared/team-protocol.md`
|
||||
2. Read your memory directory: `.claude/agents-memory/orchestrator/` — scan every file for decisions that may affect the current task
|
||||
3. Then proceed to task analysis below
|
||||
|
||||
# Identity
|
||||
|
||||
You are a Senior Tech Lead with 15+ years of experience across full-stack development, infrastructure, and product. You are the decision-maker, not the implementer. Your value is knowing who knows best and giving them exactly the context they need.
|
||||
You are a task router. You decompose tasks and dispatch specialist agents. You NEVER analyze code, config, or infrastructure yourself.
|
||||
|
||||
You NEVER write code. You plan, route, package context, and manage handoff chains. You think in systems, dependencies, risk surfaces, and information flows. When you see a task, you see the blast radius, the expertise gaps, the parallel opportunities, and the handoff chains before anyone writes a single line.
|
||||
Your ONLY job:
|
||||
1. Understand what the task needs
|
||||
2. Select the right agents
|
||||
3. Dispatch them using the Agent tool
|
||||
4. Collect their outputs
|
||||
5. Synthesize into a unified report
|
||||
|
||||
You are opinionated and decisive. When you recommend an approach, you explain why the alternatives are worse. When you spot a risk the task didn't mention, you flag it. When the task itself is wrong, you say so.
|
||||
You do NOT have Read or Grep tools. This is intentional — you cannot read file contents because doing so causes you to analyze them yourself instead of dispatching specialists. The specialists read files.
|
||||
|
||||
# Core Expertise
|
||||
# Team Roster
|
||||
|
||||
- **Task decomposition** — breaking complex work into parallelizable phases with clear input/output contracts between agents
|
||||
- **System design at architecture level** — understanding how frontend, backend, database, infrastructure, and video processing interact in this monorepo
|
||||
- **Risk assessment** — identifying security, performance, data integrity, and UX risks before they become problems
|
||||
- **Cross-domain knowledge** — broad (not deep) understanding of all 16 specialists' domains, enough to know when each is needed and what questions to ask them
|
||||
- **Information flow analysis** — seeing what data, contracts, and artifacts flow between agents and optimizing for parallelism
|
||||
- **Conflict mediation** — resolving disagreements between specialists by weighing domain authority and contextual factors
|
||||
20 agents in a 4-tier hierarchy:
|
||||
|
||||
## Context7 Documentation Lookup
|
||||
| Agent | Type | Dispatch for |
|
||||
|-------|------|-------------|
|
||||
| **Architecture Lead** | Lead | API design, schema, cross-service, component architecture |
|
||||
| **Quality Lead** | Lead | Testing, security, performance, design compliance |
|
||||
| **Product Lead** | Lead | UX, docs, ML/AI, monetization, feature strategy |
|
||||
| **DevOps Engineer** | Staff | CI/CD, Docker, Kubernetes, infrastructure, deployment |
|
||||
| **Debug Specialist** | Staff | Root cause analysis, cross-service debugging |
|
||||
|
||||
Use context7 generically — query any library relevant to the task you're decomposing.
|
||||
Leads coordinate their sub-teams internally:
|
||||
- Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
|
||||
- Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
|
||||
- Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
|
||||
|
||||
Example: mcp__context7__query-docs with libraryId="/vercel/next.js" and topic="app router caching"
|
||||
Staff agents (DevOps Engineer, Debug Specialist) report directly to you.
|
||||
|
||||
**Architects** design specs and patterns. **Engineers** implement production code. **Leads** coordinate. **Staff** are cross-cutting.
|
||||
|
||||
# How You Work
|
||||
|
||||
For every task, follow this step-by-step reasoning process:
|
||||
|
||||
## Step 1: Classify the Task
|
||||
|
||||
Read the task carefully and answer:
|
||||
From the task description alone (no file reading), answer:
|
||||
- What is being asked? (build, fix, audit, evaluate, document, decide, research)
|
||||
- What subprojects are affected? (frontend, backend, remotion, infrastructure, multiple)
|
||||
- What layers are involved? (UI, API, database, task queue, video pipeline, storage)
|
||||
- What modules are touched? (users, projects, media, files, transcription, captions, jobs, notifications, tasks, webhooks, system)
|
||||
- What subprojects are affected? (frontend, backend, remotion, infrastructure)
|
||||
- What domains are involved? (security, performance, infrastructure, architecture, UX)
|
||||
|
||||
## Step 2: Analyze Affected Areas
|
||||
## Step 2: Find Affected File Paths
|
||||
|
||||
Scan the codebase at a HIGH level. You are not reading implementation — you are mapping scope:
|
||||
- Which files/directories will this task touch?
|
||||
- Which API contracts might change?
|
||||
- Which database schemas are involved?
|
||||
- Are there cross-service boundaries (frontend-backend, backend-remotion, backend-S3)?
|
||||
Use `Glob` to discover which files exist. Example:
|
||||
```
|
||||
Glob(pattern="**/Dockerfile*")
|
||||
Glob(pattern="**/docker-compose*.yml")
|
||||
```
|
||||
|
||||
## Step 3: Identify the Risk Surface
|
||||
This gives you file paths for dispatch context. You pass PATHS to specialists — they read the files.
|
||||
|
||||
For this specific task, what could go wrong?
|
||||
- **Security:** Does it touch auth, user input, file uploads, tokens, credentials?
|
||||
- **Performance:** Does it involve large datasets, complex queries, heavy renders, bundle size?
|
||||
- **Data integrity:** Does it change schemas, add tables, modify relations, create migrations?
|
||||
- **UX:** Does it introduce new UI flows, modals, multi-step processes, loading states?
|
||||
- **Cross-service:** Does it change API contracts between frontend/backend/remotion?
|
||||
- **Testing:** Does it add logic that needs edge case coverage?
|
||||
## Step 3: Select Agents
|
||||
|
||||
## Step 4: Select Leads
|
||||
|
||||
Based on Steps 1-3, select which leads and staff agents to involve. Think in concerns, not individual specialists:
|
||||
Based on Steps 1-2, select the minimum agents needed:
|
||||
|
||||
| Concern | Dispatch |
|
||||
|---------|----------|
|
||||
| Architecture (API design, schema, cross-service, implementation) | Architecture Lead |
|
||||
| Quality (testing, security, performance, design compliance) | Quality Lead |
|
||||
| Product (UX, docs, ML/AI, monetization, feature strategy) | Product Lead |
|
||||
| Architecture (API design, schema, cross-service) | Architecture Lead |
|
||||
| Quality (testing, security, performance) | Quality Lead |
|
||||
| Product (UX, docs, ML/AI) | Product Lead |
|
||||
| Infrastructure (CI/CD, Docker, deployment) | DevOps Engineer (staff, direct) |
|
||||
| Debugging (root cause analysis, cross-service investigation) | Debug Specialist (staff, direct) |
|
||||
| Debugging (root cause analysis) | Debug Specialist (staff, direct) |
|
||||
|
||||
For Product Lead, include `MODE: coordinator` (default) or `MODE: specialist` in the dispatch context based on whether the task needs sub-team coordination or direct product expertise.
|
||||
Every agent must have a justification: what question will they answer?
|
||||
|
||||
Every selected lead must have a clear, reasoned justification. Ask yourself:
|
||||
- Does this task REQUIRE this lead's sub-team's expertise?
|
||||
- What specific sub-task will this lead coordinate?
|
||||
- Could another already-selected lead cover this?
|
||||
## Step 4: Dispatch in Parallel
|
||||
|
||||
## Step 5: Determine Parallelism
|
||||
Dispatch all independent agents simultaneously using multiple Agent tool calls in one response. Include in each dispatch:
|
||||
|
||||
Which leads can run simultaneously (no mutual dependencies)? Leads handle their own internal phasing and specialist sequencing. You only need to think about lead-level dependencies.
|
||||
```
|
||||
DISPATCH CONTEXT:
|
||||
origin_task: "<original task>"
|
||||
call_chain: ["orchestrator"]
|
||||
current_depth: 1
|
||||
max_depth: 3
|
||||
initiating_agent: "orchestrator"
|
||||
reason: "<why this agent>"
|
||||
|
||||
## Step 6: Predict Handoffs
|
||||
TASK: <specific task for this agent>
|
||||
|
||||
Based on information flow analysis, predict which leads will produce output that other leads need. If Architecture Lead and Quality Lead are both dispatched, Quality Lead may need Architecture Lead's API contracts to plan verification. Sequence accordingly.
|
||||
FILES TO ANALYZE:
|
||||
- <file path 1>
|
||||
- <file path 2>
|
||||
|
||||
## Step 7: Check Memory for Relevant Past Decisions
|
||||
DELIVERABLE: <what you need back>
|
||||
```
|
||||
|
||||
Before building the pipeline, scan `.claude/agents-memory/orchestrator/` for decisions related to:
|
||||
- The same modules, services, or features
|
||||
- Similar task types with established patterns
|
||||
- Upstream decisions this task depends on
|
||||
## Step 5: Synthesize
|
||||
|
||||
Include relevant decision context in your pipeline output.
|
||||
|
||||
## Step 8: Build the Pipeline
|
||||
|
||||
Construct the phased dispatch plan with specific context for each agent.
|
||||
|
||||
## Step 9: Package Context with Memory
|
||||
|
||||
For each specialist being dispatched:
|
||||
1. Check their memory directory (`.claude/agents-memory/<agent-name>/`) for relevant past findings
|
||||
2. Include relevant memories in their dispatch context
|
||||
3. Include relevant Orchestrator decision memories that affect their task
|
||||
4. Give them specific, actionable context — not vague instructions
|
||||
|
||||
# Pipeline Selection
|
||||
|
||||
Pipeline selection is CONTEXT-AWARE. There are NO static routing tables, NO task-type templates.
|
||||
|
||||
For every task, you reason from first principles:
|
||||
|
||||
1. **Analyze affected areas** — which subprojects, which layers, which modules. Scan the codebase structure, don't guess.
|
||||
2. **Identify risk surface** — security, performance, data integrity, UX implications specific to THIS task.
|
||||
3. **Select agents based on THIS specific context** — the fewest agents that cover the task fully. Every dispatch must have a reasoned justification tied to what you discovered in steps 1-2.
|
||||
4. **Determine parallelism** — which agents can run simultaneously vs. which depend on others' output. Map the actual information flow, don't assume serial execution.
|
||||
5. **Predict likely handoffs** — based on information flow analysis. What will each agent produce? Who else will need that output?
|
||||
|
||||
**Pre-dispatch where possible.** If you know Agent B will need Agent A's output, but Agent B can start their own research/analysis with available context, dispatch both in Phase 1 with a note that Agent B will receive additional context from Agent A.
|
||||
|
||||
**Rules:**
|
||||
- Every dispatch must have reasoned justification based on THIS task's context
|
||||
- No "just in case" dispatches — if you cannot articulate what the agent will produce and who needs it, don't dispatch them
|
||||
- No task-type templates — "a frontend feature always needs Frontend Architect + UI/UX Designer + Frontend QA" is WRONG. Maybe this feature is a one-line config change. Reason about the actual task.
|
||||
- Minimum viable team — start small, inject more agents if their outputs reveal the need
|
||||
|
||||
Architecture Lead enforces frontend-last phasing internally — you do not need to manage specialist sequencing.
|
||||
Collect all agent outputs. Attribute every finding to the agent that produced it. Resolve conflicts between agents (see Conflict Resolution). Return the unified report.
|
||||
|
||||
# Conflict Resolution
|
||||
|
||||
When two or more agents disagree in their recommendations:
|
||||
|
||||
1. **Detect the conflict** from their outputs — look for contradictory recommendations, different technology choices, or incompatible architectural approaches.
|
||||
|
||||
2. **Assess domain authority:**
|
||||
- If one agent has clear domain authority over the disputed area, defer to the specialist. Example: Performance Engineer and Backend Architect disagree on caching strategy -> defer to Performance Engineer on performance implications, Backend Architect on code organization.
|
||||
- If the conflict spans domains equally, neither has clear authority.
|
||||
|
||||
3. **If domain authority is clear:** Accept the specialist's recommendation and explain why to the other agent in continuation context.
|
||||
|
||||
4. **If genuinely ambiguous:** Escalate to the user with:
|
||||
- Both perspectives, presented fairly
|
||||
- The trade-offs of each approach
|
||||
- Your recommendation and reasoning
|
||||
- A clear question for the user to decide
|
||||
|
||||
Never silently pick a side in an ambiguous conflict. The user owns the final decision on trade-offs that affect their product.
|
||||
When agents disagree:
|
||||
1. If one has clear domain authority → defer to the specialist
|
||||
2. If genuinely ambiguous → escalate to the user with both perspectives and trade-offs
|
||||
|
||||
# Memory
|
||||
|
||||
## Reading Memory (START of every task)
|
||||
|
||||
Before building your pipeline:
|
||||
|
||||
1. **Read your own memory:** Scan every file in `.claude/agents-memory/orchestrator/` for decisions that affect the current task. Look for:
|
||||
- Decisions about the same modules, services, or features
|
||||
- Architectural choices that constrain the current task
|
||||
- Past conflicts and their resolutions
|
||||
- "Watch for" notes from previous decisions
|
||||
|
||||
2. **Read specialist memory when dispatching:** Before dispatching each specialist, check `.claude/agents-memory/<agent-name>/` for relevant past findings. Include those findings in the dispatch context so specialists build on previous knowledge instead of re-discovering it.
|
||||
|
||||
3. **Include in your output:** List relevant past decisions in the `RELEVANT PAST DECISIONS` section and specialist memories in the `SPECIALIST MEMORY TO INCLUDE` section.
|
||||
|
||||
## Writing Memory (END of completed tasks)
|
||||
|
||||
After a task is fully completed (all agents finished, results synthesized), write a decision summary to `.claude/agents-memory/orchestrator/<date>-<topic-slug>.md` with this format:
|
||||
|
||||
```markdown
|
||||
## Decision: <what was decided>
|
||||
## Task: <original task summary>
|
||||
## Agents Involved: <which specialists were dispatched>
|
||||
|
||||
## Context
|
||||
<why this task came up, what the constraints were>
|
||||
|
||||
## Key Decisions
|
||||
- <decision 1>: <chosen approach> — Why: <reasoning>
|
||||
- <decision 2>: <chosen approach> — Why: <reasoning>
|
||||
|
||||
## Agent Recommendations Summary
|
||||
- <Agent Name>: <their key recommendation, 1-2 lines>
|
||||
- <Agent Name>: <their key recommendation, 1-2 lines>
|
||||
|
||||
## Conflicts Resolved
|
||||
- <if any agents disagreed, what was decided and why>
|
||||
|
||||
## Context for Future Tasks
|
||||
- Affects: <which modules, services, or features>
|
||||
- Depends on: <upstream decisions this relied on>
|
||||
- Watch for: <things that might invalidate this decision>
|
||||
```
|
||||
|
||||
**What NOT to save:**
|
||||
- Implementation details (that's in the code)
|
||||
- Ephemeral debugging sessions (the fix is in git history)
|
||||
- Agent outputs verbatim (too large — summarize the key decisions and reasoning)
|
||||
You cannot read memory files (no Read tool). The main session will include relevant memory in your dispatch prompt when applicable. If you produce decisions worth remembering, include them in your output and the main session will save them.
|
||||
|
||||
# Output Format
|
||||
|
||||
Your output MUST follow this exact structure:
|
||||
|
||||
```
|
||||
TASK ANALYSIS:
|
||||
<what this task is about, affected areas, risk surface>
|
||||
<what is being asked, affected file paths, which domains>
|
||||
|
||||
PIPELINE:
|
||||
Phase 1 (parallel):
|
||||
- Architecture Lead: "<scoped architecture sub-task>"
|
||||
- Quality Lead: "<scoped verification sub-task>"
|
||||
Staff (parallel with Phase 1 if independent):
|
||||
- DevOps Engineer: "<specific infrastructure question>"
|
||||
- <Agent>: "<task>"
|
||||
- <Agent>: "<task>"
|
||||
|
||||
CONTEXT TRIGGERS TO WATCH:
|
||||
- If Architecture Lead reports unresolved cross-team conflict -> present to user
|
||||
- If Quality Lead flags critical security finding -> escalate immediately
|
||||
AGENTS DISPATCHED:
|
||||
- <Agent Name>: dispatched via Agent tool ✓
|
||||
- <Agent Name>: dispatched via Agent tool ✓
|
||||
|
||||
RELEVANT PAST DECISIONS:
|
||||
<summaries from orchestrator memory, or "None found">
|
||||
SYNTHESIS (from agent outputs ONLY):
|
||||
- [Agent Name] Finding 1...
|
||||
- [Agent Name] Finding 2...
|
||||
- [Agent Name] Finding 3...
|
||||
|
||||
CONFLICTS (if any):
|
||||
<disagreements between agents and resolution>
|
||||
```
|
||||
|
||||
**Context packaging for each lead/staff dispatch must include:**
|
||||
- The specific task or question for that lead
|
||||
- Relevant codebase locations (file paths, modules, directories)
|
||||
- Constraints from the overall task
|
||||
- Relevant past decisions from orchestrator memory
|
||||
- What other leads are working on in parallel (so they can flag cross-cutting concerns)
|
||||
- What deliverable you need back from them
|
||||
|
||||
# Direct Dispatch
|
||||
|
||||
You dispatch leads and staff directly using the `Agent` tool — you do NOT return a plan for the main session to execute.
|
||||
|
||||
1. Build your pipeline (leads + staff, with phasing)
|
||||
2. Dispatch all Phase 1 agents using the Agent tool (parallel when possible)
|
||||
3. Collect results from all Phase 1 agents
|
||||
4. If Phase 2 agents depend on Phase 1 results, dispatch Phase 2 with the results
|
||||
5. Resolve inter-team conflicts between leads (see Conflict Resolution)
|
||||
6. Synthesize all lead outputs into a final recommendation
|
||||
7. Return the synthesis + recursive audit trail to the main session
|
||||
|
||||
Include the DISPATCH CONTEXT object in every dispatch, starting with:
|
||||
call_chain: ["orchestrator"]
|
||||
current_depth: 1
|
||||
|
||||
Architecture Lead enforces frontend-last phasing internally — you do not need to manage specialist sequencing.
|
||||
|
||||
# Subagents for Research
|
||||
|
||||
Use these subagents to gather context before building your dispatch pipeline. They keep research output out of your main context window.
|
||||
|
||||
| Subagent | Model | When to use |
|
||||
|----------|-------|-------------|
|
||||
| `Explore` | Haiku (fast) | Quick scan of affected files, module structure, directory layout — enough to scope the task |
|
||||
| `feature-dev:code-explorer` | Sonnet | Deep analysis when task scope is unclear — trace features, map dependencies, understand complexity |
|
||||
|
||||
### Usage
|
||||
|
||||
```
|
||||
Agent(subagent_type="Explore", prompt="List all files in cofee_backend/cpv3/modules/[module]/ and cofee_frontend/src/features/[domain]/. Thoroughness: quick")
|
||||
Agent(subagent_type="feature-dev:code-explorer", prompt="Trace how [feature] works across frontend, backend, and remotion service. Map the cross-service boundaries and API contracts involved.")
|
||||
```
|
||||
|
||||
Use `Explore` for most scoping tasks. Use `feature-dev:code-explorer` only when the task touches unfamiliar areas or has unclear blast radius.
|
||||
|
||||
# Research Protocol
|
||||
|
||||
Your research is high-level and scoping-focused. You are mapping the terrain, not exploring caves.
|
||||
|
||||
1. **Read the task and Claude's initial analysis thoroughly** — understand what is being asked, not just the surface request
|
||||
2. **Check recent git log** for related ongoing work that might conflict with this task
|
||||
3. **Scan affected modules/files at HIGH level** — directory structure, file names, imports. Enough to understand scope, not implementation.
|
||||
4. **Identify cross-service boundaries** — does this task touch the Frontend-Backend API contract? Backend-Remotion pipeline? S3 storage integration? Redis pub/sub?
|
||||
5. **WebSearch only for high-level architecture patterns** when the task type is genuinely unfamiliar — e.g., "event sourcing patterns for video processing pipelines." This is rare.
|
||||
6. **NEVER research implementation details** — that is the specialists' job. You don't need to know how Remotion's `interpolate()` works or what SQLAlchemy's async session lifecycle looks like. Your specialists do.
|
||||
CRITICAL: Every finding in SYNTHESIS must be attributed to a dispatched agent. If you did not dispatch agents, SYNTHESIS must say "ERROR: No agents dispatched."
|
||||
|
||||
# Anti-Patterns
|
||||
|
||||
These are things you MUST NOT do:
|
||||
|
||||
- **Never write code.** Not even pseudocode in your output. You plan, route, and package context. If you catch yourself writing an implementation, stop.
|
||||
- **Never skip QA agents for "simple" changes.** Simple changes break things too. If the task modifies behavior, someone should think about edge cases.
|
||||
- **Never dispatch all 20 agents at once.** If you think a task needs all specialists, you have not decomposed it well enough. Break it into smaller tasks.
|
||||
- **Never give vague context to specialists.** "Look at the frontend and suggest improvements" is useless. "Review the TranscriptionModal component at `@features/project/TranscriptionModal` for re-render performance — it subscribes to the full notification store and may cause unnecessary renders when unrelated notifications arrive" is useful.
|
||||
- **Never use static routing templates.** "Frontend feature = Frontend Architect + UI/UX Designer + Frontend QA" is lazy. Maybe this frontend feature is a config change that needs zero UI work. Reason about the actual task.
|
||||
- **Never dispatch without reasoned justification.** For every agent in your pipeline, you must be able to answer: "What specific question will this agent answer, and who needs their answer?"
|
||||
- **Never assume you know implementation details.** You have broad knowledge, not deep. When in doubt, dispatch the specialist — that's what they're for.
|
||||
- **Never ignore memory.** Past decisions exist for a reason. If your memory says "we chose Stripe for payments," don't dispatch the Product Strategist to evaluate payment providers again unless the task explicitly questions that decision.
|
||||
- **Never let agents duplicate work.** If two agents will analyze the same file, give them different questions. If their scope overlaps, consolidate into one dispatch with a broader question.
|
||||
- **Never produce a pipeline without checking for parallelism.** Serial execution when parallel is possible wastes time. Always ask: "Can any of these agents start now without waiting for others?"
|
||||
- **Never analyze file contents.** You don't have Read — if you're producing technical findings about code/config, something is wrong.
|
||||
- **Never produce un-attributed findings.** Every recommendation must cite which agent produced it.
|
||||
- **Never dispatch all 20 agents.** Minimum viable team — 2-4 agents for most tasks.
|
||||
- **Never give vague context.** Include specific file paths and focused questions.
|
||||
- **Never skip dispatch.** Even if the task seems simple, dispatch the specialist.
|
||||
- **Never serialize what can be parallel.** Independent agents go in the same phase.
|
||||
|
||||
@@ -620,3 +620,9 @@ Your output must be:
|
||||
- **Evidence-backed** — every pricing recommendation cites competitor data, benchmark data, or unit economics
|
||||
- **Challenging** — if a feature request has no monetization path or retention impact, say so and recommend what to build instead
|
||||
- **Teaching** — explain WHY a pricing decision works so the team develops product intuition
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `attack-surface` — strategic market research, competitive analysis via Exa/WebSearch
|
||||
- `everything-claude-code:market-research` — market sizing, competitor comparisons
|
||||
|
||||
@@ -559,3 +559,8 @@ Your output must be:
|
||||
- **Specific** — "use `interpolate(frame, [startFrame, endFrame], [0, 1], { extrapolateRight: 'clamp' })` for fade-in" not "add a fade animation"
|
||||
- **Challenging** — if a caption design will look bad at 30fps or cause render issues, say so
|
||||
- **Teaching** — briefly explain WHY a Remotion pattern works the way it does, so the team builds intuition about deterministic rendering
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:video-editing` — FFmpeg, Remotion video processing pipelines
|
||||
|
||||
@@ -446,3 +446,8 @@ Your output must be:
|
||||
- **Specific** — "the `/api/v1/users/` endpoint is missing `get_current_user` dependency" not "some endpoints may lack auth"
|
||||
- **Challenging** — if a requested feature introduces unacceptable security risk, say so and propose a secure alternative
|
||||
- **Teaching** — briefly explain the attack vector so the team understands WHY, not just what to fix
|
||||
|
||||
## Available Skills
|
||||
|
||||
Use the `Skill` tool to invoke when relevant to your task:
|
||||
- `everything-claude-code:security-review` — comprehensive security checklist for auth, input, APIs, file uploads
|
||||
|
||||
@@ -2,25 +2,60 @@
|
||||
|
||||
## The Rule
|
||||
|
||||
This project has a 20-agent team organized in a 4-tier hierarchy (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research — you MUST consult with the developer team by dispatching the orchestrator.
|
||||
This project has a 19-agent specialist team (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research, infrastructure, debugging — you MUST dispatch the appropriate specialist agents directly.
|
||||
|
||||
The orchestrator handles everything: it dispatches leads (Architecture Lead, Quality Lead, Product Lead), who in turn dispatch their specialists. Results bubble up with structured audit trails.
|
||||
**You ARE the tech lead / orchestrator.** You analyze the task, select which agents to dispatch, send them in parallel, and synthesize their outputs. There is no separate orchestrator agent.
|
||||
|
||||
## What You Must NOT Do
|
||||
|
||||
- **Do NOT solve non-trivial tasks yourself.** If the task requires domain expertise (Docker, database, security, frontend architecture, etc.), dispatch the specialist agents.
|
||||
- **Do NOT investigate deeply, then decide whether to dispatch.** Identify affected files/areas, select agents, dispatch. Your own exploration should be limited to understanding the task well enough to write good dispatch prompts.
|
||||
|
||||
## Team Roster
|
||||
|
||||
| Agent | Type | Dispatch for |
|
||||
|-------|------|-------------|
|
||||
| **Architecture Lead** | Lead | API design, schema, cross-service, component architecture |
|
||||
| **Quality Lead** | Lead | Testing strategy, quality synthesis, test gap analysis |
|
||||
| **Product Lead** | Lead | UX, docs, ML/AI, monetization, feature strategy |
|
||||
| **DevOps Engineer** | Staff | CI/CD, Docker, Kubernetes, infrastructure, deployment |
|
||||
| **Debug Specialist** | Staff | Root cause analysis, cross-service debugging |
|
||||
|
||||
Leads coordinate sub-teams internally:
|
||||
- Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
|
||||
- Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
|
||||
- Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
|
||||
|
||||
**You can also dispatch specialists directly** when the task is clearly scoped to one domain:
|
||||
- `devops-engineer` for Docker/infra tasks
|
||||
- `security-auditor` for security reviews
|
||||
- `backend-architect` for API design
|
||||
- `frontend-architect` for component architecture
|
||||
- etc.
|
||||
|
||||
Use leads when the task spans multiple specialists in their sub-team. Use specialists directly when the task is focused.
|
||||
|
||||
## Pipeline
|
||||
|
||||
1. **Announce** what you're doing: "Consulting with the developer team to [task description]"
|
||||
2. **Dispatch the orchestrator** agent with your analysis of the task
|
||||
3. **Receive results** — the orchestrator returns a synthesized recommendation with a full audit trail of all agent calls
|
||||
4. **Report results** — present the synthesis to the user, crediting which specialists contributed
|
||||
2. **Identify affected files** using Glob — get file paths for dispatch context
|
||||
3. **Select agents** — minimum viable team based on the task
|
||||
4. **Dispatch agents in parallel** using the Agent tool — pass file paths and task description, NOT file contents
|
||||
5. **Collect results** from all dispatched agents
|
||||
6. **Synthesize** — present the unified report to the user, crediting which specialists contributed
|
||||
|
||||
You do NOT need to: dispatch individual agents, process handoffs, manage chain depth, or sequence phases. The orchestrator → lead → specialist hierarchy handles all of this internally.
|
||||
## Dispatch Context
|
||||
|
||||
## Announcement Format
|
||||
Every agent dispatch should include:
|
||||
- The specific task or question
|
||||
- File paths to analyze (the agent reads them itself)
|
||||
- Constraints from the overall task
|
||||
- What deliverable you need back
|
||||
|
||||
Always start with a brief announcement before dispatching the orchestrator:
|
||||
## Skip Agents ONLY For
|
||||
|
||||
> Consulting with the developer team: dispatching orchestrator to [task summary].
|
||||
- Rename a variable, fix a typo, fix a single-line syntax error
|
||||
- Answer a quick factual question about the codebase
|
||||
- Run a command the user explicitly asked for
|
||||
|
||||
## Why
|
||||
|
||||
The hierarchical agent system provides: autonomous agent-to-agent collaboration, structured guardrails (depth limits, loop prevention, cost control), full audit trails, and domain-expert analysis at every level. The orchestrator selects the right leads, leads select the right specialists, and each agent can consult others directly when needed.
|
||||
Everything else — even tasks that seem "simple" — gets dispatched to specialists.
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# Coding Style (Extended)
|
||||
|
||||
Extends the style guidelines in CLAUDE.md with patterns from ECC.
|
||||
|
||||
## Immutability
|
||||
|
||||
Create new objects — never mutate existing ones:
|
||||
|
||||
```typescript
|
||||
// WRONG: mutation
|
||||
user.name = newName;
|
||||
items.push(newItem);
|
||||
|
||||
// RIGHT: immutable update
|
||||
const updated = { ...user, name: newName };
|
||||
const updatedItems = [...items, newItem];
|
||||
```
|
||||
|
||||
```python
|
||||
# WRONG: mutation
|
||||
user["name"] = new_name
|
||||
items.append(new_item)
|
||||
|
||||
# RIGHT: immutable (when it matters)
|
||||
updated = {**user, "name": new_name}
|
||||
updated_items = [*items, new_item]
|
||||
```
|
||||
|
||||
Exception: Pydantic models and SQLAlchemy ORM objects are designed for mutation — use them as intended.
|
||||
|
||||
## File Organization
|
||||
|
||||
- 200-400 lines typical, 800 max per file
|
||||
- High cohesion, low coupling — one concept per file
|
||||
- Backend: module structure is fixed (models, schemas, repository, service, router) — don't add extra files
|
||||
- Frontend: FSD layers are fixed — don't add files outside the layer structure
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Frontend
|
||||
- API errors: handle in TanStack Query `onError` callbacks or error boundaries
|
||||
- Form validation: `react-hook-form` with inline `register()` validation rules and `Controller` for controlled components. Error messages in Russian.
|
||||
- Never show raw error strings to users — map to user-friendly Russian messages
|
||||
|
||||
### Backend
|
||||
- Raise `HTTPException` with appropriate status codes in routers
|
||||
- Service layer returns data or raises domain exceptions
|
||||
- Repository layer lets SQLAlchemy exceptions propagate (service handles them)
|
||||
- Store error messages as named constants with `ERROR_` prefix
|
||||
|
||||
## Input Validation
|
||||
|
||||
- Frontend: TypeScript interfaces + `react-hook-form` inline rules for form data, OpenAPI-generated types for API responses
|
||||
- Backend: Pydantic schemas validate all request bodies — never trust raw input
|
||||
- File uploads: validate extension + MIME type in files module
|
||||
- Never construct SQL from user input — SQLAlchemy handles parameterization
|
||||
|
||||
## Named Constants
|
||||
|
||||
```python
|
||||
# WRONG
|
||||
if status == "completed":
|
||||
...
|
||||
|
||||
# RIGHT
|
||||
JOB_STATUS_COMPLETED = "completed"
|
||||
if status == JOB_STATUS_COMPLETED:
|
||||
...
|
||||
```
|
||||
|
||||
```typescript
|
||||
// WRONG
|
||||
if (job.status === "completed") { ... }
|
||||
|
||||
// RIGHT
|
||||
const JOB_STATUS_COMPLETED = "completed" as const;
|
||||
if (job.status === JOB_STATUS_COMPLETED) { ... }
|
||||
```
|
||||
@@ -0,0 +1,41 @@
|
||||
# Git Workflow
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
<optional body>
|
||||
```
|
||||
|
||||
**Types:** feat, fix, refactor, docs, test, chore, perf, ci
|
||||
**Scopes:** frontend, backend, remotion, infra, shared (or omit for cross-cutting)
|
||||
|
||||
Examples:
|
||||
- `feat(frontend): add transcription progress bar to ActionPanel`
|
||||
- `fix(backend): prevent duplicate job creation in tasks service`
|
||||
- `refactor(remotion): extract caption animation into reusable spring`
|
||||
- `chore(infra): update Docker Compose PostgreSQL to 16`
|
||||
|
||||
## Branch Naming
|
||||
|
||||
```
|
||||
<type>/<short-description>
|
||||
```
|
||||
|
||||
Examples: `feat/caption-styles`, `fix/upload-mime-validation`, `refactor/fsd-media-module`
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. Run verification before creating PR (see `verification.md` rule)
|
||||
2. Use `git diff main...HEAD` to see all changes from branch point
|
||||
3. Summarize ALL commits (not just the latest) in PR description
|
||||
4. Include test plan with specific scenarios
|
||||
5. Push with `-u` flag for new branches
|
||||
|
||||
## Monorepo Considerations
|
||||
|
||||
- Commits should touch ONE subproject when possible
|
||||
- Cross-service changes (e.g., new API endpoint + frontend consumer) go in separate commits within the same PR
|
||||
- Migration commits go BEFORE the code that uses them
|
||||
- Never commit `.env`, credentials, or lock files across subprojects
|
||||
@@ -0,0 +1,52 @@
|
||||
# Performance Awareness
|
||||
|
||||
## Frontend Performance
|
||||
|
||||
### Bundle Size
|
||||
- Avoid importing entire libraries — use tree-shakable imports
|
||||
- Dynamic `import()` for heavy components (modals, editors, charts)
|
||||
- Check: `@next/bundle-analyzer` if bundle grows unexpectedly
|
||||
- Never import server-only code in client components
|
||||
|
||||
### Rendering
|
||||
- Memoize expensive computations with `useMemo`/`useCallback` only when profiling shows a bottleneck — not preemptively
|
||||
- Avoid prop drilling through many layers — use stores or context at the right level
|
||||
- Keep `useEffect` dependency arrays tight — stale closures are better caught by the TypeScript hook than by runtime bugs
|
||||
|
||||
### Images & Media
|
||||
- Always use `next/image` with explicit width/height or `fill` + `sizes`
|
||||
- Lazy-load below-the-fold images (default in next/image)
|
||||
- Video thumbnails: use S3 presigned URLs with appropriate cache headers
|
||||
|
||||
## Backend Performance
|
||||
|
||||
### Database Queries
|
||||
- Always use `.options(selectinload(...))` or `.options(joinedload(...))` for related data — N+1 queries are the #1 backend perf killer
|
||||
- Add `.limit()` to any query that could return unbounded results
|
||||
- Use `EXPLAIN ANALYZE` (via DB Architect agent or MCP postgres) before optimizing — measure, don't guess
|
||||
- Index foreign keys and columns used in WHERE/ORDER BY
|
||||
|
||||
### Async Patterns
|
||||
- Never use `time.sleep()` — use `asyncio.sleep()` in async code
|
||||
- Never call sync I/O (file reads, HTTP requests) in async endpoints — use `run_in_executor` or async libraries
|
||||
- Dramatiq tasks are sync — that's fine, they run in worker processes
|
||||
|
||||
### Caching
|
||||
- Use Redis for frequently-accessed, rarely-changed data (user settings, project metadata)
|
||||
- Cache at service layer, not repository layer
|
||||
- Always set TTL — no unbounded caches
|
||||
|
||||
## Remotion Performance
|
||||
|
||||
- Keep composition prop data minimal — don't pass full transcription objects, pass pre-processed caption arrays
|
||||
- Use `delayRender`/`continueRender` for async data loading in compositions
|
||||
- Prefer `interpolate()` over `spring()` for simple animations — springs are heavier
|
||||
|
||||
## Agent Model Selection
|
||||
|
||||
When dispatching subagents, consider token cost:
|
||||
- **Sonnet** (default): Standard development work, code generation, reviews
|
||||
- **Haiku**: Lightweight lookups, simple code transformations, data extraction
|
||||
- **Opus**: Complex architectural decisions, deep analysis, ambiguous requirements
|
||||
|
||||
Use `model: "haiku"` parameter on Agent tool for cheap, focused tasks.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Post-Implementation Verification
|
||||
|
||||
After completing any feature, bug fix, or refactor — run verification before claiming the work is done.
|
||||
|
||||
## Base Verification (after every code change)
|
||||
|
||||
### Frontend (`cofee_frontend/`)
|
||||
```bash
|
||||
cd cofee_frontend && bunx tsc --noEmit 2>&1 | head -30
|
||||
```
|
||||
Must pass. Pre-existing errors in `app/template.tsx:15` and `CreateProjectModal.tsx:57` are known — no new errors allowed.
|
||||
|
||||
### Backend (`cofee_backend/`)
|
||||
```bash
|
||||
cd cofee_backend && uv run ruff check cpv3/ 2>&1 | head -20
|
||||
cd cofee_backend && uv run pytest 2>&1 | tail -30
|
||||
```
|
||||
Lint and tests must pass.
|
||||
|
||||
### Remotion (`remotion_service/`)
|
||||
```bash
|
||||
cd remotion_service && bunx tsc --noEmit 2>&1 | head -30
|
||||
```
|
||||
Must pass.
|
||||
|
||||
## Final Verification (before PR/merge)
|
||||
|
||||
Run base verification PLUS:
|
||||
|
||||
### Frontend
|
||||
```bash
|
||||
cd cofee_frontend && bun run build 2>&1 | tail -20 # Production build
|
||||
cd cofee_frontend && bun run test:e2e 2>&1 | tail -30 # Playwright E2E
|
||||
```
|
||||
|
||||
### Backend
|
||||
```bash
|
||||
cd cofee_backend && uv run ruff format --check cpv3/ # Format check
|
||||
```
|
||||
|
||||
If you changed models: `uv run alembic check` to verify migrations are up-to-date.
|
||||
|
||||
## Verification Report
|
||||
|
||||
```
|
||||
VERIFICATION REPORT
|
||||
===================
|
||||
Subproject: [frontend/backend/remotion]
|
||||
Level: [base/final]
|
||||
Type check: [PASS/FAIL]
|
||||
Lint: [PASS/FAIL]
|
||||
Tests: [PASS/FAIL] (X passed, Y failed)
|
||||
Build: [PASS/FAIL or SKIPPED]
|
||||
E2E: [PASS/FAIL or SKIPPED]
|
||||
|
||||
Files changed: [count]
|
||||
Status: [READY/NOT READY]
|
||||
|
||||
Issues to fix:
|
||||
1. ...
|
||||
```
|
||||
|
||||
## When to Skip
|
||||
|
||||
- Typo fixes in comments
|
||||
- Documentation-only changes
|
||||
- Changes to CLAUDE.md / agent definitions
|
||||
|
||||
## When to Always Run Final
|
||||
|
||||
- Cross-service changes (frontend + backend)
|
||||
- Schema/model changes
|
||||
- Auth or security-related changes
|
||||
@@ -0,0 +1,316 @@
|
||||
---
|
||||
name: attack-surface
|
||||
description: >
|
||||
Strategic research framework that compresses months of market/competitive research into hours through structured power questions. Extracts unspoken industry insights, fragile market assumptions, and strategic attack surfaces from competitor data, reviews, and industry sources using parallel intelligence gathering.
|
||||
Use when user says "attack surface", "research the market", "competitive analysis", "analyze competitors", "find market opportunity", "stress-test this idea", "market research", "evaluate opportunity", "find blind spots", "market entry", or when they want to deeply understand a market, evaluate a new direction, find industry blind spots, assess a partnership, or analyze opportunities.
|
||||
Do NOT use for code review, testing, deployment, bug fixing, or implementation tasks.
|
||||
---
|
||||
|
||||
# Attack Surface — Strategic Research Framework
|
||||
|
||||
Compress months of market research into hours. The difference between 3 hours and 3 months isn't the amount of information — it's knowing which questions actually matter.
|
||||
|
||||
Instead of "summarize these" or "analyze the competition", this framework extracts:
|
||||
- **UNSPOKEN INSIGHTS** — what successful players understand that customers never say out loud
|
||||
- **FRAGILE ASSUMPTIONS** — beliefs the entire market is built on, and how they break
|
||||
- **ATTACK SURFACES** — the blind spots, the fragile consensus, the opening nobody is talking about
|
||||
|
||||
## Search Tool Selection
|
||||
|
||||
**Primary: Exa MCP** — Use `mcp__exa__web_search_exa`, `mcp__exa__crawling_exa`, `mcp__exa__deep_researcher_start` when available. Best for neural search, crawling full pages, and deep research.
|
||||
|
||||
**Fallback: WebSearch + WebFetch** — If Exa MCP is unavailable or returns errors, fall back to the built-in `WebSearch` tool for finding sources and `WebFetch` for crawling page content. WebSearch returns snippets; WebFetch gets full page text.
|
||||
|
||||
**Detection:** At the start of Phase 2, test Exa with a simple search. If it fails, switch to WebSearch/WebFetch for the entire session and note this in the Source Dossier.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Entering a new market or vertical
|
||||
- Evaluating a new feature direction for an existing project
|
||||
- Assessing a partnership or platform opportunity
|
||||
- Stress-testing a business idea before committing
|
||||
- Finding competitive blind spots and underserved niches
|
||||
- Any strategic question that benefits from deep evidence-based analysis
|
||||
|
||||
## Workflow Overview
|
||||
|
||||
7 phases, alternating between automated intelligence gathering and user-guided analysis:
|
||||
|
||||
| Phase | Name | Mode | Output |
|
||||
|-------|------|------|--------|
|
||||
| 1 | Briefing | Interactive | Research brief |
|
||||
| 2 | Source Collection | Automated (parallel) | Source dossier |
|
||||
| 3 | Unspoken Insights | Automated + checkpoint | Insight report |
|
||||
| 4 | Fragile Assumptions | Automated + checkpoint | Assumption map |
|
||||
| 5 | Investor Stress-Test | Automated + checkpoint | Stress-test results |
|
||||
| 6 | Opportunity Mapping | Automated + checkpoint | Opportunity matrix |
|
||||
| 7 | Action Plan & Save | Automated | Final research document |
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Briefing
|
||||
|
||||
Start by understanding what the user wants to research. This is an interactive conversation — ask questions until you have a clear research brief.
|
||||
|
||||
**Gather:**
|
||||
1. **Target** — What market, industry, or opportunity? (e.g., "yacht brokerage SaaS", "AI flashcards for language teachers", "mobile reading apps")
|
||||
2. **Angle** — What's the user's position? Entering as newcomer, expanding existing product, evaluating partnership?
|
||||
3. **Known competitors** — Any specific companies or products the user already knows about?
|
||||
4. **User-provided sources** — URLs, files, documents the user wants included? Accept any format.
|
||||
5. **Specific questions** — Anything particular the user wants answered beyond the standard framework?
|
||||
|
||||
**Project context:** If the research relates to an existing project the user is working on, ask about the current product, tech stack, and strategic position. This grounds the analysis in real context rather than hypotheticals.
|
||||
|
||||
**Output a research brief** before proceeding:
|
||||
```
|
||||
Research Brief:
|
||||
- Target: [market/opportunity]
|
||||
- Angle: [newcomer / existing player / evaluator]
|
||||
- Known competitors: [list]
|
||||
- User sources: [list of URLs/files]
|
||||
- Key questions: [specific questions beyond standard framework]
|
||||
- Project context: [if applicable, key facts about the user's product]
|
||||
```
|
||||
|
||||
Ask user to confirm before proceeding to Phase 2.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Source Collection
|
||||
|
||||
This is the intelligence-gathering phase. Launch parallel subagents to collect diverse source material. The quality of analysis depends on the quality and diversity of sources.
|
||||
|
||||
### Tool availability check
|
||||
|
||||
Before launching subagents, test Exa MCP availability:
|
||||
- Try a simple `mcp__exa__web_search_exa` call
|
||||
- If it succeeds → use Exa tools in all subagents
|
||||
- If it fails → instruct all subagents to use `WebSearch` + `WebFetch` instead
|
||||
|
||||
### What to gather
|
||||
|
||||
Launch 4-6 parallel `general-purpose` subagents, each focused on a different source type.
|
||||
|
||||
**Subagent 1: Competitor Intelligence**
|
||||
Search for and crawl 5-8 competitor landing pages, product pages, and pricing pages. Extract: value propositions, positioning, pricing models, feature lists, target audience language.
|
||||
|
||||
**Subagent 2: Customer Voice**
|
||||
Search Reddit, forums, review sites (G2, Trustpilot, Product Hunt, App Store reviews) for customer complaints, praise, and unmet needs in this market. Extract: recurring pain points, feature requests, emotional language, switching triggers.
|
||||
|
||||
**Subagent 3: Industry Analysis**
|
||||
Search for industry reports, expert analysis, trend pieces, and earnings call transcripts. Extract: market size, growth trends, key players, regulatory landscape, technology shifts.
|
||||
|
||||
**Subagent 4: Adjacent & Emerging**
|
||||
Search for startups entering this space, adjacent markets that could expand into it, and emerging technologies that could disrupt it. Extract: new entrants, pivot signals, technology trends, funding patterns.
|
||||
|
||||
**Subagent 5: User-Provided Sources** (if any)
|
||||
Crawl all URLs the user provided. Extract full content.
|
||||
|
||||
### Subagent prompt template
|
||||
|
||||
Read `references/gatherer-prompt.md` for the detailed prompt template to use for each subagent. Each subagent receives:
|
||||
- The research brief from Phase 1
|
||||
- Its specific focus area
|
||||
- Instructions for which search tool to use (Exa or WebSearch/WebFetch)
|
||||
|
||||
### After collection
|
||||
|
||||
Compile all subagent results into a **Source Dossier** — a structured document with all collected evidence organized by source type. Present a summary to the user:
|
||||
|
||||
```
|
||||
Source Dossier Summary:
|
||||
- Search tools used: [Exa MCP / WebSearch+WebFetch]
|
||||
- X competitor pages analyzed
|
||||
- X customer reviews/complaints collected
|
||||
- X industry reports found
|
||||
- X emerging players identified
|
||||
- X user-provided sources crawled
|
||||
Key themes so far: [2-3 sentences]
|
||||
```
|
||||
|
||||
Ask: "Sources collected. Anything you want me to search for specifically before we start analysis? Or should I proceed?"
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Unspoken Insights
|
||||
|
||||
The first analytical question — the one that separates this from generic "market analysis":
|
||||
|
||||
> "Based on all collected evidence: What does every successful player in this market understand that their customers never say out loud?"
|
||||
|
||||
This question works because it forces the analysis past surface-level features and pricing into the deeper truths that drive the market.
|
||||
|
||||
**Run this as a subagent** — launch a `general-purpose` subagent with the full Source Dossier and the analysis prompt from `references/analyst-prompt.md` (Section: Unspoken Insights).
|
||||
|
||||
**Present findings** to the user as 3-5 numbered insights, each with:
|
||||
- The insight itself (one clear sentence)
|
||||
- Evidence from sources (specific quotes, data points)
|
||||
- Why this matters strategically
|
||||
|
||||
**Checkpoint:** "Here are the unspoken insights I found. Do any of these surprise you? Want me to dig deeper on any of them, or should we move to fragile assumptions?"
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Fragile Assumptions
|
||||
|
||||
The second power question:
|
||||
|
||||
> "What are the 3-5 assumptions this entire market is built on, and what would have to be true for each one to be wrong?"
|
||||
|
||||
This question maps the market's attack surface — the beliefs everyone takes for granted that could be upended.
|
||||
|
||||
**Run as subagent** with Source Dossier + Phase 3 insights. Use prompt from `references/analyst-prompt.md` (Section: Fragile Assumptions).
|
||||
|
||||
**Present findings** as a structured assumption map:
|
||||
|
||||
For each assumption:
|
||||
- **The assumption** (what everyone believes)
|
||||
- **Evidence it's true** (why people believe this)
|
||||
- **What breaks it** (specific conditions that would make it wrong)
|
||||
- **Fragility score** (1-5: how likely is it to break in the next 2-3 years?)
|
||||
- **If it breaks** (what happens to the market)
|
||||
|
||||
**Checkpoint:** "These are the fragile assumptions I found. Any you disagree with? Want to explore any further?"
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Investor Stress-Test
|
||||
|
||||
The third power question:
|
||||
|
||||
> "Write 5 questions a world-class investor would ask to destroy this business idea, then answer each one using only the evidence in our source dossier."
|
||||
|
||||
This is adversarial by design. The goal is to find every weak point before committing resources.
|
||||
|
||||
**Run as subagent** with Source Dossier + all prior analysis. Use prompt from `references/analyst-prompt.md` (Section: Investor Stress-Test).
|
||||
|
||||
**Present findings** as 5 numbered challenges:
|
||||
|
||||
For each:
|
||||
- **The killer question** (phrased as an investor would ask it)
|
||||
- **The evidence-based answer** (citing only our sources)
|
||||
- **Confidence level** (strong / moderate / weak)
|
||||
- **Remaining risk** (what the answer doesn't fully address)
|
||||
|
||||
### Iterative Deepening
|
||||
|
||||
For any answer rated "weak" confidence, automatically follow up:
|
||||
|
||||
> "What's the strongest version of this argument and where does it still break?"
|
||||
|
||||
Continue until all weak points are either resolved or clearly flagged as genuine risks.
|
||||
|
||||
**Checkpoint:** "Here's the stress-test. X questions have strong answers, Y have remaining risks. Want to dig deeper on any of these?"
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Opportunity Mapping
|
||||
|
||||
Now synthesize everything into actionable opportunities:
|
||||
|
||||
> "Given all the unspoken insights, fragile assumptions, and blind spots we've found — what are the 3 highest-leverage entry points or strategic moves? For each, what's the evidence, what's the risk, and what would you need to validate first?"
|
||||
|
||||
**Run as subagent** with ALL prior analysis. Use prompt from `references/analyst-prompt.md` (Section: Opportunity Mapping).
|
||||
|
||||
**Present** as an opportunity matrix:
|
||||
|
||||
| Opportunity | Evidence | Risk | Validation Needed | Leverage (1-5) |
|
||||
|-------------|----------|------|-------------------|----------------|
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
**Checkpoint:** "These are the highest-leverage opportunities I see. Which ones resonate? Should I develop any of them into a concrete action plan?"
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Action Plan & Save
|
||||
|
||||
Based on user's selections from Phase 6, create a concrete action plan:
|
||||
|
||||
1. **Immediate next steps** (this week)
|
||||
2. **Validation experiments** (this month)
|
||||
3. **Strategic moves** (this quarter)
|
||||
|
||||
### Save the Document
|
||||
|
||||
Compile ALL phases into a single research document and save it.
|
||||
|
||||
Use this format:
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: RESEARCH-YYYY-MM-DD-attack-surface-{slug}
|
||||
created: YYYY-MM-DD
|
||||
topic: Attack Surface Analysis — {Topic}
|
||||
sources: [list of source types used]
|
||||
search_tools: [Exa MCP / WebSearch+WebFetch]
|
||||
tags: [attack-surface, market-research, {topic-tags}]
|
||||
---
|
||||
|
||||
# Attack Surface: {Topic}
|
||||
|
||||
## Executive Summary
|
||||
[3-5 bullet points with the most important findings]
|
||||
|
||||
## Research Brief
|
||||
[From Phase 1]
|
||||
|
||||
## Source Dossier Summary
|
||||
[From Phase 2 — source counts and key themes]
|
||||
|
||||
## Unspoken Insights
|
||||
[From Phase 3]
|
||||
|
||||
## Fragile Assumptions
|
||||
[From Phase 4 — the assumption map]
|
||||
|
||||
## Investor Stress-Test
|
||||
[From Phase 5 — questions, answers, confidence levels]
|
||||
|
||||
## Opportunity Matrix
|
||||
[From Phase 6]
|
||||
|
||||
## Action Plan
|
||||
[From Phase 7]
|
||||
|
||||
## Raw Sources
|
||||
[Links to all sources consulted]
|
||||
```
|
||||
|
||||
Save to the project root as `RESEARCH-YYYY-MM-DD-attack-surface-{slug}.md`. Tell the user the file path and offer to discuss any findings further.
|
||||
|
||||
---
|
||||
|
||||
## Subagent Instructions
|
||||
|
||||
All subagents use the `general-purpose` subagent type via the Agent tool. Read the reference files for detailed prompt templates:
|
||||
|
||||
- `references/gatherer-prompt.md` — Prompt template for Phase 2 source collection subagents
|
||||
- `references/analyst-prompt.md` — Prompt templates for Phases 3-6 analysis subagents
|
||||
|
||||
When launching subagents:
|
||||
- Phase 2: Launch 4-6 gatherers **in parallel** (one Agent tool call per search focus)
|
||||
- Phases 3-6: Launch **sequentially** (each builds on prior results)
|
||||
- Always pass the full Source Dossier to analysis subagents
|
||||
- Set `run_in_background: false` for analysis subagents (need results before proceeding)
|
||||
- Always include the search tool instructions (Exa vs WebSearch) in subagent prompts
|
||||
|
||||
### Token Budget
|
||||
|
||||
This skill launches 6-10 subagent calls total. Estimated cost:
|
||||
- Phase 2: 4-6 subagents x ~5-15K tokens each
|
||||
- Phases 3-6: 4 subagents x ~10-20K tokens each
|
||||
- Total: ~60-150K tokens per full research session
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
| Mistake | Fix |
|
||||
|---------|-----|
|
||||
| Skipping Phase 1 briefing | The research brief focuses everything — never skip |
|
||||
| Generic searches | Use specific, targeted queries from the research brief |
|
||||
| Presenting analysis without evidence | Every insight must cite specific sources |
|
||||
| Moving past weak stress-test answers | Always run iterative deepening on weak answers |
|
||||
| Forgetting to save | Always save the final document at the end |
|
||||
| Ignoring user-provided sources | Crawl them FIRST — the user chose them for a reason |
|
||||
| Not testing Exa availability | Always test before launching parallel subagents |
|
||||
@@ -0,0 +1,151 @@
|
||||
# Analysis Subagent — Prompt Templates
|
||||
|
||||
Use these templates when launching Phases 3-6 analysis subagents. Each receives the Source Dossier and prior analysis results. All analysis subagents should use `general-purpose` subagent type.
|
||||
|
||||
---
|
||||
|
||||
## Section: Unspoken Insights (Phase 3)
|
||||
|
||||
```
|
||||
You are a strategic analyst conducting deep market research.
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Source Dossier:
|
||||
{FULL_SOURCE_DOSSIER}
|
||||
|
||||
Your task: Answer this question with rigorous evidence from the sources above:
|
||||
|
||||
"What does every successful player in this market understand that their customers never say out loud?"
|
||||
|
||||
This isn't about features or pricing. It's about the deeper truths — the things that take founders 2 years of customer calls to figure out. The psychological patterns, the hidden motivations, the unspoken expectations.
|
||||
|
||||
Look for:
|
||||
- Patterns in what successful companies do but don't advertise
|
||||
- Gaps between what customers SAY they want and what they actually pay for
|
||||
- Emotional undercurrents in customer complaints and reviews
|
||||
- Things competitors all do the same way (unspoken consensus)
|
||||
- Customer behaviors that contradict their stated preferences
|
||||
|
||||
Return exactly 3-5 insights. For each:
|
||||
1. **The insight** — one clear, provocative sentence
|
||||
2. **Evidence** — 2-3 specific quotes or data points from the sources, with source URLs
|
||||
3. **Strategic implication** — why this matters for someone entering or competing in this market
|
||||
|
||||
Be specific and evidence-based. Generic observations like "customers want a good user experience" are worthless. We need insights that would make an industry veteran say "it took me years to figure that out."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section: Fragile Assumptions (Phase 4)
|
||||
|
||||
```
|
||||
You are a strategic analyst mapping the attack surface of a market.
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Source Dossier:
|
||||
{FULL_SOURCE_DOSSIER}
|
||||
|
||||
Prior analysis — Unspoken Insights:
|
||||
{PHASE_3_RESULTS}
|
||||
|
||||
Your task: Answer this question:
|
||||
|
||||
"What are the 3-5 assumptions this entire market is built on, and what would have to be true for each one to be wrong?"
|
||||
|
||||
Every market operates on a set of shared beliefs that nobody questions. These are the load-bearing assumptions — if one breaks, the entire competitive landscape shifts. Your job is to find them.
|
||||
|
||||
Look for:
|
||||
- Pricing models everyone copies (is there a reason, or just convention?)
|
||||
- Distribution channels everyone uses (what if a new channel emerges?)
|
||||
- Customer segments everyone targets (who is being ignored?)
|
||||
- Technology choices everyone makes (what if the tech shifts?)
|
||||
- Business models everyone follows (what if a different model works?)
|
||||
- Regulations everyone plans around (what if they change?)
|
||||
|
||||
For each assumption, return:
|
||||
1. **The assumption** — what everyone in this market believes
|
||||
2. **Evidence it's currently true** — why this belief is reasonable today (cite sources)
|
||||
3. **Breaking conditions** — specific, concrete conditions that would make it false
|
||||
4. **Fragility score (1-5)** — how likely these conditions are in the next 2-3 years
|
||||
- 1 = rock solid, would take a black swan
|
||||
- 3 = plausible, early signals visible
|
||||
- 5 = already cracking, evidence of change in sources
|
||||
5. **If it breaks** — what happens to the market, who wins, who loses
|
||||
|
||||
Focus on assumptions scored 3-5. Those are the real attack surfaces.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section: Investor Stress-Test (Phase 5)
|
||||
|
||||
```
|
||||
You are a world-class venture investor reviewing a potential investment. Your reputation depends on finding fatal flaws BEFORE writing a check. You've seen 10,000 pitches and killed 9,900 of them.
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Source Dossier:
|
||||
{FULL_SOURCE_DOSSIER}
|
||||
|
||||
Prior analysis:
|
||||
- Unspoken Insights: {PHASE_3_RESULTS}
|
||||
- Fragile Assumptions: {PHASE_4_RESULTS}
|
||||
|
||||
Your task:
|
||||
|
||||
Step 1: Write 5 questions that would destroy this business idea. Not softballs — the questions that make founders sweat. The ones that expose whether they've really done their homework or are running on hope.
|
||||
|
||||
Step 2: Answer each question using ONLY the evidence in the Source Dossier and prior analysis. No hand-waving. If the evidence doesn't support a strong answer, say so.
|
||||
|
||||
For each of the 5 questions:
|
||||
1. **The killer question** — phrased as an investor would ask it, sharp and direct
|
||||
2. **The evidence-based answer** — using only our collected sources
|
||||
3. **Confidence level** — STRONG (evidence clearly supports), MODERATE (evidence partially supports), or WEAK (evidence is thin or contradictory)
|
||||
4. **Remaining risk** — what the answer doesn't fully address
|
||||
|
||||
Step 3: For any answer rated WEAK, follow up with:
|
||||
"What's the strongest possible version of the argument for this idea, and where does it still break?"
|
||||
|
||||
The goal is not to kill the idea — it's to stress-test it so thoroughly that whatever survives is genuinely defensible.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section: Opportunity Mapping (Phase 6)
|
||||
|
||||
```
|
||||
You are a strategic advisor synthesizing an entire research sprint into actionable opportunities.
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
All prior analysis:
|
||||
- Unspoken Insights: {PHASE_3_RESULTS}
|
||||
- Fragile Assumptions: {PHASE_4_RESULTS}
|
||||
- Investor Stress-Test: {PHASE_5_RESULTS}
|
||||
|
||||
Your task:
|
||||
|
||||
"Given all the unspoken insights, fragile assumptions, and blind spots we've found — what are the 3 highest-leverage entry points or strategic moves?"
|
||||
|
||||
For each opportunity:
|
||||
1. **The opportunity** — one clear sentence describing the strategic move
|
||||
2. **Why now** — what's changed (or changing) that makes this viable
|
||||
3. **Evidence** — specific findings from our research that support this
|
||||
4. **The moat** — what would make this defensible once established
|
||||
5. **Risk** — the biggest thing that could go wrong
|
||||
6. **Validation needed** — the cheapest, fastest experiment to test this before committing
|
||||
7. **Leverage score (1-5)** — how much impact relative to effort
|
||||
|
||||
Also identify:
|
||||
- **The contrarian opportunity** — the one that goes against market consensus but is supported by evidence
|
||||
- **The timing play** — the one that depends on getting the timing right (a fragile assumption about to break)
|
||||
- **The safe bet** — the one with the most evidence and lowest risk
|
||||
|
||||
Rank all opportunities by leverage score. Be honest about which ones are speculative vs. well-supported.
|
||||
```
|
||||
@@ -0,0 +1,187 @@
|
||||
# Source Gatherer — Subagent Prompt Templates
|
||||
|
||||
Use these templates when launching Phase 2 subagents. Each subagent gets a specific focus area and the research brief.
|
||||
|
||||
## Search Tool Instructions
|
||||
|
||||
Include ONE of these blocks at the top of every subagent prompt, depending on Exa availability:
|
||||
|
||||
### If Exa MCP is available:
|
||||
```
|
||||
SEARCH TOOLS: Use Exa MCP for all searches.
|
||||
- `mcp__exa__web_search_exa` — neural search, returns relevant results with snippets
|
||||
- `mcp__exa__crawling_exa` — crawl a URL to get full page content (use maxCharacters: 10000)
|
||||
- `mcp__exa__deep_researcher_start` + `mcp__exa__deep_researcher_check` — for comprehensive research queries
|
||||
```
|
||||
|
||||
### If Exa MCP is NOT available (fallback):
|
||||
```
|
||||
SEARCH TOOLS: Use built-in WebSearch and WebFetch.
|
||||
- `WebSearch` — search the web, returns result snippets. Run multiple searches with different queries.
|
||||
- `WebFetch` — fetch full page content from a URL. Use for competitor pages, articles, reviews.
|
||||
For each search, run 2-3 different query variations to maximize coverage.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template: Competitor Intelligence
|
||||
|
||||
```
|
||||
You are gathering competitive intelligence for a strategic research project.
|
||||
|
||||
{SEARCH_TOOL_INSTRUCTIONS}
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Your job: Find and analyze 5-8 competitor or key player websites in this market.
|
||||
|
||||
Search queries to try:
|
||||
- "{market} software/platform/tool"
|
||||
- "best {market} solutions {year}"
|
||||
- "alternatives to {known_competitor}" (if any known)
|
||||
- "{market} startup"
|
||||
|
||||
For each competitor found, crawl their landing page, pricing page, and about page.
|
||||
|
||||
For each competitor, extract and return:
|
||||
- Company name and URL
|
||||
- Value proposition (their main headline/pitch)
|
||||
- Target audience (who they're speaking to)
|
||||
- Key features (top 5-10)
|
||||
- Pricing model (if visible)
|
||||
- Positioning language (how they differentiate)
|
||||
- Notable claims or promises
|
||||
|
||||
Return a structured report with all competitors analyzed. Include direct quotes from their sites.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template: Customer Voice
|
||||
|
||||
```
|
||||
You are gathering customer sentiment for a strategic research project.
|
||||
|
||||
{SEARCH_TOOL_INSTRUCTIONS}
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Your job: Find genuine customer opinions — complaints, praise, and unmet needs.
|
||||
|
||||
Search queries to try:
|
||||
- "reddit {market} complaints"
|
||||
- "reddit {market} frustrating"
|
||||
- "reddit {market} switched from {competitor}"
|
||||
- "{competitor} review" or "{competitor} problems"
|
||||
- "site:producthunt.com {market}"
|
||||
- "{market} customer reviews G2 Trustpilot"
|
||||
|
||||
Crawl the most relevant results to get full content.
|
||||
|
||||
Extract and categorize:
|
||||
- **Recurring pain points** (what comes up again and again)
|
||||
- **Emotional triggers** (what makes people angry, excited, or frustrated)
|
||||
- **Feature requests** (what people wish existed)
|
||||
- **Switching triggers** (why people leave one solution for another)
|
||||
- **Praise patterns** (what people genuinely love)
|
||||
|
||||
Include direct quotes with source URLs. Raw customer language is more valuable than your summary — preserve the exact words people use.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template: Industry Analysis
|
||||
|
||||
```
|
||||
You are gathering industry-level intelligence for a strategic research project.
|
||||
|
||||
{SEARCH_TOOL_INSTRUCTIONS}
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Your job: Find broad industry context — market size, trends, expert analysis.
|
||||
|
||||
Search queries to try:
|
||||
- "{market} market size growth trends {year}"
|
||||
- "{market} industry report"
|
||||
- "{market} market analysis {year}"
|
||||
- "{major_company} earnings call {market}" (if applicable)
|
||||
- "{market} regulatory changes"
|
||||
- "{market} technology disruption"
|
||||
|
||||
If using Exa, also use `deep_researcher_start` with model `exa-research-pro` for comprehensive coverage.
|
||||
|
||||
Extract:
|
||||
- **Market size and growth** (TAM/SAM/SOM if available)
|
||||
- **Key trends** (what's changing in this market)
|
||||
- **Regulatory landscape** (any regulations that matter)
|
||||
- **Technology shifts** (what new tech is enabling or disrupting)
|
||||
- **Expert predictions** (what industry analysts say is coming)
|
||||
- **Funding patterns** (who's investing, how much, in what)
|
||||
|
||||
Cite specific numbers and sources. Vague claims like "the market is growing" without data are useless.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template: Adjacent & Emerging
|
||||
|
||||
```
|
||||
You are scanning for emerging threats and adjacent opportunities for a strategic research project.
|
||||
|
||||
{SEARCH_TOOL_INSTRUCTIONS}
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Your job: Find what's coming next — new entrants, adjacent markets, and potential disruptors.
|
||||
|
||||
Search queries to try:
|
||||
- "{market} startup {year}"
|
||||
- "{market} new entrant funding"
|
||||
- "pivot to {market}"
|
||||
- "{adjacent_market} expanding into {market}"
|
||||
- "AI {market}" or "{market} automation"
|
||||
- "Y Combinator {market}" or "TechCrunch {market} {year}"
|
||||
|
||||
Crawl the most promising results.
|
||||
|
||||
Extract:
|
||||
- **New entrants** (startups launched in last 2 years)
|
||||
- **Adjacent threats** (companies from other markets that could enter)
|
||||
- **Technology disruptors** (new tech that could change the game)
|
||||
- **Pivot signals** (companies pivoting toward this market)
|
||||
- **Funding patterns** (recent funding rounds in this space)
|
||||
- **Unconventional approaches** (anyone doing something radically different)
|
||||
|
||||
Focus on what nobody in the established market is paying attention to yet.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template: User-Provided Sources
|
||||
|
||||
```
|
||||
You are extracting content from sources provided by the user for a strategic research project.
|
||||
|
||||
{SEARCH_TOOL_INSTRUCTIONS}
|
||||
|
||||
Research brief:
|
||||
{RESEARCH_BRIEF}
|
||||
|
||||
Sources to crawl:
|
||||
{LIST_OF_URLS_OR_FILES}
|
||||
|
||||
Your job: Extract full content from each source. For URLs, use crawling tools (Exa crawling or WebFetch). For local files, use the Read tool.
|
||||
|
||||
For each source, return:
|
||||
- Source URL/path
|
||||
- Title
|
||||
- Full extracted content (preserve structure)
|
||||
- Key takeaways relevant to the research brief (3-5 bullet points per source)
|
||||
|
||||
These are sources the user specifically chose — they contain information the user considers important. Extract everything.
|
||||
```
|
||||
Reference in New Issue
Block a user