@garygentry/feature-forge 0.2.14 → 0.3.1

package/adapters/pi/skills/forge-guide/references/stack-resolution.md

@@ -0,0 +1,54 @@
+# Stack Resolution Protocol
+
+How feature-forge resolves stack-specific guidance for a project.
+
+## Resolution Order (highest priority first)
+
+1. **Project-level override** (first existing path wins). These hold the team's explicit technology decisions and take absolute precedence:
+   1. `.feature-forge/stack-decisions.md` — the preferred, host-neutral location (it belongs to this tool, not to any one agent).
+   2. `.agents/references/stack-decisions.md` — for projects that centralize cross-agent config under `.agents/`.
+   3. `.claude/references/stack-decisions.md` — **legacy alias**, still honored for backward compatibility. If only this file exists, use it and suggest copying it to `.feature-forge/stack-decisions.md`.
+
+2. **Detected stack profile**: `references/stacks/{stack}.md` in this plugin, where `{stack}` matches the `stack` field in `forge.config.json`. Provides language-specific conventions for spec writing, verification, and examples.
+
+3. **Generic fallback**: `references/stacks/_generic.md` in this plugin. Language-neutral guidance that works for any stack. Used when no stack is detected or no matching profile exists.
+
+## How Stack Detection Works
+
+Stack detection happens during **forge-2-tech** (the technical specification stage), which is the natural point where technology decisions are made.
+
+1. The agent examines the project's root manifest and build files
+2. Identifies the primary language, build tool, package manager, and framework
+3. Asks the user to confirm: "I detected this as a {stack} project. Correct?"
+4. Persists the stack identity in `forge.config.json` via the `stack`, `typeCheckCommand`, and `testCommand` fields
+5. All downstream stages (forge-3-specs, forge-4-backlog, forge-verify, forge-6-docs) read the `stack` field and load the matching profile
+
+## forge.config.json Fields
+
+```json
+{
+  "stack": "typescript",
+  "typeCheckCommand": "bun run typecheck",
+  "testCommand": "bun test"
+}
+```
+
+- `stack` — Identifier matching a profile filename in `references/stacks/` (e.g., "typescript", "python", "go")
+- `typeCheckCommand` — Used in acceptance criteria and verification checks. Null if the stack has no type checker.
+- `testCommand` — Used in acceptance criteria and verification checks.
+
+## Available Profiles
+
+| Profile | File | Covers |
+|---------|------|--------|
+| TypeScript | `references/stacks/typescript.md` | Node.js/Bun, npm/pnpm/bun, monorepo patterns, TS-specific spec conventions |
+| Python | `references/stacks/python.md` | Python 3.10+, pip/uv/poetry, pytest, type hints, Pydantic/dataclasses |
+| Generic | `references/stacks/_generic.md` | Any stack — language-neutral guidance using placeholders |
+
+## When No Stack Is Configured
+
+If `forge.config.json` has no `stack` field and forge-2-tech hasn't run yet (e.g., when using `--force`), skills should:
+
+1. Attempt basic detection from project files (look for manifest files)
+2. Use `_generic.md` as fallback
+3. Note in the pipeline state that stack detection was skipped

package/adapters/pi/skills/forge-guide/references/stacks/_generic.md

@@ -0,0 +1,111 @@
+# Generic Stack Profile
+
+Language-neutral guidance for projects without a dedicated stack profile. Use this as a fallback when no matching `references/stacks/{stack}.md` exists.
+
+## Discovery Protocol
+
+Identify the project's stack by checking for these manifest and build files:
+
+| File | Stack |
+|------|-------|
+| `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 |
+
+Also check for:
+- **Lock files**: Reveal the package manager (`bun.lockb`, `uv.lock`, `poetry.lock`, `go.sum`, `Cargo.lock`, etc.)
+- **Workspace/monorepo configs**: `turbo.json`, `nx.json`, `lerna.json`, `pants.toml`, `Cargo workspace`, Go workspace `go.work`
+- **CI configuration**: `.github/workflows/`, `Makefile`, `justfile` — often reveals build and test commands
+
+## Archetype Adaptations
+
+### 00-core-definitions.md
+
+The shared type/data contract document. Language-neutral name for what TypeScript calls "core types and interfaces." Contents should include:
+
+- **Data structures**: The primary types, classes, structs, records, or models that define the feature's domain. Use the project's idiomatic type system (dataclasses, structs, interfaces, schemas, etc.)
+- **Error/exception hierarchy**: Base error type and domain-specific subtypes with structured properties. Every language has a mechanism for this (exception classes, error types, Result enums, etc.)
+- **Constants and enumerations**: Shared values referenced across the feature
+- **Public contracts**: Function signatures, protocols, interfaces, or traits that define the feature's API surface
+
+**Documentation rule**: Every type/structure must have documentation comments in the project's convention (JSDoc, docstrings, godoc, rustdoc, etc.)
+
+**Export rule**: Everything must be accessible through the module's entry point following project conventions.
+
+### 01-architecture-layout.md
+
+How the feature is structured in the project:
+
+- **Directory tree**: Full layout (not abbreviated)
+- **Project manifest**: Dependencies, entry points, build scripts
+- **Build/compiler configuration**: Key options
+- **Module export structure**: What each entry point exposes
+- **Build and deployment considerations**
+
+### NN-testing-strategy.md
+
+- **Testing framework and tooling**: Match project conventions
+- **Unit test approach**: What to test, what to mock/stub
+- **Integration test approach**: Cross-module interaction testing
+- **Test fixtures and factories**
+- **Coverage targets**
+- **Test file location conventions**
+
+## Spec Conventions
+
+When writing implementation specs:
+- Include complete type definitions and function signatures in the project's language — not pseudocode
+- Include documentation comments on every public type and function
+- Include error handling for every operation
+- Include example usage where it aids clarity
+- Cross-reference other spec documents by filename
+
+## Verification Adaptations
+
+Replace stack-specific checks with these generic equivalents:
+
+| Stack-specific check | Generic equivalent |
+|---------------------|-------------------|
+| "Valid TypeScript syntax" | "Valid syntax in the project's language" |
+| "Barrel exports (index.ts)" | "Module exports/entry points follow project conventions" |
+| "bun run typecheck passes" | "`{typeCheckCommand}` passes" (from forge.config.json) |
+| "bun test passes" | "`{testCommand}` passes" (from forge.config.json) |
+| "JSDoc on every field" | "Documentation comments on every field" |
+| "tsconfig.json extends root" | "Build configuration follows project conventions" |
+
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+Since no dedicated profile applies, identify these by role rather than exact filename:
+
+- **Runtime entrypoints (a legitimate non-test call site):** the process/main entry the build's
+  run command actually launches (from the CI/`Makefile`/manifest "start" target), an HTTP/RPC handler
+  or route, a scheduled/worker task, or a CLI subcommand — **not** a file in the project's test
+  directory or matching its test-file convention.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** any
+  module/hook the framework runs **once per process before serving** — a startup/lifecycle hook, an
+  import-time initializer, a global preload, or a shared test-setup module that bootstraps production
+  graphs. Side effects here run on every process start (and, under a dev/watch runtime, on every
+  reload).
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** database/ORM
+  clients and connection pools, message/queue clients, telemetry/observability SDKs, or a broad
+  whole-service-layer import. An init pulling any of these into a universal bootstrap entry is the
+  CHECK-I23 pattern — recommend lazy initialization at the first handler/worker that needs the graph,
+  not eagerly at process start.
+
+## Acceptance Criteria Patterns
+
+Use these placeholder patterns in backlog items. Replace `{typeCheckCommand}`, `{testCommand}`, and `{module}` with values from `forge.config.json` and the project structure:
+
+- `{typeCheckCommand} passes for {module}`
+- `{testCommand} passes for {module}`
+- `{module}/[entry point] exports [expected symbols]`
+- `[dependency manifest] includes [new dependency]`
+- `[build command] succeeds`

package/adapters/pi/skills/forge-guide/references/stacks/go.md

@@ -0,0 +1,157 @@
+# Go Stack Profile
+
+Stack-specific guidance for Go projects (1.21+).
+
+## Stack Identity
+
+- **Language**: Go 1.21+ (required for `slog` stdlib logging, `slices`/`maps` packages, improved generics)
+- **Build system**: `go build`, `go install` (no external build tool required)
+- **Module system**: Go modules (`go.mod` / `go.sum`)
+- **Philosophy**: Simplicity-first — prefer the standard library, add dependencies only when justified
+
+## Discovery Checklist
+
+When examining a Go project, check for:
+
+- **Module definition**: `go.mod` (module path, Go version, dependencies)
+- **Dependency lock**: `go.sum` (checksums for reproducible builds)
+- **Entry points**: `cmd/` directory (for CLIs, services, or multiple binaries)
+- **Private packages**: `internal/` directory (compiler-enforced encapsulation)
+- **Public packages**: `pkg/` directory (if used — not all projects follow this convention)
+- **Build automation**: `Makefile`, `Taskfile.yml`, `mage` targets
+- **Configuration**: `.golangci.yml` or `.golangci.yaml` (linter config)
+- **Code generation**: `go generate` directives, `//go:generate` comments, `tools.go` for tool dependencies
+- **Framework**: Check imports for chi, gin, echo, fiber (routers), or stdlib `net/http`
+- **Database**: Check for sqlx, pgx, ent, gorm, or `database/sql`
+
+## Archetype Conventions
+
+### 00-core-definitions.md (Go)
+
+- **Structs**: Use `struct` types with json/db tags (e.g., `` `json:"name" db:"name"` ``). Document every exported field with a comment.
+- **Interfaces**: Keep small and behavior-focused (1–3 methods). Define at the consumer site, not the implementation site. Name with `-er` suffix where natural (e.g., `Reader`, `Validator`).
+- **Error types**: Custom types implementing the `error` interface. Use `errors.New` for sentinel errors, `fmt.Errorf` with `%w` for wrapping. Group domain errors in a dedicated `errors.go` file.
+- **Constants**: Use `iota` for sequential constants, typed constants for domain values, `const` blocks for related groups
+- **Type aliases and generics**: Use sparingly. Generic types when the abstraction genuinely applies across multiple concrete types.
+- **No barrel exports**: Go uses package-level visibility (`Exported` vs `unexported`); there is no index file pattern.
+
+### 01-architecture-layout.md (Go)
+
+- **Standard project layout**:
+  - `cmd/<binary-name>/main.go` — entry points (one per binary)
+  - `internal/` — private application code (compiler-enforced)
+  - `pkg/` — public library code (optional, some projects skip this)
+  - `api/` — OpenAPI specs, protobuf definitions, API contracts
+  - `configs/` — configuration file templates
+  - `scripts/` — build, install, analysis scripts
+- **go.mod**: Module path matching the repo URL (e.g., `github.com/user/repo`), minimum Go version, direct and indirect dependencies
+- **Package design**: One package per directory, package name matches directory name, package-level `doc.go` for documentation
+- **Build considerations**: Cross-compilation with `GOOS`/`GOARCH`, build tags for platform-specific code, `ldflags` for version injection
+
+### NN-testing-strategy.md (Go)
+
+- **Framework**: `testing` package from stdlib (no external framework required)
+- **Test file location**: `*_test.go` files in the same package (white-box) or `_test` package suffix (black-box)
+- **Table-driven tests**: Standard pattern using slice of test structs with `t.Run()` subtests
+- **Test helpers**: Functions accepting `testing.TB` with `t.Helper()` call at top
+- **Mocking**: Interfaces + manual mocks, or testify/mock, gomock, mockgen if project uses them
+- **Assertions**: stdlib `if got != want` pattern, or testify `assert`/`require` if project uses it
+- **Integration tests**: Build tags (`//go:build integration`) to separate from unit tests
+- **Benchmarks**: `func BenchmarkXxx(b *testing.B)` with `b.N` loop
+- **Test fixtures**: `testdata/` directory (ignored by Go tooling), `TestMain` for setup/teardown
+
+## Spec Quality Rules
+
+- All Go code must be valid syntax with complete type information — not pseudocode
+- Follow Go idioms:
+  - Return `error` as the last return value — never panic for expected failures
+  - Accept interfaces, return structs (depend on behavior, produce concrete types)
+  - Design meaningful zero values (a zero-valued struct should be usable or clearly invalid)
+  - No getters — use the field name directly (e.g., `user.Name` not `user.GetName()`)
+  - Use embedding for composition, not inheritance
+  - `context.Context` as the first parameter for any function that may block or be cancelled
+  - `error` as the last return value for any function that can fail
+- Include complete function signatures with named return values where they improve clarity
+- Document every exported type, function, and method with a comment starting with the identifier name
+- Use `//nolint` directives only with a justification comment
+
+## Verification Specifics
+
+- **Static analysis**: `go vet ./...` (catches common mistakes)
+- **Linting**: `golangci-lint run` (if `.golangci.yml` exists or CI uses it)
+- **Testing**: `go test ./...` (all packages)
+- **Building**: `go build ./...` (ensures all packages compile)
+- **Formatting**: `gofmt -l .` or `goimports -l .` (should produce no output)
+- **Module tidiness**: `go mod tidy` (ensures `go.mod` and `go.sum` are consistent)
+
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** `func main()` in a `package main` under
+  `cmd/…` or the module root, an HTTP handler registered on a `*http.ServeMux` / router, a gRPC service
+  registration, or a worker/consumer goroutine started from `main` — not a `*_test.go` file.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package-level
+  `func init()` that constructs heavy clients, package-level `var` initializers that dial/connect at
+  import time, or a single `bootstrap`/`wire` module `main` calls before serving. `init()` and
+  package-var side effects run on **every** binary start, before `main` gets control.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB drivers/pools
+  (`database/sql` + a driver, `pgx`, `gorm`, `mongo-driver`), message/queue clients (`sarama`/Kafka,
+  `amqp`, `go-redis`), telemetry SDKs (`go.opentelemetry.io/*`, `sentry-go`), or a broad internal
+  service package. An `init()` or package-var that dials any of these is the CHECK-I23 pattern —
+  recommend a `sync.Once` lazy constructor invoked from the first handler that needs it, not an
+  eager package-level connect.
+
+## Testing
+
+- **Framework**: `testing` stdlib package
+- **Test command**: `go test ./...` for all, `go test -v -run TestName ./pkg/...` for specific
+- **Table-driven tests**: Idiomatic pattern — slice of anonymous structs with `name`, input, and expected fields
+- **Subtests**: `t.Run("case name", func(t *testing.T) { ... })` for grouped assertions
+- **Assertions**: testify `assert`/`require` (if project uses it), otherwise manual `if` checks with `t.Errorf`
+- **Coverage**: `go test -coverprofile=coverage.out ./...` then `go tool cover -html=coverage.out`
+- **Race detection**: `go test -race ./...` for concurrency safety
+- **Fuzzing**: `func FuzzXxx(f *testing.F)` (Go 1.18+)
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| HTTP router | net/http (stdlib), chi, gin, echo, fiber |
+| Database | database/sql (stdlib), sqlx, pgx, ent, gorm |
+| Migrations | golang-migrate, goose, atlas |
+| CLI | cobra, urfave/cli, kong |
+| Logging | log/slog (stdlib), zerolog, zap |
+| Configuration | viper, envconfig, koanf |
+| Dependency injection | wire, fx, dig |
+| gRPC | google.golang.org/grpc, connect-go |
+| Testing | testify, gomock, go-cmp |
+
+## Example: Project-Level Override
+
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Go 1.22 with standard go toolchain
+- Makefile for build automation
+
+## Backend
+- chi for HTTP routing
+- sqlx with PostgreSQL
+- log/slog for structured logging
+
+## Testing
+- testify for assertions and mocking
+- Table-driven tests with t.Run() subtests
+- Build tag `integration` for integration tests
+
+## Conventions
+- Standard project layout (cmd/, internal/, pkg/)
+- golangci-lint with project .golangci.yml
+- Context as first parameter, error as last return
+- Interfaces defined at consumer site
+```

package/adapters/pi/skills/forge-guide/references/stacks/python.md

@@ -0,0 +1,184 @@
+# Python Stack Profile
+
+Stack-specific guidance for Python projects (3.10+).
+
+## Stack Identity
+
+- **Language**: Python 3.10+ (required for modern type hint syntax: `X | Y` unions, `match` statements)
+- **Package management**: pip, uv, poetry, pdm, or pipenv (check for respective lock/config files)
+- **Type checking**: mypy, pyright, or pytype
+- **Linting**: ruff, flake8, pylint
+
+## Discovery Checklist
+
+When examining a Python project, check for:
+
+- **Project manifest**: `pyproject.toml` (modern), `setup.py`/`setup.cfg` (legacy), `requirements.txt` (minimal)
+- **Package manager**: `uv.lock` (uv), `poetry.lock` (poetry), `pdm.lock` (pdm), `Pipfile.lock` (pipenv)
+- **Monorepo**: `pants.toml` (Pants), `BUILD` files (Bazel), `nx.json` with Python plugins, or plain workspace structure
+- **Framework**: FastAPI, Django, Flask, Starlette, Litestar
+- **Database**: SQLAlchemy, Django ORM, Tortoise ORM, SQLModel
+- **Validation**: Pydantic, attrs, marshmallow
+- **Testing**: pytest (dominant), unittest
+- **Type checking**: `mypy.ini`, `pyrightconfig.json`, or `[tool.mypy]` / `[tool.pyright]` in `pyproject.toml`
+
+## Archetype Conventions
+
+### 00-core-definitions.md (Python)
+
+- **Data structures**: Use `dataclasses` for simple data containers, Pydantic `BaseModel` for validated/serializable models. Use `TypedDict` for dict-shaped data.
+- **Type aliases**: Use `type` statements (3.12+) or `TypeAlias` annotation
+- **Union types**: Use `X | Y` syntax (3.10+)
+- **Protocols**: Use `typing.Protocol` for structural subtyping (Python's equivalent of interfaces)
+- **Error/exception hierarchy**: Base exception class inheriting from `Exception` (or a more specific built-in); domain-specific subclasses with typed attributes
+- **Constants and enumerations**: Use `enum.Enum`, `enum.StrEnum`, or module-level constants with `Final` annotation
+- **Module exports**: Define `__all__` in `__init__.py` for explicit public API
+
+### 01-architecture-layout.md (Python)
+
+- **Project layout**: `src/` layout (recommended) or flat layout
+- **pyproject.toml**: `[project]` table with `name`, `dependencies`, `optional-dependencies`, `[project.scripts]` for CLI entry points
+- **Tool configuration**: `[tool.pytest.ini_options]`, `[tool.mypy]`, `[tool.ruff]` sections in `pyproject.toml`
+- **Module entry points**: `__init__.py` files with explicit `__all__` lists for re-exports
+- **Namespace packages**: When applicable, `py.typed` marker for PEP 561 compliance
+
+### Monorepo conventions (if applicable)
+
+- **Workspace structure**: `packages/` or `libs/` directories with individual `pyproject.toml` per package
+- **Internal dependencies**: Path dependencies in `pyproject.toml` or editable installs
+- **Build coordination**: Pants, Bazel, or Makefile-based orchestration
+
+## Spec Quality Rules
+
+- All Python code must be valid syntax with complete type annotations — not pseudocode
+- Use Google-style or NumPy-style docstrings consistently (match project convention)
+- Include `Args`, `Returns`, `Raises` sections in docstrings for every public function
+- Use `Protocol` classes to define interfaces/contracts
+- Include explicit import statements in all code examples
+- Use `async def` for asynchronous operations where applicable
+
+### Example: Well-Specified Function
+
+```python
+class SessionExpiredError(AuthError):
+    """Raised when a session token has expired.
+
+    Attributes:
+        expired_at: When the session expired.
+    """
+
+    def __init__(self, expired_at: datetime) -> None:
+        self.expired_at = expired_at
+        super().__init__(
+            code="SESSION_EXPIRED",
+            message=f"Session expired at {expired_at.isoformat()}",
+        )
+
+
+async def refresh_session_token(
+    current_token: str,
+    *,
+    max_age: timedelta = SESSION_DURATION,
+    refresh_threshold: timedelta = REFRESH_THRESHOLD,
+    signing_key: bytes,
+) -> str | None:
+    """Refresh a session token if it's within the refresh threshold.
+
+    Returns a new token with an extended expiry, or None if the session
+    is not eligible for refresh (valid but outside threshold).
+
+    Args:
+        current_token: The JWT string from the session cookie.
+        max_age: Maximum age of a token eligible for refresh.
+        refresh_threshold: How close to expiry before refresh is allowed.
+        signing_key: Secret key for signing the new token.
+
+    Returns:
+        New session token string, or None if refresh is not possible.
+
+    Raises:
+        SessionExpiredError: If the token has already expired.
+        TokenValidationError: If the token signature is invalid.
+    """
+    ...
+```
+
+## Verification Specifics
+
+- **Type checking**: `mypy .`, `mypy src/`, `pyright`, or `pyright src/`
+- **Linting**: `ruff check .` or `flake8`
+- **Formatting**: `ruff format --check .` or `black --check .`
+- **Import validation**: `mypy` with `--strict` or `--disallow-untyped-defs` catches missing type annotations
+- **Module export validation**: `__all__` lists in `__init__.py` match spec's public API
+
+### Runtime Entrypoints & Bootstrap-Wiring Sites
+
+Used by `CHECK-I22` (a runtime-required bootstrap needs a **non-test** caller on one of these) and
+`CHECK-I23` (a heavy init wired into a **universal** bootstrap entry should move to a lazier site).
+
+- **Runtime entrypoints (a legitimate non-test call site):** a `if __name__ == "__main__":` block, a
+  `[project.scripts]` console-script target in `pyproject.toml`, an ASGI/WSGI app object
+  (`app = FastAPI()` / Django `wsgi.py` / `asgi.py`), a route/view/handler, a Celery/RQ task module, or
+  a management command — not a `test_*.py` / `conftest.py`.
+- **Universal bootstrap entries (run on every startup — the `CHECK-I23` risk site):** a package
+  `__init__.py` that eagerly instantiates heavy clients at import time, a framework startup hook
+  (FastAPI `lifespan` / `@app.on_event("startup")`, Django `AppConfig.ready()`, a Gunicorn/uvicorn
+  `--preload` module), or a `conftest.py` that bootstraps production graphs. Import-time side effects
+  here run on every process start.
+- **Heavy server-only import markers (what makes an init "heavy" for `CHECK-I23`):** DB/ORM engines
+  (`sqlalchemy.create_engine`, `psycopg`, Django ORM, `pymongo`, `redis`), task queues (`celery`,
+  `rq`, `kafka`), telemetry SDKs (`opentelemetry`, `sentry_sdk`), or a whole-service-layer package
+  import. An init pulling any of these at a universal entry is the CHECK-I23 pattern — recommend lazy
+  init (module-level `@lru_cache` factory, `Depends()` provider, or first-use lazy import) at the
+  handler that needs it.
+
+## Testing
+
+- **Framework**: pytest (with `conftest.py` for fixtures)
+- **Fixtures**: Define in `conftest.py` at appropriate scope (session, module, function)
+- **Mocking**: `unittest.mock.patch`, `monkeypatch` fixture, or `pytest-mock`
+- **Coverage**: `pytest-cov` with `--cov=src/` flag
+- **Test file location**: `tests/` directory mirroring `src/` structure, or co-located `test_*.py` files
+- **Async testing**: `pytest-asyncio` for async function tests
+- **Type testing**: Runtime checks with `isinstance()`, static checks with `reveal_type()`
+
+## Common Frameworks
+
+| Category | Options |
+|----------|---------|
+| Web (async) | FastAPI, Starlette, Litestar |
+| Web (sync) | Django, Flask |
+| Database ORM | SQLAlchemy, Django ORM, SQLModel, Tortoise ORM |
+| Migrations | Alembic (SQLAlchemy), Django migrations |
+| Validation | Pydantic, attrs, marshmallow |
+| Task queues | Celery, Dramatiq, Huey, ARQ |
+| CLI | Click, Typer, argparse |
+| HTTP client | httpx, aiohttp, requests |
+
+## Example: Project-Level Override
+
+Create `.feature-forge/stack-decisions.md` (legacy alias: `.claude/references/stack-decisions.md`) in your project root:
+
+```markdown
+# Stack Decisions
+
+## Runtime & Build
+- Python 3.12 with uv for package management
+- src/ layout with pyproject.toml
+
+## Backend
+- FastAPI for HTTP framework
+- SQLAlchemy 2.0 with PostgreSQL (async)
+- Pydantic v2 for validation and serialization
+
+## Testing
+- pytest with pytest-asyncio
+- Factory Boy for test fixtures
+- Coverage target: 90%
+
+## Conventions
+- Google-style docstrings
+- ruff for linting and formatting
+- mypy with --strict for type checking
+- __all__ exports in every __init__.py
+```