@garygentry/feature-forge 0.1.0

package/adapters/codex/skills/forge-1-prd/forge-1-prd.md

@@ -0,0 +1,120 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-1-prd/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-1-prd
+description: Create a requirements PRD for a feature through structured interview. Use when user runs /feature-forge:forge-1-prd or explicitly asks to start the forge pipeline for a new feature. Do NOT trigger for general requirements discussions, project scoping outside forge, or PRD questions unrelated to the forge pipeline.
+---
+
+# forge-1-prd — Requirements Interviewer
+
+Create a thorough, requirements-only PRD through relentless structured interviewing. The PRD captures WHAT the feature must do, not HOW it will be built.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+## Step 1: Read Configuration and Check State
+
+### Branch Setup (if using git)
+If `gitCommitAfterStage` is true and the project uses git, use `AskUserQuestion` to offer: "Want me to create a `forge/{feature}` branch for this pipeline? (Recommended — keeps forge work isolated.)" If yes, create and checkout the branch before proceeding.
+
+Set the working directory by invoking the **Feature Directory Resolution** block in `references/shared-conventions.md`, which yields `{resolvedFeatureDir}`. Note one PRD-specific caveat: at PRD time a brand-new standalone feature may have NO directory yet, so resolution is expected to fail `not-found` for a never-started standalone feature — in that case forge-1 creates `{specsDir}/{feature}/` as today. For an epic member the directory already exists (created empty by forge-0-epic with an `epic` back-pointer), so resolution succeeds and yields the nested path.
+
+If `.pipeline-state.json` exists for this feature and `forge-1-prd` is already marked complete, use `AskUserQuestion` to warn: "A PRD already exists for '{feature}'. Continuing will create a new version. Proceed?"
+
+## Step 2: Examine Existing Context
+
+Before starting the interview, invoke the **Epic Context Injection** block in `references/shared-conventions.md`. This block self-gates: it skips entirely if the feature has no `epic` back-pointer, so standalone behavior is unchanged. If this feature is an epic member, the injected charter's `exposes`/`consumes` are requirement inputs — every contract obligation must appear as a REQ in the PRD.
+
+1. **Check the project structure**: Read the project's build configuration and dependency manifests to understand what modules/packages exist. Look for `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, workspace configs, or equivalent.
+2. **Check existing specs**: Look at `{specsDir}/` for other features' PRDs to understand conventions and the overall system
+3. **Check existing docs**: Look at the docs directory for architecture documentation
+4. **Note integration surfaces**: Identify which existing packages might be relevant to this feature
+
+This context helps you ask informed questions and spot gaps the user might not think of.
+
+## Step 3: Conduct the Interview
+
+Interview the user relentlessly. Your goal is to extract complete, unambiguous requirements.
+
+Read `references/prd-template.md` for the interview structure and question categories. Cover every category. Don't rush — missing a requirement now costs 10x to fix later.
+
+### CRITICAL GUARDRAIL: No Technology Decisions
+
+The PRD is EXCLUSIVELY about requirements. You MUST enforce this boundary:
+
+**When the user says something like:**
+- "I want to use Zod for validation" → Capture as: "Runtime schema validation with type inference is required." Note their Zod preference as a constraint but not a requirement.
+- "We'll store it in Drizzle/PostgreSQL" → Capture as: "Persistent storage required for X data with Y query patterns."
+- "I want a React component that..." → Capture as: "A user interface is required that allows users to..."
+- "We should use WebSockets for..." → Capture as: "Real-time updates are required when X changes, with latency under Y."
+- "I want a REST API" → Capture as: "An HTTP-accessible interface is required for X operations"
+- "We need a microservice for X" → Capture as: "X must be independently deployable and scalable"
+- "Use a queue for Y" → Capture as: "Y must be processed asynchronously with guaranteed delivery"
+
+**When YOU start drifting into technology:**
+If you catch yourself writing about specific libraries, API designs, database schemas, or implementation patterns — STOP. Ask yourself: "Is this a requirement or an implementation choice?" Rewrite it as the underlying requirement.
+
+**The one exception:** When a technology choice IS the requirement (e.g., "must integrate with the existing @repo/auth package" or "must work with our Hono backend"). These are constraints, and they belong in the Constraints section of the PRD, clearly labeled as such.
+
+A technology constraint is valid when it stems from organizational mandate, existing infrastructure, or team expertise — not from preference. Ask "Why must it be X specifically?" If the answer is "because we already run X in production," that's a legitimate constraint. If the answer is "because it's fast," capture the performance requirement instead.
+
+### Interview Approach
+
+**Turn structure:** Output your analysis or context as regular text, then use `AskUserQuestion` for the actual questions. NEVER put questions in your text output — they MUST go through `AskUserQuestion`.
+
+**Pacing:** Cover one topic area at a time, asking 2-3 related questions per `AskUserQuestion` call. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch.
+
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose):
+- Probe deeper after each answer: failure modes, stakeholders, minimum viable version
+- Challenge assumptions: which users specifically, what does "fast" mean quantitatively
+- Identify edge cases: empty input, concurrent access, scale
+- Capture non-functional requirements: performance, security, accessibility, observability
+- Ask about what's OUT of scope — as important as what's in scope
+
+**Completion criteria:** The interview is complete when:
+1. Every category in `references/prd-template.md` has been covered with at least one question
+2. The user has confirmed there's nothing else to add
+3. You can draft every PRD section without leaving TBD placeholders
+
+Before moving to Step 4, summarize your coverage as text, then use `AskUserQuestion` to ask: "Anything I'm missing?"
+
+**Parking lot:** If the user raises a concern that belongs to a different pipeline stage, acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [tech spec/implementation specs]. Let's continue with [current stage]."
+
+## Step 4: Write the PRD
+
+Once the interview is thorough, write `{resolvedFeatureDir}/PRD.md` following the structure in `references/prd-template.md`.
+
+Every requirement MUST have a unique ID (e.g., REQ-AUTH-01, REQ-PERF-01). These IDs are referenced by all downstream documents.
+
+## Step 5: Review with User
+
+Present the complete PRD to the user. Ask:
+- "Does this capture everything? Any requirements missing?"
+- "Are the priorities correct?"
+- "Anything in here that should be out of scope?"
+
+Use `AskUserQuestion` to collect this feedback.
+
+Iterate until the user confirms the PRD is complete.
+
+## Step 6: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Create or update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `forge-2-tech`
+   - Set `stages.forge-1-prd.version` to 1 (or increment if revising)
+   - Record `artifacts`, `completedAt`
+   - Set `stages.forge-1-prd.basedOnVersions` to `{}` (no upstream dependencies)
+   - Check downstream stages (`forge-2-tech`, `forge-3-specs`, `forge-4-backlog`, `forge-5-loop`, `forge-6-docs`). If any have `basedOnVersions` referencing an older version of `forge-1-prd`, set their status to `stale`.
+2. Use `AskUserQuestion` to ask: "Anything you want to note before we wrap? (preserved across sessions)"
+   - If yes, store in the `notes` field
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete PRD v{n}"`, then set `stages.forge-1-prd.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+5. Tell the user: "PRD complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the PRD\n  - `/feature-forge:forge-2-tech {feature}` to start the tech spec\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- Users often front-load their feature description with tech decisions because that's how engineers think. Gently but firmly redirect to requirements. Don't be preachy about it — just reframe what they said.
+- If the user provides a very detailed initial description, don't skip the interview. Use their description as a starting point but probe for what's missing. Long descriptions often have big gaps in edge cases and non-functional requirements.
+- Don't number requirements sequentially across categories (REQ-01, REQ-02...). Use category prefixes (REQ-AUTH-01, REQ-PERF-01) so inserting new requirements doesn't require renumbering.
+- The PRD should be readable by a non-technical stakeholder. If a section requires deep technical knowledge to understand, it probably belongs in the tech spec, not the PRD.

package/adapters/codex/skills/forge-1-prd/references/prd-template.md

@@ -0,0 +1,106 @@
+# PRD Template and Interview Guide
+
+This reference defines the standard PRD structure and the interview questions to cover for each section.
+
+## PRD Document Structure
+
+```markdown
+# {Feature Name} — Product Requirements Document
+
+## 1. Problem Statement
+What problem does this feature solve? Who has this problem? Why does it matter now?
+
+## 2. User Stories
+As a [role], I want [capability], so that [benefit].
+- Include primary actors and secondary actors
+- Include admin/operator stories, not just end-user stories
+
+## 3. Functional Requirements
+
+### 3.1 {Capability Area}
+- REQ-{CAT}-01: {Requirement description}
+  - Priority: P0 (must have) | P1 (should have) | P2 (nice to have)
+  - Notes: {Any clarification}
+
+### 3.2 {Another Capability Area}
+...
+
+## 4. Non-Functional Requirements
+
+### 4.1 Performance
+- REQ-PERF-01: ...
+
+### 4.2 Security
+- REQ-SEC-01: ...
+
+### 4.3 Observability
+- REQ-OBS-01: ...
+
+### 4.4 Accessibility
+- REQ-A11Y-01: ...
+
+### 4.5 Scalability
+- REQ-SCALE-01: ...
+
+## 5. Constraints
+Technical, organizational, or external constraints that must be respected.
+(This is where technology mandates go — e.g., "must integrate with existing @repo/auth package")
+
+## 6. Out of Scope
+Explicitly list what this feature will NOT do in this version.
+
+## 7. Open Questions
+Unresolved items that need answers before or during implementation.
+
+## 8. Success Criteria
+How do we know this feature is done and working correctly?
+```
+
+## Interview Question Categories
+
+Cover ALL of these areas during the interview. Don't move on until each is addressed.
+
+### Core Understanding
+- What is the feature in one sentence?
+- Who are the primary users? Secondary users? Admins/operators?
+- What workflow or process does this support?
+- What exists today that this replaces or augments?
+
+### Functional Depth
+- Walk me through the happy path end to end
+- What are the key data entities involved?
+- What inputs does the system accept? What are valid/invalid inputs?
+- What outputs does the system produce?
+- What states can things be in? What transitions are allowed?
+- What happens when the user makes a mistake?
+
+### Error and Edge Cases
+- What happens when X is unavailable?
+- What if two users do Y at the same time?
+- What happens with empty inputs? Huge inputs? Malformed inputs?
+- What does partial failure look like?
+- How should the system recover from crashes mid-operation?
+
+### Integration
+- What existing parts of the system does this interact with?
+- What data does it need from other features?
+- What data does it provide to other features?
+- Are there external systems or APIs involved?
+
+### Non-Functional
+- What's the expected load? (requests/sec, concurrent users, data volume)
+- What are the latency requirements?
+- What security considerations exist? (authn, authz, data sensitivity)
+- What needs to be logged, monitored, or alerted on?
+- Are there accessibility requirements?
+
+### Scope and Priority
+- What's the minimum viable version of this?
+- What would you cut if you had to ship in half the time?
+- What's explicitly NOT part of this feature?
+- Are there follow-up features that depend on decisions made here?
+
+### Success
+- How do you know this feature is working correctly?
+- What would a user complain about if we got it wrong?
+- Are there quantitative targets? (latency < Xms, uptime > Y%)

package/adapters/codex/skills/forge-2-tech/forge-2-tech.md

@@ -0,0 +1,197 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-2-tech/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-2-tech
+description: Create a technical specification from an existing PRD in the forge pipeline. Use when user runs /feature-forge:forge-2-tech or asks to create a tech spec for a forge feature after PRD completion. Do NOT trigger for general technical design discussions, architecture reviews, or tech specs outside the forge pipeline.
+---
+
+# forge-2-tech — Technical Specification Driver
+
+Create a thorough technical specification by interviewing the user about technology decisions, grounded in PRD requirements.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+## Step 1: Validate Prerequisites
+
+**Resolve the feature directory first** via the **Feature Directory Resolution** block in `references/shared-conventions.md`, setting `{resolvedFeatureDir}`.
+
+**Prerequisite check:** Read `{resolvedFeatureDir}/.pipeline-state.json`. If not in force mode and `forge-1-prd` is not `complete`, STOP and tell the user: "The PRD for '{feature}' isn't complete yet. Run `/feature-forge:forge-1-prd {feature}` first."
+
+Read `{resolvedFeatureDir}/PRD.md` into context. This is your foundation — every technology decision must trace back to a PRD requirement.
+
+After reading the PRD, invoke the **Epic Context Injection** block in `references/shared-conventions.md`. It self-gates on the resolved feature's `epic` back-pointer: for a standalone feature it is a no-op; for an epic member it loads EPIC.md, this feature's charter, and the completed direct dependencies' specs into context before the research and interview.
+
+## Step 2: Examine Existing Context
+
+Before interviewing, you need to understand the existing codebase. This involves reading many files across the project, which consumes context.
+
+### Recommended: Delegate to forge-researcher Subagent
+
+Spawn the `forge-researcher` subagent via the Agent tool to scan the codebase. Pass a prompt like: "Research the codebase for planning the {feature} feature. Focus on integration points, established patterns, and relevant packages."
+
+If this feature belongs to an epic, also add to the dispatch prompt: "If this feature belongs to an epic, also account for these epic contracts: {paste this feature's `consumes` and the `exposes` of its direct deps}, and the completed dependency tech-specs at {paths}. Do not re-research transitive deps." This threads epic context into the researcher without changing the agent's behavior.
+
+The researcher runs in its own context window, reads the project structure, and returns a concise integration report. This keeps your main conversation context clean for the interactive interview.
+
+**Single vs. parallel research.** For a small or well-understood codebase, **one**
+researcher is the right default. For a **large codebase or uncertain scope** (many
+packages, several integration surfaces, monorepo), dispatch **multiple `forge-researcher`
+subagents in parallel — a single message with multiple Agent calls** (the
+`superpowers:dispatching-parallel-agents` pattern), each scoped to a **disjoint focus**
+so they don't re-read the same ground:
+- one on **project structure & conventions** (layout, build, naming, error/test patterns),
+- one per **major integration area / subsystem** the feature touches (its exports, types,
+  public API),
+- optionally one on **existing feature specs & in-progress conflicts**.
+
+Each returns its own report; **you merge them** into a single integration picture for the
+interview. This cuts latency and deepens coverage versus one researcher sweeping
+everything serially. No agent change is needed — `forge-researcher` already returns a
+self-contained report; just give each instance a narrower focus.
+
+If the `forge-researcher` subagent is not available, perform the research inline (steps below).
+
+### Manual Research (fallback)
+
+1. **Read the PRD thoroughly**: Understand all requirements and constraints
+2. **Check for project-level stack decisions**: Look for `.claude/references/stack-decisions.md` in the project root. If present, read it — these are established technology choices that should be respected unless there's a strong reason to deviate.
+3. **Read the plugin's default stack reference**: Read `references/stack-discovery-checklist.md` for general stack context (only if no project-level override exists)
+4. **Examine the existing codebase**: Look at `package.json` files, existing packages, directory structure, and established patterns. Understand what conventions are already in place.
+5. **Review other features' tech specs**: Check `{specsDir}/*/tech-spec.md` and `{specsDir}/*/*/tech-spec.md` (depth-2, to find nested epic members) for consistency in approach and to identify shared infrastructure. Apply the **feature-shaped-dir bound**: only treat a directory as a feature if it directly contains a `.pipeline-state.json` (filter matches whose parent directory holds one, or enumerate members via the helper). A flat-only tree has no depth-2 feature dirs, so this gains no new matches there (REQ-COMPAT-01).
+6. **Identify integration points**: For each existing package that this feature touches, read its exports, types, and public API. Document these as constraints.
+
+### Stack Detection and Persistence
+
+After researching the codebase, identify the primary stack (language, build tool, package manager, framework). Read `references/stack-resolution.md` for the full resolution protocol.
+
+1. Check if `forge.config.json` already has a `stack` field — if so, use it
+2. Otherwise, detect from project files and use `AskUserQuestion` to confirm: "I detected this as a {stack} project. Correct?"
+3. Update `forge.config.json` with `stack`, `typeCheckCommand`, and `testCommand`
+4. Verify that a matching stack profile exists at `references/stacks/{stack}.md`. If it does, load it for stack-specific guidance during this and all subsequent stages. If no profile exists, inform the user: "No dedicated profile for {stack}. Using generic fallback — spec conventions, verification checks, and examples will be language-neutral. Consider creating a project-level override at `.claude/references/stack-decisions.md`." Then load `references/stacks/_generic.md`.
+
+## Step 3: Conduct the Interview
+
+Interview the user about technology decisions. Unlike the PRD interview, here you SHOULD discuss specific technologies, libraries, patterns, and architecture.
+
+### Interview Approach
+
+**Turn structure:** Output your research findings, analysis, or technical proposals as regular text. Then use `AskUserQuestion` for the actual questions. NEVER put questions in your text output — they MUST go through `AskUserQuestion`.
+
+**Pacing:** Present 1-2 decision areas per `AskUserQuestion` call and STOP to wait for the user's response before continuing. After receiving answers, probe deeper on anything incomplete before moving to the next topic. Signal progress in your text before the next question batch. Do NOT dump all decision areas in a single message — the interview is a conversation, not a document.
+
+**First message pattern:** Output the research summary as text, then use `AskUserQuestion` to confirm the stack and ask about the first decision area (typically package/module structure). Wait for the user to respond before proceeding to subsequent areas.
+
+**Question strategies** (use these as content for `AskUserQuestion`, not as inline prose):
+- For each PRD requirement, propose a technical approach and ask for confirmation or alternatives
+- Proactively suggest approaches consistent with the established stack
+- Challenge over-engineering: does the feature need this, or is a simpler approach sufficient?
+- Ask about every integration point and how the feature interacts with existing modules
+
+**Parking lot:** If the user raises a concern that belongs to a different pipeline stage (e.g., backlog granularity, documentation format), acknowledge it and note it in the pipeline state's `notes` field: "Good point — I've noted that for the [specs/backlog/docs stage]. Let's continue with the tech spec."
+
+### Key Decision Areas to Cover
+
+Work through these areas across multiple turns, grouping related areas (1-2 per message):
+
+- **Package/module structure**: Where does this live in the project? What are its exports? (For non-monorepo projects, this becomes module organization — where the code lives, how it's organized, and what its exports are.)
+- **Data model**: What are the key entities, their schemas, and storage approach?
+- **API design**: What endpoints or interfaces does this expose?
+- **Dependencies**: What external and internal packages are needed?
+- **Patterns**: Which established patterns from the codebase apply here?
+- **Error handling**: How are errors surfaced, propagated, and recovered from?
+- **Testing strategy**: Unit, integration, e2e — what approach for this feature?
+- **Configuration**: What's configurable? How is it configured?
+- **Migration/deployment**: Any special rollout considerations?
+
+### Requirement Traceability
+
+Every technical decision MUST reference the PRD requirement(s) it addresses. Use the format:
+
+```
+### JWT-based Session Tokens (REQ-AUTH-01, REQ-SEC-02)
+Sessions will use signed JWT tokens with...
+```
+
+If you find yourself writing a technical section that doesn't trace to any PRD requirement, STOP and ask: "I'm about to specify X, but I can't find a PRD requirement for it. Should we add one, or is this unnecessary?"
+
+## Step 4: Integration Analysis (Required)
+
+Before finalizing the tech spec, this section is MANDATORY:
+
+1. List every existing package this feature depends on
+2. List every existing package that will need to import from this feature
+3. For each integration point, document:
+   - Which types or contracts are shared
+   - How data flows between packages
+   - Any patterns established by existing code that must be followed
+   - The EXACT function signatures and import paths verified from source code. If you cannot locate an expected export, note explicitly: "WARNING: Could not locate X export in {module} — verify this exists before implementing."
+4. Check for potential conflicts with in-progress features (other spec directories)
+
+## Step 5: Write the Tech Spec
+
+Write `{resolvedFeatureDir}/tech-spec.md` with this structure:
+
+```markdown
+# {Feature Name} — Technical Specification
+
+## 1. Overview
+Brief technical summary and key architectural decisions.
+
+## 2. Module Structure
+Project location, directory layout, public API surface.
+
+## 3. Technical Decisions
+### 3.1 {Decision Area} (REQ-XXX-NN)
+Decision, rationale, alternatives considered.
+
+## 4. Data Model
+Schemas, types, storage approach.
+
+## 5. API Design
+Endpoints, interfaces, contracts.
+
+## 6. Integration Points
+How this feature connects to existing packages.
+
+## 7. Error Handling
+Error types, propagation, recovery.
+
+## 8. Testing Approach
+Strategy, tooling, coverage targets.
+
+## 9. Dependencies
+External packages, internal packages, version constraints.
+
+## 10. Open Technical Questions
+Unresolved technical decisions.
+```
+
+## Step 6: Review with User
+
+Present the complete tech spec. Ask:
+- "Does this capture all the technical decisions correctly?"
+- "Any patterns from the existing codebase I missed?"
+- "Are the integration points complete?"
+
+Use `AskUserQuestion` to collect this feedback.
+
+## Step 7: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `forge-3-specs`
+   - Record `artifacts`, `completedAt`, `version`
+   - Set `stages.forge-2-tech.basedOnVersions` to `{"forge-1-prd": <current forge-1-prd version>}`
+   - Check downstream stages (forge-3-specs, forge-4-backlog, forge-5-loop, forge-6-docs). If any have `basedOnVersions` referencing an older version of forge-2-tech, set their status to `stale`
+2. Use `AskUserQuestion` to ask about notes to persist
+3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files, attempt commit with message `"{commitPrefix}({feature}): complete tech-spec v{n}"`, then set `stages.forge-2-tech.status` to `complete` with commit hash only on success. If commit fails, leave status as `in-progress`.
+5. Tell the user: "Tech spec complete. Next steps:\n  - `/feature-forge:forge-verify {feature}` to verify the tech spec\n  - `/feature-forge:forge-3-specs {feature}` to create implementation specs\n  - `/feature-forge:forge {feature}` to see full pipeline status"
+
+## Gotchas
+
+- Don't duplicate the PRD. The tech spec answers HOW, not WHAT. If you find yourself restating requirements, reference them by ID instead.
+- When the user's stack decisions differ from what you'd recommend, document their choice AND note your concern as an "Alternatives Considered" item — don't silently override their preference.
+- Integration points are the #1 source of implementation surprises. Spend extra time here. Read the actual code of packages this feature touches, don't just guess at their APIs.
+- If the existing codebase has inconsistent patterns (it happens), call it out and ask which pattern should be followed for this feature.

package/adapters/codex/skills/forge-2-tech/references/stack-discovery-checklist.md

@@ -0,0 +1,95 @@
+# Stack Discovery Checklist (Plugin Default)
+
+This file contains a default stack discovery protocol for the feature-forge plugin. Projects can override this by placing a `stack-decisions.md` in `.claude/references/` at the project root.
+
+## Note to Agent
+
+This is a DISCOVERY PROTOCOL — it helps you identify what stack the project uses. It is NOT a set of decisions. Always check `.claude/references/stack-decisions.md` first — if present, it takes precedence.
+
+After discovering the stack, check if `references/stacks/{stack}.md` exists in the plugin for stack-specific guidance. See `references/stack-resolution.md` for the full resolution protocol.
+
+## Purpose
+
+This is a default discovery guide for understanding a project's technology stack. Projects should create `.claude/references/stack-decisions.md` with their actual stack decisions, which takes precedence over this checklist.
+
+## Stack Discovery Protocol
+
+### 1. Identify the Primary Language and Runtime
+
+Check for project manifests:
+- `package.json` → Node.js / Bun (JavaScript/TypeScript)
+- `pyproject.toml`, `setup.py`, `setup.cfg` → Python
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- `pom.xml`, `build.gradle`, `build.gradle.kts` → Java / Kotlin
+- `*.csproj`, `*.sln` → .NET (C#/F#)
+- `mix.exs` → Elixir
+- `Gemfile` → Ruby
+- `Package.swift` → Swift
+
+### 2. Identify the Package Manager
+
+Check for lock files:
+- `bun.lockb` → Bun
+- `pnpm-lock.yaml` → pnpm
+- `package-lock.json` → npm
+- `yarn.lock` → Yarn
+- `uv.lock` → uv
+- `poetry.lock` → Poetry
+- `go.sum` → Go modules
+- `Cargo.lock` → Cargo
+
+### 3. Identify Project Structure
+
+Check for monorepo/workspace configurations:
+- `turbo.json` → Turborepo
+- `nx.json` → Nx
+- `lerna.json` → Lerna
+- `pnpm-workspace.yaml` → pnpm workspaces
+- `pants.toml` → Pants (Python/Go/Java)
+- `go.work` → Go workspaces
+- `Cargo.toml` with `[workspace]` → Cargo workspaces
+
+If none found, this is likely a single-project repository.
+
+### 4. Identify Frameworks and Libraries
+
+Examine the dependency manifest for:
+- **Web frameworks**: Hono, Express, Fastify, FastAPI, Django, Flask, Gin, Actix, Spring Boot, etc.
+- **Frontend**: React, Vue, Svelte, Solid, etc.
+- **Database/ORM**: Drizzle, Prisma, SQLAlchemy, GORM, Diesel, etc.
+- **Validation**: Zod, Pydantic, etc.
+- **Testing**: Vitest, pytest, go test, etc.
+
+### 5. Identify Build and Type Checking
+
+- Check for CI config (`.github/workflows/`, `Makefile`, `justfile`) to find build, test, and type check commands
+- Check `package.json` scripts, `pyproject.toml` `[tool.*]` sections, or `Makefile` targets
+
+## How to Create a Project-Level Override
+
+Create `.claude/references/stack-decisions.md` in your project root with your specific stack decisions. See `references/stacks/typescript.md` or `references/stacks/python.md` for stack-specific examples of what to include.
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- [Language and version]
+- [Package manager]
+- [Build tool / monorepo orchestration if applicable]
+
+## Backend
+- [Web framework]
+- [Database / ORM]
+- [Validation library]
+
+## Frontend (if applicable)
+- [UI framework]
+- [Component library]
+- [Styling approach]
+
+## Conventions
+- [Testing framework and approach]
+- [Type checking / linting command]
+- [Module organization patterns]
+```