@zigrivers/scaffold 2.1.1 → 2.28.1

package/knowledge/core/task-decomposition.md

@@ -4,11 +4,45 @@ description: Breaking architecture into implementable tasks with dependency anal
 topics: [tasks, decomposition, dependencies, user-stories, parallelization, sizing, critical-path]
 ---
 
-## User Stories to Tasks
+# Task Decomposition
 
-> **Note:** User stories are created as an upstream artifact in the pre-pipeline phase and available at `docs/user-stories.md`. This section covers how to consume stories and derive implementation tasks from them.
+Expert knowledge for breaking user stories into implementable tasks with dependency analysis, sizing, parallelization, and agent context requirements.
+
+## Summary
+
+### Story-to-Task Mapping
+
+User stories bridge PRD features and implementation tasks. Each story decomposes into tasks following the technical layers needed. Every task must trace back to a user story, and every story to a PRD feature (PRD Feature → US-xxx → Task BD-xxx).
+
+### Task Sizing
+
+Each task should be completable in a single AI agent session (30-90 minutes of agent time). A well-sized task has a clear title (usable as commit message), touches 1-5 files, produces a testable result, and has no ambiguity about "done."
+
+Split large tasks by layer (API, UI, DB, tests), by feature slice (happy path, validation, edge cases), or by entity. Combine tiny tasks that touch the same file and have no independent value.
+
+### Dependency Types
+
+- **Logical** — Task B requires Task A's output (endpoint needs DB schema)
+- **File contention** — Two tasks modify the same file (merge conflict risk)
+- **Infrastructure** — Task requires setup that must exist first (DB, auth, CI)
+- **Knowledge** — Task benefits from understanding gained in another task
+
+Only logical, file contention, and infrastructure dependencies should be formal constraints.
+
+### Definition of Done
+
+1. Acceptance criteria from the user story are met
+2. Unit tests pass (for new logic)
+3. Integration tests pass (for API endpoints or component interactions)
+4. No linting or type errors
+5. Code follows project coding standards
+6. Changes committed with proper message format
+
+## Deep Guidance
 
-### From Stories to Tasks
+### From Stories to Tasks — Extended
+
+> **Note:** User stories are created as an upstream artifact in the pre-pipeline phase and available at `docs/user-stories.md`. This section covers how to consume stories and derive implementation tasks from them.
 
 User stories bridge the gap between what the business wants (PRD features) and what developers build (implementation tasks). Every PRD feature maps to one or more user stories (created in the pre-pipeline), and every user story should map to one or more implementation tasks.
 
@@ -115,9 +149,9 @@ This traceability ensures:
 - No orphan tasks exist (every task serves a purpose)
 - Impact analysis is possible (changing a PRD feature reveals which tasks are affected)
 
-## Task Sizing
+### Task Sizing — Extended
 
-### Right-Sizing for Agent Sessions
+#### Right-Sizing for Agent Sessions
 
 Each task should be completable in a single AI agent session (typically 30-90 minutes of agent time). Tasks that are too large overflow the context window; tasks that are too small create unnecessary coordination overhead.
 
@@ -136,7 +170,7 @@ Each task should be completable in a single AI agent session (typically 30-90 mi
 | "Create Button component" | "Build form components (Input, Select, Textarea) with validation states" | "Create the full design system" |
 | "Add index to users table" | "Create database schema for user management with migration" | "Set up the entire database" |
 
-### Splitting Large Tasks
+#### Splitting Large Tasks
 
 When a task is too large, split along these axes:
 
@@ -163,7 +197,7 @@ When a task is too large, split along these axes:
 - The task involves more than 2 architectural boundaries (e.g., database + API + frontend + auth)
 - You can't describe what "done" looks like in 2-3 sentences
 
-### Combining Small Tasks
+#### Combining Small Tasks
 
 If multiple tiny tasks touch the same file and have no independent value, combine them:
 
@@ -172,20 +206,9 @@ If multiple tiny tasks touch the same file and have no independent value, combin
 
 The test: would the small task result in a useful commit on its own? If not, combine.
 
-### Definition of Done
-
-Every task needs a clear definition of done. Standard criteria:
-
-1. All acceptance criteria from the user story are met
-2. Unit tests pass (for new logic)
-3. Integration tests pass (for API endpoints or component interactions)
-4. No linting or type errors
-5. Code follows project coding standards
-6. Changes are committed with proper message format
-
-## Dependency Analysis
+### Dependency Analysis — Extended
 
-### Types of Dependencies
+#### Types of Dependencies
 
 **Logical dependencies:** Task B requires Task A's output. The API endpoint task depends on the database schema task because the endpoint queries tables that must exist first.
 
@@ -195,7 +218,7 @@ Every task needs a clear definition of done. Standard criteria:
 
 **Knowledge dependencies:** A task requires understanding gained from completing another task. The developer who builds the auth system understands the auth patterns needed by other features.
 
-### Building Dependency Graphs (DAGs)
+#### Building Dependency Graphs (DAGs)
 
 A dependency graph is a directed acyclic graph (DAG) where:
 - Nodes are tasks
@@ -210,7 +233,7 @@ A dependency graph is a directed acyclic graph (DAG) where:
 4. Draw an edge from producer to consumer
 5. Check for cycles (if A depends on B and B depends on A, something is wrong — split or reorganize)
 
-### Detecting Cycles
+#### Detecting Cycles
 
 Cycles indicate a modeling problem. Common causes and fixes:
 
@@ -218,7 +241,7 @@ Cycles indicate a modeling problem. Common causes and fixes:
 - **Feature interaction:** Feature X needs Feature Y's component, and Feature Y needs Feature X's component. Fix: extract the shared component into its own task.
 - **Testing dependency:** "Can't test A without B, can't test B without A." Fix: use mocks/stubs to break the cycle during testing. The integration test that tests both together becomes a separate task.
 
-### Finding Critical Path
+#### Finding Critical Path
 
 The critical path is the longest chain of dependent tasks from start to finish. It determines the minimum project duration.
 
@@ -235,7 +258,7 @@ The critical path is the longest chain of dependent tasks from start to finish.
 - To shorten the project, focus on splitting or accelerating critical-path tasks
 - Non-critical-path tasks have "float" — they can be delayed without affecting the project end date
 
-### Dependency Documentation
+#### Dependency Documentation
 
 For each dependency, document:
 
@@ -245,9 +268,9 @@ For each dependency, document:
 | BD-12 -> BD-13 | File contention | Both modify src/routes/index.ts | Medium — merge conflict risk |
 | BD-01 -> BD-* | Infrastructure | BD-01 sets up the database; everything needs it | High — blocks all work |
 
-## Parallelization
+### Parallelization and Wave Planning
 
-### Identifying Independent Tasks
+#### Identifying Independent Tasks
 
 Tasks are safe to run in parallel when:
 - They have no shared dependencies (no common prerequisite still in progress)
@@ -267,7 +290,7 @@ Tasks are safe to run in parallel when:
 - Tasks that modify the same shared utility file
 - Tasks where one produces test fixtures the other consumes
 
-### Managing Shared-State Tasks
+#### Managing Shared-State Tasks
 
 When tasks must share state (database, shared configuration, route registry):
 
@@ -277,7 +300,7 @@ When tasks must share state (database, shared configuration, route registry):
 
 **Feature flags:** Both tasks can merge independently. A feature flag controls which one is active. Integrate them in a separate task after both complete.
 
-### Merge Strategies for Parallel Work
+#### Merge Strategies for Parallel Work
 
 When parallel tasks produce branches that must be merged to main:
 
@@ -285,7 +308,7 @@ When parallel tasks produce branches that must be merged to main:
 - **First-in wins:** The first task to merge gets a clean merge. Subsequent tasks must rebase and resolve conflicts.
 - **Minimize shared files:** Design the task decomposition to minimize file overlap. Feature-based directory structure helps enormously.
 
-### Wave Planning
+#### Wave Planning
 
 Organize tasks into waves based on the dependency graph:
 
@@ -298,9 +321,9 @@ Wave 4 (depends on Wave 3): End-to-end tests, performance optimization, polish
 
 Each wave's tasks can run in parallel. Wave N+1 starts only when all its dependencies in Wave N are complete. The number of parallel agents should match the number of independent tasks in the current wave.
 
-## Agent Context
+### Agent Context Requirements
 
-### What Context Each Task Needs
+#### What Context Each Task Needs
 
 Every task description should specify what documents and code the implementing agent needs to read:
 
@@ -321,7 +344,7 @@ Produces:
 - tests/features/auth/register.integration.test.ts
 ```
 
-### Handoff Information
+#### Handoff Information
 
 When a task produces output that another task consumes, specify the handoff:
 
@@ -338,7 +361,7 @@ Consuming tasks:
   BD-30 (onboarding flow) expects the response shape above
 ```
 
-### Assumed Prior Work
+#### Assumed Prior Work
 
 Explicitly state what the agent can assume exists:
 
@@ -353,7 +376,7 @@ Does NOT assume:
 - Any auth endpoints exist (this is the first)
 ```
 
-## Common Pitfalls
+### Common Pitfalls
 
 **Tasks too vague.** "Implement backend" or "Set up auth" with no acceptance criteria, no file paths, and no test requirements. An agent receiving this task will guess wrong about scope, structure, and conventions. Fix: every task must specify exact files to create/modify, acceptance criteria, and test requirements.
 

package/knowledge/core/task-tracking.md

@@ -0,0 +1,225 @@
+---
+name: task-tracking
+description: Task tracking patterns including Beads methodology, task hierarchies, progress tracking, and lessons-learned workflows
+topics: [task-management, beads, progress-tracking, lessons-learned, autonomous-work]
+---
+
+# Task Tracking
+
+Structured task tracking for AI agents ensures work continuity across sessions, prevents drift, and builds institutional memory. This knowledge covers the Beads methodology, task hierarchies, progress conventions, and the lessons-learned workflow that turns mistakes into permanent improvements.
+
+## Summary
+
+### Beads Methodology Overview
+
+Beads is an AI-friendly issue tracker designed for single-developer and AI-agent workflows. Unlike heavyweight project management tools (Jira, Linear), Beads stores task data in the repository itself, making it accessible to AI agents without external API integration.
+
+Core properties:
+- **Repository-local** — Task data lives in `.beads/`, committed alongside code
+- **Git-hook synced** — Task state updates automatically on commit via data-sync hooks
+- **CLI-driven** — All operations via `bd` commands (create, list, status, ready)
+- **ID-prefixed commits** — Every commit message includes `[BD-xxx]` for traceability
+
+### Task Hierarchy
+
+Tasks organize into three levels:
+
+| Level | Scope | Example | Typical Count |
+|-------|-------|---------|---------------|
+| **Epic** | Large feature or milestone | "User authentication system" | 3-8 per project |
+| **Task** | Single agent session (30-90 min) | "Implement login endpoint with validation" | 10-50 per project |
+| **Subtask** | Atomic unit within a task | "Add password hashing util" | 0-5 per task |
+
+Epics group related tasks. Tasks are the unit of work assignment — one task per agent session. Subtasks are optional decomposition within a task, useful when a task has distinct testable steps.
+
+### Progress Tracking
+
+Track task status through a simple state machine:
+
+```
+ready → in-progress → review → done
+                  ↘ blocked
+```
+
+- **ready** — All dependencies met, can start immediately
+- **in-progress** — Agent is actively working on it
+- **review** — Implementation complete, awaiting PR merge
+- **done** — PR merged, tests passing on main
+- **blocked** — Cannot proceed, dependency or question unresolved
+
+### Lessons-Learned Workflow
+
+The `tasks/lessons.md` file captures patterns discovered during work. It has three sections:
+
+1. **Patterns** — Approaches that worked well (reuse these)
+2. **Anti-Patterns** — Approaches that failed (avoid these)
+3. **Common Gotchas** — Project-specific traps (watch for these)
+
+After ANY correction from the user, immediately update `tasks/lessons.md` with the pattern. Write the rule so that it prevents the same mistake in future sessions.
+
+## Deep Guidance
+
+### Beads Setup and Commands
+
+#### Initialization
+
+```bash
+bd init              # Creates .beads/ directory with data store and git hooks
+```
+
+Initialization creates:
+- `.beads/` — Data directory (committed to git)
+- Git hooks for automatic data sync (these are Beads data hooks, not code-quality hooks like pre-commit linters)
+- Initial `[BD-0]` bootstrap convention
+
+#### Core Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `bd create "title"` | Create a new task | Starting new work |
+| `bd list` | Show all tasks | Session start, planning |
+| `bd status BD-xxx` | Check task state | Before picking up work |
+| `bd start BD-xxx` | Mark task in-progress | Beginning work on a task |
+| `bd done BD-xxx` | Mark task complete | After PR merged |
+| `bd ready` | List tasks ready to start | Picking next task |
+| `bd block BD-xxx "reason"` | Mark task blocked | When dependency is unmet |
+
+#### Commit Message Convention
+
+Every commit references its Beads task:
+
+```
+[BD-42] feat(api): implement user registration endpoint
+
+- Add POST /api/v1/auth/register
+- Add input validation with zod schema
+- Add integration tests for happy path and validation errors
+```
+
+The `[BD-xxx]` prefix enables:
+- Automatic task-to-commit traceability
+- Progress tracking based on commit activity
+- Session reconstruction (which commits belong to which task)
+
+### Task Lifecycle Patterns
+
+#### Session Start Protocol
+
+1. Review `tasks/lessons.md` for recent patterns and corrections
+2. Run `bd ready` to see available tasks
+3. Pick the highest-priority ready task (or continue an in-progress task)
+4. Run `bd start BD-xxx` to claim the task
+5. Read the task description and acceptance criteria before writing code
+
+#### Session End Protocol
+
+1. Commit all work with `[BD-xxx]` prefix
+2. If task is complete: create PR, run `bd done BD-xxx`
+3. If task is incomplete: leave clear notes about current state and next steps
+4. If lessons were learned: update `tasks/lessons.md`
+
+#### Task Completion Criteria
+
+A task is done when:
+- All acceptance criteria from the task description are met
+- Tests pass (`make check` or equivalent)
+- Code follows project coding standards
+- Changes are committed with proper `[BD-xxx]` message
+- PR is created (or merged, depending on workflow)
+
+Do not mark a task done based on "it seems to work." Prove it works — tests pass, logs clean, behavior verified.
+
+### Lessons-Learned Workflow — Extended
+
+#### When to Capture
+
+Capture a lesson immediately when:
+- The user corrects your approach or output
+- A test fails due to a pattern you should have known
+- You discover a project-specific convention by reading code
+- A dependency or tool behaves differently than expected
+- A workaround is needed for a known issue
+
+#### How to Write Lessons
+
+Each lesson should be specific, actionable, and preventive:
+
+**Good lesson:**
+```markdown
+### Anti-Pattern: Using `git push -f` on shared branches
+- **Trigger:** Pushed force to a branch with an open PR
+- **Impact:** Overwrote collaborator's review comments
+- **Rule:** Never force-push to branches with open PRs. Use `git push --force-with-lease` if force is truly needed.
+```
+
+**Bad lesson:**
+```markdown
+### Be careful with git
+- Don't break things
+```
+
+The lesson must contain enough detail that a future agent (or the same agent in a new session) can apply the rule without additional context.
+
+#### Integration with CLAUDE.md
+
+The CLAUDE.md Self-Improvement section establishes the contract:
+
+> After ANY correction from the user: update `tasks/lessons.md` with the pattern.
+> Write rules that prevent the same mistake recurring.
+> Review `tasks/lessons.md` at session start before picking up work.
+
+This creates a feedback loop: correction → lesson → rule → prevention. Each session starts by reviewing lessons, ensuring that past mistakes inform current work.
+
+#### Cross-Session Memory
+
+`tasks/lessons.md` is the primary cross-session learning mechanism. It persists in the repository and is loaded via CLAUDE.md references. For projects using MCP memory servers (Tier 2 memory), lessons can also be stored in the knowledge graph for structured querying — but `tasks/lessons.md` remains the canonical file. Do not duplicate entries across both systems.
+
+### Progress Tracking Conventions
+
+#### Status Files
+
+For complex projects, maintain a progress summary:
+
+```markdown
+# Progress
+
+## Current Sprint
+- [x] BD-10: Database schema migration (done)
+- [x] BD-11: Auth middleware (done)
+- [ ] BD-12: User registration endpoint (in-progress)
+- [ ] BD-13: Login endpoint (ready)
+- [ ] BD-14: Profile management (blocked — needs BD-12)
+
+## Blocked
+- BD-14: Waiting on BD-12 (user model finalization)
+```
+
+#### Completion Criteria Checklists
+
+Each task should define explicit completion criteria, not vague goals:
+
+```markdown
+## BD-12: User registration endpoint
+
+### Done when:
+- [ ] POST /api/v1/auth/register endpoint exists
+- [ ] Input validation rejects invalid email, weak password
+- [ ] Password is hashed with bcrypt (cost factor 12)
+- [ ] Duplicate email returns 409 Conflict
+- [ ] Integration test covers happy path + 3 error cases
+- [ ] `make check` passes
+```
+
+### Common Anti-Patterns
+
+**Stale tasks.** Tasks created during planning but never updated as the project evolves. The task list says "implement X" but X was descoped two sessions ago. Fix: review the task list at the start of each session. Archive or close tasks that no longer apply.
+
+**Unclear completion criteria.** "Implement the feature" with no acceptance criteria, no test requirements, no file paths. An agent starting this task has to guess what "done" means. Fix: every task specifies exact deliverables, test requirements, and a verifiable definition of done.
+
+**Missing lessons.** The user corrects the same mistake three sessions in a row because nobody captured it in `tasks/lessons.md`. Fix: treat lesson capture as mandatory, not optional. After every correction, update the file before continuing with other work.
+
+**Task ID drift.** Commits stop including `[BD-xxx]` prefixes partway through the project. Traceability breaks down. Fix: make task ID inclusion a habit enforced by review. If using a pre-commit hook, validate the prefix.
+
+**Overloaded tasks.** A single task covers "implement the API, write the UI, add tests, update docs." This overflows a single session and makes progress tracking meaningless. Fix: split into tasks that each fit in one agent session (30-90 minutes).
+
+**Lessons without rules.** A lesson says "we had trouble with X" but doesn't state a preventive rule. Future sessions read the lesson but don't know what to do differently. Fix: every lesson must include a concrete rule — "Always do Y" or "Never do Z" — not just a description of what went wrong.

package/knowledge/core/tech-stack-selection.md

@@ -0,0 +1,214 @@
+---
+name: tech-stack-selection
+description: Framework evaluation methodology, decision matrices, and technology tradeoff analysis
+topics: [tech-stack, framework-selection, decision-matrix, tradeoffs, scalability, ecosystem]
+---
+
+# Tech Stack Selection
+
+Choosing a technology stack is one of the highest-leverage decisions in a project. A poor choice compounds into years of friction; a good choice becomes invisible. This knowledge covers systematic evaluation frameworks, decision matrices, and the discipline to separate signal from hype.
+
+## Summary
+
+### Selection Criteria Categories
+
+Every technology choice should be evaluated across six dimensions:
+
+1. **Ecosystem Maturity** — Package ecosystem breadth, stability of core libraries, frequency of breaking changes, quality of documentation, Stack Overflow answer density.
+2. **Team Expertise** — Current team proficiency, hiring pool depth in your market, ramp-up time for new developers, availability of training resources.
+3. **Performance Characteristics** — Throughput, latency, memory footprint, startup time, concurrency model. Match to your workload profile, not benchmarks.
+4. **Community & Support** — GitHub activity, release cadence, corporate backing stability, conference presence, number of active maintainers.
+5. **Licensing & Cost** — License type (MIT, Apache, BSL, SSPL), commercial support costs, cloud provider pricing, vendor lock-in implications.
+6. **Integration Fit** — Compatibility with existing systems, deployment target constraints, team tooling preferences, CI/CD compatibility.
+
+### Decision Matrix Concept
+
+A decision matrix scores each candidate technology against weighted criteria. Weights reflect project priorities — a startup prototype weights "time to first feature" heavily; an enterprise migration weights "long-term support" heavily. The matrix does not make the decision — it structures the conversation and forces explicit tradeoff acknowledgment. Set weights before scoring begins to prevent post-hoc rationalization of a predetermined choice.
+
+### When to Revisit
+
+Stack decisions should be revisited when: the team composition changes significantly, a dependency reaches end-of-life, performance requirements shift by an order of magnitude, or the licensing model changes. Do not revisit because a new framework is trending.
+
+### The Anti-Pattern Shortlist
+
+The most common selection failures: **Resume-Driven Development** (choosing tech the team wants to learn, not what fits), **Hype-Driven Development** (choosing what is trending, not what is proven), **Ignoring Team Skills** (a 20% perf gain is not worth a 200% productivity loss during ramp-up), and **Premature Vendor Lock-In** (building on proprietary services without abstraction layers).
+
+### Documentation Requirement
+
+Every stack decision must produce a written record: what was chosen, what was rejected, why, and under what conditions the decision should be revisited. This lives in `docs/tech-stack.md` or as an Architecture Decision Record (ADR). Undocumented decisions get relitigated every quarter.
+
+## Deep Guidance
+
+### The Evaluation Framework
+
+#### Step 1: Define Non-Negotiable Constraints
+
+Before evaluating options, enumerate hard constraints that eliminate candidates outright:
+
+- **Runtime environment**: Browser, Node, Deno, Bun, JVM, native binary, embedded
+- **Deployment target**: Serverless, containers, bare metal, edge, mobile device
+- **Compliance requirements**: HIPAA, SOC2, FedRAMP — some libraries/services are pre-approved
+- **Existing commitments**: Must integrate with an existing PostgreSQL database, must deploy to AWS, must support IE11
+- **Team size and tenure**: A 2-person team cannot maintain a microservices architecture in 4 languages
+
+Hard constraints are binary. If a technology fails any constraint, it is eliminated regardless of how well it scores on other dimensions.
+
+#### Step 2: Weight the Criteria
+
+Assign weights (1-5) to each criterion based on project context:
+
+| Criterion | Startup MVP | Enterprise Migration | Performance-Critical | Open Source Tool |
+|-----------|-------------|---------------------|---------------------|-----------------|
+| Ecosystem Maturity | 3 | 5 | 3 | 4 |
+| Team Expertise | 5 | 4 | 3 | 2 |
+| Performance | 2 | 3 | 5 | 3 |
+| Community | 4 | 3 | 2 | 5 |
+| Licensing | 2 | 5 | 2 | 5 |
+| Integration Fit | 3 | 5 | 4 | 3 |
+
+These weights are examples. The team must set them for their specific context before scoring begins — otherwise weights get adjusted post-hoc to justify a predetermined choice.
+
+#### Step 3: Score and Compare
+
+Score each candidate 1-5 per criterion. Multiply by weight. Sum. The highest score is not automatically the winner — it is the starting point for discussion.
+
+```
+| Criterion (weight)       | React (score) | Vue (score) | Svelte (score) |
+|--------------------------|---------------|-------------|----------------|
+| Ecosystem Maturity (5)   | 5 (25)        | 4 (20)      | 3 (15)         |
+| Team Expertise (4)       | 5 (20)        | 2 (8)       | 1 (4)          |
+| Performance (3)          | 3 (9)         | 3 (9)       | 5 (15)         |
+| Community (3)            | 5 (15)        | 4 (12)      | 3 (9)          |
+| Licensing (2)            | 5 (10)        | 5 (10)      | 5 (10)         |
+| Integration Fit (4)      | 4 (16)        | 4 (16)      | 3 (12)         |
+| **Total**                | **95**        | **75**       | **65**         |
+```
+
+The matrix reveals where tradeoffs concentrate. In this example, Svelte wins on performance but loses on ecosystem and team expertise. The conversation is now: "Is the performance gain worth the ramp-up cost and ecosystem risk?"
+
+### Category-Specific Evaluation
+
+#### Frontend Frameworks
+
+Key discriminators: bundle size, SSR support, routing model, state management ecosystem, TypeScript support quality, component library availability, build tooling maturity.
+
+**React**: Largest ecosystem, most hiring options, most third-party libraries. Risk: meta-framework churn (Next.js vs Remix vs others). Best when: team knows React, project needs rich component library ecosystem.
+
+**Vue**: Batteries-included official ecosystem (Vue Router, Pinia, Vite). Gentler learning curve. Smaller hiring pool in US/UK, larger in Asia-Pacific. Best when: team is learning frontend, project benefits from cohesive tooling.
+
+**Svelte/SvelteKit**: Best runtime performance, smallest bundles, compiler-based approach. Smaller ecosystem, fewer battle-tested libraries. Best when: performance is critical, team is small and adaptable.
+
+#### Backend Frameworks
+
+Key discriminators: request throughput, cold start time, ORM/database tooling, middleware ecosystem, deployment model compatibility, type safety.
+
+**Node.js (Express/Fastify/Hono)**: Same language as frontend, huge npm ecosystem, excellent serverless support. Risk: callback/async complexity at scale, single-threaded CPU bottlenecks. Best when: team is JavaScript-native, workload is I/O-bound.
+
+**Python (FastAPI/Django)**: Strong ML/data ecosystem, excellent type hints (FastAPI), batteries-included admin (Django). Risk: GIL for CPU-bound work, slower raw throughput. Best when: project involves data processing/ML, team is Python-native.
+
+**Go**: Excellent concurrency, fast compilation, small binaries, low memory footprint. Risk: verbose error handling, less expressive type system, smaller web framework ecosystem. Best when: high-concurrency services, CLI tools, infrastructure software.
+
+#### Database Selection
+
+Key discriminators: data model fit, query patterns, scalability model, operational complexity, backup/restore tooling, managed service availability.
+
+**PostgreSQL**: Default choice for relational data. JSON support bridges document needs. Extensions ecosystem (PostGIS, pgvector, TimescaleDB). Risk: horizontal scaling requires careful planning. Best when: data is relational, you need ACID guarantees, you want one database.
+
+**SQLite**: Zero-ops, embedded, surprisingly capable for read-heavy workloads. Litestream for replication. Risk: single-writer limitation, no built-in network access. Best when: single-server deployment, edge/embedded, development/testing.
+
+**MongoDB**: True document model, flexible schema, built-in horizontal scaling. Risk: no joins (denormalization complexity), eventual consistency by default. Best when: data is genuinely document-shaped, schema evolves rapidly, write-heavy workload.
+
+#### Infrastructure & Deployment
+
+Key discriminators: operational burden, cost model, scaling characteristics, vendor lock-in degree, team DevOps expertise.
+
+**Serverless (Lambda/Cloud Functions)**: Zero idle cost, automatic scaling, no server management. Risk: cold starts, vendor lock-in, debugging complexity, execution time limits. Best when: unpredictable traffic, many small functions, cost-sensitive.
+
+**Containers (ECS/Cloud Run/Fly.io)**: Portable, predictable performance, good local development parity. Risk: orchestration complexity (if self-managed), persistent storage challenges. Best when: consistent workloads, need local dev parity, multi-cloud possible.
+
+**PaaS (Railway/Render/Vercel)**: Fastest time to deploy, managed everything. Risk: cost at scale, limited customization, vendor-specific features. Best when: small team, prototype/MVP, standard web application architecture.
+
+### Common Anti-Patterns
+
+#### Resume-Driven Development
+
+**Pattern**: Choosing technologies because the team wants to learn them, not because they fit the project.
+**Signal**: "Let's use Kubernetes" for a single-server app. "Let's rewrite in Rust" for a CRUD API.
+**Mitigation**: The decision matrix forces explicit scoring. If a technology wins only on "fun to learn," the matrix will show it.
+
+#### Hype-Driven Development
+
+**Pattern**: Choosing technologies because they are trending on Hacker News or have impressive benchmarks.
+**Signal**: Citing benchmarks without mapping them to actual workload characteristics. "X is 10x faster than Y" without asking "do we need that speed?"
+**Mitigation**: Require a concrete performance requirement before performance can be weighted heavily.
+
+#### Ignoring Team Skills
+
+**Pattern**: Choosing the "best" technology without accounting for team proficiency.
+**Signal**: Picking Go for a team of Python developers because "Go is faster." The 6-month ramp-up and initial low-quality Go code will cost more than Python's slower runtime.
+**Mitigation**: Weight team expertise appropriately. A 20% performance gain is rarely worth a 200% productivity loss during ramp-up.
+
+#### Premature Vendor Lock-In
+
+**Pattern**: Building on vendor-specific services without an abstraction layer, making migration prohibitively expensive.
+**Signal**: Direct use of DynamoDB-specific APIs throughout business logic. Lambda-specific handler signatures in core code.
+**Mitigation**: Score "portability" as part of integration fit. Use repository/adapter patterns for external services.
+
+### Migration Cost Assessment
+
+When evaluating a technology change mid-project, assess migration cost across five dimensions:
+
+1. **Code rewrite volume** — What percentage of the codebase must change? API boundaries, data models, business logic, or just infrastructure wrappers?
+2. **Data migration complexity** — Schema changes, data transformation, downtime requirements, rollback capability.
+3. **Team retraining** — How long until the team is productive in the new technology? Count weeks, not days.
+4. **Integration surface** — How many external systems connect to the component being replaced? Each integration point is a migration risk.
+5. **Rollback plan** — Can you run old and new in parallel? Can you revert if the migration fails? If not, the risk multiplier is high.
+
+A migration is justified when: the current technology is end-of-life, the current technology cannot meet a hard requirement, or the migration cost is less than the ongoing maintenance cost of staying.
+
+### Vendor Lock-In Evaluation
+
+Rate lock-in risk on a scale:
+
+| Level | Description | Example | Exit Cost |
+|-------|-------------|---------|-----------|
+| **None** | Standard interface, multiple providers | PostgreSQL, S3-compatible storage | Low |
+| **Low** | Portable with adapter work | Redis (managed vs self-hosted) | Medium |
+| **Medium** | Significant API surface to abstract | Firebase Auth, Stripe Billing | High |
+| **High** | Deep integration, no portable equivalent | DynamoDB single-table design, Vercel Edge Config | Very High |
+| **Total** | No alternative exists | Apple Push Notifications, platform-specific APIs | Impossible |
+
+For each dependency, document the lock-in level in `docs/tech-stack.md`. When lock-in is Medium or higher, require an abstraction layer (repository pattern, adapter interface) that isolates vendor-specific code.
+
+### Decision Record Template
+
+Every technology decision should produce a record:
+
+```markdown
+## Decision: [Technology Choice]
+
+**Date**: YYYY-MM-DD
+**Status**: Accepted | Superseded by [link]
+**Deciders**: [Names]
+
+### Context
+What problem are we solving? What constraints exist?
+
+### Options Considered
+1. **[Option A]** — Brief description. Pros: ... Cons: ...
+2. **[Option B]** — Brief description. Pros: ... Cons: ...
+3. **[Option C]** — Brief description. Pros: ... Cons: ...
+
+### Decision
+We chose [Option X] because [primary reasons].
+
+### Consequences
+- Positive: [what we gain]
+- Negative: [what we accept as tradeoffs]
+- Neutral: [what doesn't change]
+
+### Revisit Conditions
+Revisit this decision if: [specific, measurable conditions]
+```
+
+This record prevents "nobody remembers why we chose X" six months later. It also prevents relitigating decisions without new information — if the conditions for revisiting haven't changed, the decision stands.