@soleri/forge 9.3.0 → 9.4.0

package/src/skills/agent-issues/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: agent-issues
+description: >
+  Use when creating GitHub issues, bugs, tasks, or milestones that will be
+  worked on by AI coding agents. Triggers on: "create issue", "file bug",
+  "gh issue", "add milestone", "create task", "report bug", "gh tasks",
+  "create tasks", "create tickets", "file tickets", or when generating
+  structured work items from conversation context.
+---
+
+
+# Agent-Optimized Issue Creation
+
+Create GitHub issues that AI agents can parse, execute, and verify without ambiguity. Every issue is a self-contained work order — an agent reading it has everything needed to start, execute, and prove completion.
+
+## Core Principle
+
+**Human issues describe problems. Agent issues describe solutions as testable outcomes.**
+
+An agent cannot act on "improve avatar handling." It can act on: "Add PNG upload to `POST /v1/avatar` in `apps/api/src/routes/avatar.ts`, return `{ avatarUrl }`, reject files > 2MB with 413."
+
+## When to Use
+
+- Creating any GitHub issue via `gh issue create`
+- Filing bugs from conversation context or error logs
+- Breaking plans into trackable work items
+- Creating milestones with sub-issues
+- Converting vault patterns or anti-patterns into actionable fixes
+
+## Issue Template by Type
+
+### Bug
+
+```markdown
+# Objective
+<one sentence: what's broken and what "fixed" looks like>
+
+## Type: bug
+## Component: <package or module name>
+## Priority: P0 | P1 | P2 | P3
+
+## Context
+- Impact: <who/what is affected>
+- Related: <links to issues, PRs, vault entries>
+- First seen: <date or commit>
+
+## Steps to Reproduce
+1. <exact command or action>
+2. <exact command or action>
+3. Observe: <what happens>
+
+## Expected vs Actual
+| | Behavior |
+|--|----------|
+| **Expected** | <correct behavior> |
+| **Actual** | <broken behavior> |
+
+## Error Output
+```
+<paste exact error, stack trace, or log output>
+```
+
+## Root Cause (if known)
+- File: `path/to/file.ts` — `functionName()` or line reference
+- Why: <brief technical explanation>
+
+## Scope
+| In | Out |
+|----|-----|
+| Fix the specific bug | Refactoring surrounding code |
+| Add regression test | Performance optimization |
+
+## Code Locations
+- Bug site: `path/to/file.ts` — `symbolName`
+- Test file: `path/to/file.test.ts`
+- Related: `path/to/related.ts` — `relatedSymbol`
+
+## Acceptance Criteria
+- [ ] Bug no longer reproduces with steps above
+- [ ] Regression test added that fails without fix, passes with fix
+- [ ] No new lint/type errors
+- [ ] Existing tests pass
+
+## Verification
+```bash
+<exact test command>
+<exact build/lint command>
+```
+```
+
+### Feature
+
+```markdown
+# Objective
+<one sentence: what capability is added and why>
+
+## Type: feature
+## Component: <package or module name>
+## Priority: P0 | P1 | P2 | P3
+
+## Context
+- Why: <user need or business reason>
+- Related: <links to issues, PRs, vault entries, specs>
+
+## Scope
+| In | Out |
+|----|-----|
+| <specific deliverable> | <what NOT to touch> |
+
+## Constraints
+- Backward compatibility: <requirements>
+- Dependencies: <allowed/forbidden>
+- Performance: <budgets if any>
+- Security: <requirements if any>
+
+## Code Locations
+- Entry point: `path/to/file.ts` — `functionOrClass`
+- Integration point: `path/to/other.ts` — `symbol`
+- Test location: `path/to/test.ts`
+
+## Proposed Approach (optional)
+1. <step>
+2. <step>
+
+## Acceptance Criteria
+- [ ] Given <precondition>, when <action>, then <result>
+- [ ] Given <precondition>, when <action>, then <result>
+- [ ] Tests added for new behavior
+- [ ] Types exported if public API
+
+## Verification
+```bash
+<exact test command>
+<exact build command>
+```
+
+## Definition of Done
+- [ ] Acceptance criteria satisfied
+- [ ] `npm test` passes
+- [ ] `npm run typecheck` passes
+- [ ] Changes scoped to "In Scope" only
+```
+
+### Milestone
+
+```markdown
+# Milestone: <short title>
+
+## Objective
+<one sentence: what this milestone achieves>
+
+## Timeline
+- Target: <date>
+- Depends on: <blocking milestones or external factors>
+
+## Sub-Issues
+
+| # | Type | Title | Priority | Depends On |
+|---|------|-------|----------|------------|
+| 1 | feature | <title> | P1 | — |
+| 2 | feature | <title> | P1 | #1 |
+| 3 | bug | <title> | P2 | — |
+
+## Completion Criteria
+- [ ] All sub-issues closed
+- [ ] Integration test passes end-to-end
+- [ ] <milestone-level verification>
+```
+
+## Field Guide
+
+### Writing Good Objectives
+
+| Bad | Good |
+|-----|------|
+| "Fix the login" | "Login returns 401 instead of session token when OAuth callback has valid code" |
+| "Add dark mode" | "Add `prefers-color-scheme` media query support to all semantic color tokens" |
+| "Improve performance" | "Reduce cold-start vault search from 800ms to <200ms by lazy-loading FTS index" |
+
+### Writing Good Acceptance Criteria
+
+Use Given/When/Then for behavioral criteria. Use plain checkboxes for structural criteria.
+
+**Behavioral:**
+- [ ] Given a user with valid OAuth code, when POST /auth/callback, then returns 200 with session token
+
+**Structural:**
+- [ ] Unit test covers happy path + error case
+- [ ] No new `any` types introduced
+- [ ] Public API documented in JSDoc
+
+### Writing Good Code Locations
+
+Always include:
+1. **File path** — repo-root relative
+2. **Anchor** — function name, class name, route, or config key
+3. **Context** — what the agent should look at there
+
+```
+- Handler: `packages/core/src/auth/callback.ts` — `handleOAuthCallback()`
+- Token logic: `packages/core/src/auth/session.ts` — `createSession()`
+- Test: `packages/core/src/__tests__/auth.test.ts` — "OAuth callback" describe block
+```
+
+### Constraints That Prevent Agent Overreach
+
+Be explicit about boundaries. Agents optimize globally unless told not to.
+
+```
+## Constraints
+- Do NOT modify the public API surface of `@soleri/core`
+- Do NOT add new npm dependencies
+- Do NOT refactor surrounding code — fix only the bug
+- Backward compatible: existing agent.yaml files must still work
+```
+
+## Workflow
+
+1. **Gather context** — search vault, read error logs, check git blame
+2. **Identify code locations** — grep codebase for relevant symbols
+3. **Choose template** — bug, feature, or milestone
+4. **Fill template** — every field. Skip none.
+5. **Create issue** — `gh issue create --title "..." --body "..." --label "..."`
+
+## Integration with Planning
+
+When creating issues from a plan, the plan is the source of truth — GitHub issues are the projection. Each task becomes a lean issue pointing back to the plan.
+
+### Plan-Sourced Task Template
+
+```markdown
+# Objective
+<one sentence: what this task delivers>
+
+## Plan: `<plan-id>` | Task <N> of <total>
+## Parent: #<epic-issue-number>
+## Complexity: Low | Medium | High
+## Depends on: <task dependencies or "nothing">
+
+## Code Locations
+- `path/to/file.ts` — `symbolOrFunction`
+
+## Acceptance Criteria
+- [ ] <testable outcome>
+- [ ] <testable outcome>
+- [ ] Tests pass
+
+## Verification
+```bash
+<exact command>
+```
+```
+
+### Rules for Plan-Sourced Issues
+
+1. **Plan ID is mandatory** — every task issue must include `## Plan: \`<plan-id>\`` so the full plan is one API call away
+2. **Keep issues lean** — task description + code locations + acceptance criteria
+3. **One issue per task** — don't bundle multiple plan tasks into one issue
+4. **Parent/epic issue** — create a parent issue that lists all task issues
+5. **Map complexity to priority** — High → P1, Medium → P2, Low → P3
+6. **Include task number** — "Task 3 of 11" helps track progress
+
+## Labels
+
+Always apply at least:
+- Type: `bug`, `feature`, `refactor`, `chore`
+- Priority: `P0`, `P1`, `P2`, `P3` (if using priority labels)
+- Component: package or module name (if using component labels)

package/src/skills/agent-persona/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: agent-persona
+description: >
+  Use when the user activates the agent's persona via its greeting phrase, or says
+  "activate persona", "be yourself", "stay in character", or any activation phrase
+  defined in the agent's persona configuration. Reinforces character persistence
+  through the session and survives context compaction.
+---
+
+# Agent Persona — Stay in Character
+
+This skill reinforces persona persistence. The MCP activation loads the runtime payload — this skill ensures the character sticks across the full session, including after context compaction.
+
+## How It Works
+
+Every agent has a persona defined in `agent.yaml`. The persona contains:
+
+- **name** — the agent's display name
+- **role** — what the agent does
+- **tone** — `precise`, `mentor`, or `pragmatic`
+- **greeting** — the activation response
+- **principles** — core values that guide behavior
+
+## Activation
+
+When the user triggers activation (greeting phrase or explicit request):
+
+```
+YOUR_AGENT_core op:activate
+  params: { projectPath: "." }
+```
+
+The activation response contains the full persona payload. Adopt it immediately.
+
+## Rules
+
+1. **Stay in character for EVERY response** until the user explicitly deactivates
+2. **Technical accuracy is the priority** — persona is the wrapper, not a replacement for correctness
+3. **Tone consistency** — match the configured tone (`precise` = concise and exact, `mentor` = educational and encouraging, `pragmatic` = direct and practical)
+4. If character drifts after context compaction, the persona information in the compacted summary should restore it — follow it
+
+## Context Compaction Survival
+
+Long sessions trigger context compaction. To survive:
+
+- The persona activation state is included in compaction summaries
+- After compaction, check if persona was active and re-adopt the character
+- Never break character just because the conversation was compacted
+
+## Deactivation
+
+When the user says "deactivate", "stop persona", "be normal", or uses the agent's deactivation phrase:
+
+```
+YOUR_AGENT_core op:activate
+  params: { deactivate: true }
+```
+
+Return to neutral assistant mode.
+
+## Anti-Patterns
+
+- **Dropping character mid-session** — if activated, stay activated
+- **Over-persona, under-substance** — character adds flavor, not replaces technical depth
+- **Forcing persona on unwilling users** — only activate when explicitly triggered
+- **Ignoring tone setting** — a `precise` agent should not use flowery language; a `mentor` agent should not be terse

package/src/skills/deep-review/SKILL.md

@@ -188,6 +188,18 @@ Only capture if genuinely reusable — not every review finding is vault-worthy.
 - Skipping git history (temporal smells are the most actionable)
 - Treating all smells as equal severity (prioritize by impact)
 
+## Rationalization Prevention
+
+Do NOT rationalize away findings. If a smell or issue is detected, report it honestly.
+
+- **HARD-GATE: All three passes must complete before presenting the report. Do not skip a pass.**
+- **HARD-GATE: Critical (red) findings must be flagged -- never downgrade severity to avoid difficult conversations.**
+- Do not say "this is probably fine" to dismiss a code smell you detected.
+- Do not omit findings because "the code works" -- working code can still be poorly architected.
+- Do not soften severity because the code is recent or written by the user.
+- If git history shows high churn, report it. Do not skip temporal smells for convenience.
+- Present the full picture. A review that hides problems is worse than no review.
+
 ## Quick Reference
 
 | Pass            | Focus            | Key Activities                                              |

package/src/skills/deliver-and-ship/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: deliver-and-ship
+description: >
+  Use when the user says "ship it", "ready to deploy", "package", "release",
+  "pre-PR check", "delivery checklist", "is this ready", "final review", or mentions
+  shipping, deploying, packaging, or releasing work. Runs pre-delivery quality gates
+  to ensure nothing ships without passing stability, knowledge capture, and code quality checks.
+---
+
+# Deliver & Ship — Quality Gate Runner
+
+Run all pre-delivery quality gates before shipping. This ensures nothing leaves without passing stability checks, knowledge capture, and code quality verification.
+
+## When to Use
+
+When work is considered "done" and ready to be committed, PR'd, or deployed. This is the last checkpoint before code leaves the developer's hands.
+
+## Orchestration Sequence
+
+### Step 1: Code Quality
+
+Run the project's linter, formatter, and type checker on all modified files:
+
+1. Check for lint/format scripts in `package.json` (or equivalent)
+2. Run `typecheck` / `tsc --noEmit` if TypeScript
+3. Run any project-specific quality gates (clippy for Rust, mypy for Python, etc.)
+
+Any type error or lint failure is a blocker.
+
+### Step 2: Test Suite
+
+Run the full test suite to catch regressions:
+
+```
+YOUR_AGENT_core op:admin_health
+```
+
+Verify the agent itself is healthy, then run project tests. All tests must pass.
+
+### Step 3: Stability Assessment
+
+Classify the changes as safe or breaking:
+
+- **Safe**: Internal refactors, bug fixes, additive features (new exports, new ops)
+- **Breaking**: Removed exports, changed signatures, renamed public APIs, schema migrations
+- Breaking changes need migration guidance in the commit/PR description
+
+### Step 4: Knowledge Audit
+
+Check if patterns discovered during this work session should be captured before shipping:
+
+```
+YOUR_AGENT_core op:memory_search
+  params: { query: "current session" }
+```
+
+```
+YOUR_AGENT_core op:brain_stats
+```
+
+Look for:
+
+- Bug fixes that reveal an anti-pattern worth capturing
+- New patterns that should be in the vault for next time
+- Architectural decisions that need documenting
+
+Uncaptured knowledge is lost knowledge. If something should be captured:
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<what was learned>",
+    description: "<the pattern or anti-pattern>",
+    type: "pattern",
+    tags: ["<relevant-tags>"]
+  }
+```
+
+### Step 5: Commit Quality
+
+Verify commit messages follow conventional commits:
+
+- `feat:` for new features
+- `fix:` for bug fixes
+- `refactor:` for refactors
+- `chore:` for maintenance
+- No AI attribution (blocked by engine rules)
+
+### Step 6: Delivery Report
+
+Present a checklist:
+
+- [ ] Code quality: pass/fail (Step 1)
+- [ ] Tests: pass/fail (Step 2)
+- [ ] Stability: safe change / breaking change (Step 3)
+- [ ] Knowledge: captured / needs capture (Step 4)
+- [ ] Commits: clean / needs cleanup (Step 5)
+
+All items must pass before recommending "ship it."
+
+## Domain-Specific Gates
+
+Agents with domain-specific facades may add extra gates. For example:
+
+- **Design system agents**: token validation, contrast checks, accessibility audit
+- **API agents**: schema validation, backward compatibility checks
+- **Security agents**: dependency audit, secret scanning
+
+These are additive — they don't replace the generic gates above.
+
+## Exit Criteria
+
+Delivery is approved when all gates pass. If any gate fails, report the failure and recommend fixes before shipping. Never approve delivery with blocking issues.
+
+## Agent Tools Reference
+
+| Op                  | When to Use                            |
+| ------------------- | -------------------------------------- |
+| `admin_health`      | Verify agent/system health             |
+| `memory_search`     | Check for uncaptured session knowledge |
+| `brain_stats`       | Review learning state                  |
+| `capture_knowledge` | Persist patterns before shipping       |
+| `capture_quick`     | Fast capture for simple learnings      |

package/src/skills/discovery-phase/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: discovery-phase
+description: >
+  Use for structured exploration before committing to a plan — "I don't know where to start",
+  "what are our options", "investigate", "research this", "explore options", "discovery". Ideal
+  when requirements are unclear, entering a new domain, or facing architectural decisions. Produces
+  a discovery document with options, tradeoffs, and a recommendation.
+---
+
+# Discovery Phase
+
+Structured exploration before committing to a plan. Define the question, research prior art, explore the codebase, identify constraints, draft options with tradeoffs, and recommend a path forward.
+
+<HARD-GATE>
+Do NOT create a plan, write code, or take any implementation action until the discovery document is complete and the user has reviewed it. Discovery produces knowledge, not artifacts.
+</HARD-GATE>
+
+## Checklist
+
+1. **Define the question** — restate what we're exploring as one specific, answerable sentence
+2. **Search vault for prior art** — `YOUR_AGENT_core op:search_intelligent params: { query: "<question>", mode: "scan" }`. Also `op:memory_search` with `crossProject: true`.
+3. **Explore codebase** — read relevant files, configs, architecture, recent commits
+4. **Identify constraints** — hard (must-haves) vs soft (nice-to-haves), unknowns that block a decision
+5. **Draft 2-4 options** — each with pros, cons, risk, and effort (S/M/L)
+6. **Recommend** — pick one, state the primary reason, note what would change the answer
+7. **Capture to vault** — persist the discovery finding
+8. **Transition** — hand off to brainstorming or writing-plans skill
+
+## Option Format
+
+For each option:
+
+| Field | Content |
+| ----- | ------- |
+| **Approach** | One-sentence summary |
+| **Pros** | What it gives us |
+| **Cons** | What it costs |
+| **Risk** | What could go wrong |
+| **Effort** | S / M / L |
+
+## After Discovery
+
+```
+YOUR_AGENT_core op:capture_knowledge
+  params: {
+    title: "<topic> — discovery finding",
+    description: "<question, options considered, recommendation, rationale>",
+    type: "decision",
+    category: "<domain>",
+    tags: ["discovery", "decision"]
+  }
+```
+
+Save to `docs/discoveries/YYYY-MM-DD-<topic>.md` and commit. Then transition to the next skill.
+
+## Anti-Patterns
+
+- **Skipping discovery** — jumping to implementation when the problem space is unclear
+- **Analysis paralysis** — timebox to 30-60 min; if no clear winner, pick the most reversible option
+- **Boiling the ocean** — scope to one question; split compound questions into separate discoveries
+
+## Quick Reference
+
+| Op                   | When to Use                        |
+| -------------------- | ---------------------------------- |
+| `search_intelligent` | Search vault for prior art         |
+| `memory_search`      | Check session history and projects |
+| `capture_knowledge`  | Persist discovery finding          |
+| `route_intent`       | Classify what comes after          |

package/src/skills/env-setup/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: env-setup
+description: >
+  Use when a developer needs to set up, fix, or restore a local development environment.
+  Triggers on post-clone setup, project onboarding, first-time running a repo, pulled changes
+  that broke the build, missing or misconfigured dependencies, MODULE_NOT_FOUND or Cannot find
+  module errors, gyp ERR or native module build failures, missing .env files or unknown required
+  environment variables, database setup, Docker compose issues, or connection refused during
+  local dev. Covers Node.js, Python, Rust, Go, Ruby, PHP, and Docker-based projects.
+---
+
+# Environment Setup
+
+Detect what a project needs, diagnose what's missing, and produce an actionable setup checklist.
+
+## Overview
+
+Scan the project root for configuration files, detect the tech stack and dependencies, identify gaps between what's required and what's present, then generate ordered setup steps. Offer to execute each step.
+
+## When to Use
+
+- Just cloned a repo and need to get it running
+- Getting errors after pulling changes (missing deps, env vars, DB migrations)
+- Onboarding to an unfamiliar project
+- Setting up a project on a new machine
+- Docker/container environment not starting
+- Missing `.env` file or environment variables
+
+## Detection Phase
+
+Scan the project root and identify:
+
+### Package Managers & Dependencies
+
+| File               | Stack   | Install Command                                              |
+| ------------------ | ------- | ------------------------------------------------------------ |
+| `package.json`     | Node.js | `npm install` / `yarn` / `pnpm install` (check for lockfile) |
+| `requirements.txt` | Python  | `pip install -r requirements.txt`                            |
+| `pyproject.toml`   | Python  | `pip install -e .` or `poetry install` or `uv sync`          |
+| `Pipfile`          | Python  | `pipenv install`                                             |
+| `Cargo.toml`       | Rust    | `cargo build`                                                |
+| `go.mod`           | Go      | `go mod download`                                            |
+| `Gemfile`          | Ruby    | `bundle install`                                             |
+| `composer.json`    | PHP     | `composer install`                                           |
+
+**Lockfile priority:** If a lockfile exists (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Pipfile.lock`, `poetry.lock`), use the matching package manager. Don't mix.
+
+### Environment Variables
+
+1. Check for `.env.example`, `.env.sample`, `.env.template`
+2. Check for existing `.env` — if missing, copy from template
+3. Parse template for required variables (lines without defaults or with placeholder values)
+4. Flag variables that need real values (API keys, secrets, database URLs)
+5. **If no template exists:** grep source for `process.env.`, `os.environ`, `env::var`, `os.Getenv` to discover env vars the project actually uses.
+
+### Native Dependencies
+
+| Indicator                                | What It Means                          |
+| ---------------------------------------- | -------------------------------------- |
+| `better-sqlite3`, `sqlite3` in deps      | Needs C++ compiler                     |
+| `node-gyp` in deps or scripts            | Needs Python 3 + C++ toolchain         |
+| `sharp` in deps                          | Needs `libvips`                        |
+| `Cargo.toml` with `[build-dependencies]` | Needs Rust toolchain for build scripts |
+| `setup.py` with `ext_modules`            | Needs C compiler for Python extensions |
+
+### Databases
+
+| File/Config                              | Database         | Setup Needed                 |
+| ---------------------------------------- | ---------------- | ---------------------------- |
+| `docker-compose.yml` with postgres/mysql | PostgreSQL/MySQL | Container + migrations       |
+| `prisma/schema.prisma`                   | Prisma-managed   | `npx prisma migrate dev`     |
+| `drizzle.config.*`                       | Drizzle-managed  | `npx drizzle-kit push`       |
+| `alembic.ini`                            | SQLAlchemy       | `alembic upgrade head`       |
+| `config/database.yml`                    | Rails            | `rails db:create db:migrate` |
+
+### Infrastructure
+
+| File                                          | What It Means                               |
+| --------------------------------------------- | ------------------------------------------- |
+| `docker-compose.yml`                          | Services to start with `docker compose up`  |
+| `Dockerfile`                                  | Can build container locally                 |
+| `Makefile`                                    | Check for `setup`, `install`, `dev` targets |
+| `.tool-versions` / `.node-version` / `.nvmrc` | Required runtime version                    |
+| `turbo.json` / `nx.json` / `lerna.json`       | Monorepo setup                              |
+
+### IDE & Tool Integration
+
+| File                     | Integration                  |
+| ------------------------ | ---------------------------- |
+| `.vscode/`               | VS Code settings, extensions |
+| `.mcp.json` / `mcp.json` | MCP server config            |
+| `.editorconfig`          | Cross-editor formatting      |
+
+## Diagnosis Phase
+
+After detection, check what's present vs needed:
+
+1. **Runtime version** — does installed version match version files?
+2. **Dependencies installed?** — does `node_modules/`, `venv/`, `vendor/` exist?
+3. **Native build tools?** — are compilers available?
+4. **Env file present?** — does `.env` exist when a template does?
+5. **Database reachable?** — can the configured DB URL connect?
+6. **Docker running?** — is Docker daemon running if needed?
+7. **Build artifacts** — does the project need an initial build step?
+
+## Checklist Generation
+
+Produce steps in dependency order:
+
+```
+## Setup Checklist
+
+1. [ ] Install runtime (Node 20.x via nvm)
+2. [ ] Install dependencies (pnpm install)
+3. [ ] Copy environment file (cp .env.example .env)
+4. [ ] Fill in required env vars: DATABASE_URL, API_KEY
+5. [ ] Start Docker services (docker compose up -d)
+6. [ ] Run database migrations (npx prisma migrate dev)
+7. [ ] Build the project (pnpm build)
+8. [ ] Start dev server (pnpm dev)
+```
+
+**Order matters:** runtime -> deps -> env -> infrastructure -> migrations -> build -> run.
+
+After presenting the checklist, offer: "Want me to run these steps for you?"
+
+## Execution Phase
+
+If the user says yes, execute steps sequentially. Stop and ask if:
+
+- A step fails
+- A step requires manual input (API keys, passwords)
+- A step would modify system-level config (global installs, PATH changes)
+
+## Monorepo Handling
+
+If monorepo detected (turbo.json, nx.json, pnpm-workspace.yaml):
+
+1. Install root dependencies first
+2. Ask which package/app the user wants to work on
+3. Check for package-specific setup
+4. Run package-specific setup after root
+
+## Common Mistakes
+
+- **Wrong package manager** — using `npm install` when `yarn.lock` exists. Always check lockfiles first.
+- **Skipping env file** — project crashes on first API call. Always check for templates.
+- **Missing native build tools** — `npm install` fails with gyp errors. Check before installing.
+- **Missing runtime version** — subtle bugs from wrong Node/Python version.
+- **Docker not running** — cryptic "connection refused" errors.
+- **Stale dependencies** — after `git pull`, always re-install if lockfile changed.