openplanr 1.25.2 → 2.0.0

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/designer.md

@@ -0,0 +1,83 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/spec-driven/designer.md: spec-driven-mode-only content for designer-agent. Loaded by agents/designer-agent.md when MODE=spec-driven. T-002 of SPEC-002. -->
+
+> **Mode:** spec-driven
+> **Loaded by:** `agents/designer-agent.md` when the orchestrator passes `MODE=spec-driven` and `SPEC_DIR`.
+
+## Path Resolution
+
+The orchestrator (`/plan`) passes `MODE=spec-driven` and `SPEC_DIR`:
+
+- Read PNGs from `<SPEC_DIR>/design/*.png` (the user attached them via `planr spec attach-design`).
+- Write `<SPEC_DIR>/design/design-spec.md` (same `design/` subfolder).
+
+`<SPEC_DIR> = .planr/specs/SPEC-NNN-${ARGUMENTS}/`. The 10-section design-spec content is identical in both modes.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Feature/spec slug (`$ARGUMENTS`) | `/planr:plan` orchestrator | Yes |
+| `<SPEC_DIR>/SPEC-NNN-{slug}.md` (for `UIFiles:` resolution) | Product Owner | Yes |
+| Resolved PNGs from `<SPEC_DIR>/design/*.png` | UX Designer | Yes (triggers this agent) |
+| `input/tech/stack.md` | Tech Lead | Yes (for component library awareness) |
+
+---
+
+## Outputs
+
+| Output | Path | Description |
+|--------|------|-------------|
+| Design specification | `<SPEC_DIR>/design/design-spec.md` | 10-section design doc |
+
+---
+
+## Path expansion (applies to every PNG path)
+
+Before resolving any PNG path from `UIFiles:`, frontmatter, the orchestrator's brief, or an explicit argument:
+
+- Expand `~/foo` → `$HOME/foo` (read the runtime `$HOME` env var)
+- Expand `~user/foo` through the host's user-directory resolver; never hard-code a home path.
+- Resolve bare relative paths against the **project root** (working directory), NOT against `${CLAUDE_PLUGIN_ROOT}/references/pipeline`
+
+If a referenced path doesn't exist after expansion, try the unexpanded form as a fallback. If neither resolves, log the expected path and continue with the next priority source — do not error.
+
+## PNG Resolution (spec-driven mode)
+
+In spec-driven mode the canonical PNG location is `<SPEC_DIR>/design/*.png`. The user attaches PNGs via `planr spec attach-design`. If `<SPEC_DIR>/design/` is empty, the agent falls back through this priority order: `UIFiles:` block in the spec frontmatter, then `input/ui/feat-{slug}/`, then top-level `input/ui/*.png` under the single-feature exception.
+
+If all sources are empty: skip silently (do not write design-spec.md, do not error).
+
+---
+
+## Execution Steps
+
+```
+0. Receive spec slug from /planr:plan as $ARGUMENTS (the {slug} in SPEC-NNN-{slug})
+1. Resolve PNGs via the priority list (start at <SPEC_DIR>/design/*.png)
+   → If 0 PNGs resolve: skip silently and exit (no design-spec.md written)
+2. For each resolved PNG: analyze via Vision — extract colors, layout, components
+3. Cross-reference input/tech/stack.md to identify component library in use
+4. Compose design-spec.md following the 10-section template (see entry file)
+5. Write to <SPEC_DIR>/design/design-spec.md
+   (creating parent directories as needed)
+6. Log: "Designer Agent complete. N PNGs analyzed for SPEC-NNN-$ARGUMENTS. → design/design-spec.md"
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| No PNGs resolve for the spec | Skip silently — do not create design-spec.md |
+| PNG unreadable / corrupt | Log warning, skip that file, continue |
+| Cannot infer color precisely | Use closest approximation, flag in Open Questions |
+| No component library detected | Document as "custom / unknown", note in section 4 |
+
+---
+
+*Reads: `<SPEC_DIR>/design/*.png` · `input/tech/stack.md`*
+*Writes: `<SPEC_DIR>/design/design-spec.md`*
+*Chained to: specification-agent*

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/devops.md

@@ -0,0 +1,55 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/spec-driven/devops.md: spec-driven-mode-only content for devops-agent. Loaded by agents/devops-agent.md when MODE=spec-driven. T-002 of SPEC-002. -->
+
+> **Mode:** spec-driven
+> **Loaded by:** `agents/devops-agent.md` when the orchestrator passes `MODE=spec-driven` and `SPEC_DIR`.
+
+## Context locations
+
+Use the request and current repository as primary context. When present,
+`<SPEC_DIR> = .planr/specs/SPEC-NNN-${ARGUMENTS}/` provides useful specification,
+story, and task context; `input/tech/stack.md` and `output/db/schema.json` provide
+optional stack and database context.
+
+Infrastructure outputs normally remain at project-owned paths such as
+`docker-compose.yml`, `.env.example`, `Dockerfile.*`, and
+`.github/workflows/ci.yml`.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Explicit request and existing infrastructure files | User / repository | Primary |
+| `<SPEC_DIR>/` | Planning context | When useful |
+| `input/tech/stack.md` | Tech Lead | When present |
+| Relevant `${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/devops/*.md` file | Stack library | When it matches the stack |
+| `output/db/schema.json` | DB Agent | When DB service configuration is needed |
+
+---
+
+## Mode guidance
+
+```
+1. Locate the application services, existing infrastructure files, package/build
+   commands, and any useful specification context.
+2. Apply the entry agent's infrastructure guidance to the artifacts relevant to
+   the requested outcome.
+3. Check internal consistency in proportion to the change and report the result.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| Planning or stack artifact missing | Infer from repository configuration when safe and state material assumptions |
+| Database context missing | Avoid inventing database settings; use established configuration or flag the missing choice |
+| Existing infrastructure is hand-customized | Preserve intentional edits and make the smallest coherent change |
+
+---
+
+*Reads: request · current infrastructure · package/build config · relevant spec/stack/schema context*
+*Writes: docker-compose.yml · .env.example · Dockerfiles · CI workflow*
+*Does NOT deploy — per framework non-goals*

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/doc-gen.md

@@ -0,0 +1,67 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/spec-driven/doc-gen.md: spec-driven-mode-only content for doc-gen-agent. Loaded by agents/doc-gen-agent.md when MODE=spec-driven. T-002 of SPEC-002. -->
+
+> **Mode:** spec-driven
+> **Loaded by:** `agents/doc-gen-agent.md` when the orchestrator passes `MODE=spec-driven` and `SPEC_DIR`.
+
+## Path Resolution
+
+The orchestrator (`/ship`) passes `MODE=spec-driven` and `SPEC_DIR`:
+
+- Read US: `<SPEC_DIR>/stories/US-*.md`
+- Read tasks: `<SPEC_DIR>/tasks/T-*.md`
+- Read design-spec (optional): `<SPEC_DIR>/design/design-spec.md`
+
+`<SPEC_DIR> = .planr/specs/SPEC-NNN-${ARGUMENTS}/`. Output to `Docs/feat-${ARGUMENTS}/` is mode-agnostic.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Explicit request and maintained documentation | User / repository | Primary |
+| `<SPEC_DIR>/stories/US-*.md` | Specification Agent | When useful |
+| `<SPEC_DIR>/tasks/T-*.md` | Specification Agent | When useful |
+| Implemented source and tests | Repository | When documenting behavior |
+| `<SPEC_DIR>/design/design-spec.md` | Designer Agent | When relevant |
+| `input/tech/stack.md` | Tech Lead | When relevant |
+
+---
+
+## Outputs
+
+| Output | Path | Description |
+|--------|------|-------------|
+| Feature index | `Docs/feat-{name}/README.md` | Overview, US list, links |
+| US summary | `Docs/feat-{name}/us-{slug}.md` | Per-US plain-language summary + acceptance criteria |
+| API reference | `Docs/feat-{name}/api.md` | All endpoints with request/response shapes (from Tech tasks + actual handlers) |
+| Architecture note | `Docs/feat-{name}/architecture.md` | High-level diagram-as-text, file map, key abstractions |
+
+---
+
+## Execution Steps
+
+```
+1. Read the request, existing maintained docs, relevant specification/design
+   context, and the implemented source and tests that establish behavior.
+2. Identify the documentation surfaces materially affected by the change.
+3. Update those surfaces using the repository's current structure, or the default
+   `Docs/feat-$ARGUMENTS/` shapes when no stronger convention exists.
+4. Verify relevant links, commands, examples, API shapes, and code references.
+5. Return the changed paths, checks, and any material intent/implementation drift.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| Planning artifact missing | Use the request, source, tests, and maintained docs; state any material assumption |
+| Endpoint described in planning is not found in code | Document observed behavior and flag the discrepancy clearly |
+| `Docs/feat-{name}/` already exists with hand-edits | Preserve user-marked sections (look for `<!-- HUMAN -->` markers), regenerate AI sections |
+
+---
+
+*Reads: request · maintained docs · relevant spec/design context · source · tests · stack context*
+*Writes: `Docs/feat-{name}/*.md`*

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/frontend.md

@@ -0,0 +1,96 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/spec-driven/frontend.md: spec-driven-mode-only content for frontend-agent. Loaded by agents/frontend-agent.md when MODE=spec-driven. T-002 of SPEC-002. -->
+
+> **Mode:** spec-driven
+> **Loaded by:** `agents/frontend-agent.md` when the orchestrator passes `MODE=spec-driven` and `SPEC_DIR`.
+
+## Path Resolution
+
+The orchestrator (`/ship`) passes the absolute task file path,
+`MODE=spec-driven`, and `SPEC_DIR`. Use that exact task path first.
+
+- Spec directory: `.planr/specs/SPEC-NNN-{slug}/`.
+- Task: `<SPEC_DIR>/tasks/T-NNN-{slug}.md`.
+- Specification: the single `<SPEC_DIR>/SPEC-NNN-*.md` whose ID matches
+  `specId`.
+- Parent story: `<SPEC_DIR>/stories/{storyId}-*.md`.
+- Optional acceptance scenarios: `<SPEC_DIR>/stories/{storyId}-gherkin.feature`
+  when present; story Markdown remains canonical.
+- Design context: `<SPEC_DIR>/design/design-spec.md` when present.
+- Dependencies: resolve each `dependsOn` ID against task frontmatter in the flat
+  `<SPEC_DIR>/tasks/` directory.
+
+If `SPEC_DIR` was not passed, resolve it from the explicit SPEC ID or slug under
+`.planr/specs/` and use it only when the match is unique. If no exact task path
+was passed, match the explicit task ID or slug only inside that spec's `tasks/`
+directory and use it only when unique. Follow
+`${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/task-context-resolution.md` after resolving
+the file. Task content is schema-identical in both modes; only paths differ.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `<SPEC_DIR>/tasks/T-NNN-{slug}.md` (Type=UI) | Specification Agent | Yes |
+| `<SPEC_DIR>/design/design-spec.md` | Designer Agent | If exists |
+| `input/tech/stack.md` | Tech Lead | Yes |
+| Existing codebase files (for context) | Dev environment | Read-only for context |
+
+---
+
+## Outputs
+
+All files listed under `### Create` and `### Modify` in the task file (`<SPEC_DIR>/tasks/T-NNN-{slug}.md`).
+
+---
+
+## Implementation guidance
+
+```
+1. Load `<SPEC_DIR>/tasks/T-NNN-{slug}.md` and extract frontmatter,
+   Create/Modify/Preserve, Objective, Implementation or Technical Spec,
+   Verification, and Done When. Follow `storyId` to the story, load its optional
+   Gherkin sidecar when present, then load the enclosing specification.
+2. Load `input/tech/stack.md`. Resolve every `ActiveStackFiles` entry through the
+   installed stack root and the project-local `.openplanr/stacks` overlay as
+   defined by the shared task-context guidance.
+3. Read each declared predecessor's output contract when `dependsOn` is non-empty.
+   Load `<SPEC_DIR>/design/design-spec.md` when it exists.
+4. Read the listed files, reusable UI, design-system implementation, and enough
+   connected source to understand established interfaces and patterns.
+5. Implement the requested UI behavior completely using established project and
+   design-system patterns. Cover material loading, empty, error, success, and
+   accessibility behavior.
+6. Add meaningful component, interaction, and browser coverage where it improves
+   confidence.
+7. Treat Create/Modify as expected scope. A directly required companion test,
+   story, fixture, route registration, generated file, or configuration change is
+   valid when it serves acceptance criteria, stays within frontend ownership, and
+   remains outside Preserve. Disclose it in the result.
+8. Keep Preserve paths unchanged. If the requested outcome conflicts with one,
+   find a safe in-scope alternative or report the conflict clearly.
+9. Apply `${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/shared/verification-and-recovery-frontend.md` for
+   adaptive verification and recovery.
+10. Return the shared implementation-result format.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| SPEC_DIR or Ship task path missing/ambiguous | Report the selector, searched directory, and candidates; do not guess |
+| Parent story or spec missing | Continue from the task and source when sufficient; list the missing path under Issues |
+| Active stack file missing | Report the logical path and both lookup locations; use the installed default when available |
+| design-spec.md missing | Use the existing design system; report the missing path only when the task depends on absent tokens or states |
+| Component library unavailable | Report the import/package and affected UI; use an established project alternative when one exists |
+| `dependsOn` output unavailable | Name the dependency and required interface; continue independent work and report the blocked portion |
+| Preserve path changed | Restore it, use another implementation approach, and report a conflict only if no safe approach remains |
+
+---
+
+*Reads: task · spec/story/Gherkin · dependency outputs · stack overlays · design · source*
+*Writes: UI layer files only*
+*Runs in parallel with: Backend Agent (Tech task)*

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/qa.md

@@ -0,0 +1,17 @@
+<!-- Spec-driven inputs for planr-qa. -->
+
+# Spec-driven QA context
+
+Use the supplied `SPEC_DIR` and task scope to locate relevant context:
+
+- Task contracts: `<SPEC_DIR>/tasks/T-*.md`, excluding failure reports.
+- Parent context: `<SPEC_DIR>/SPEC-*.md`, referenced stories, and Gherkin files.
+- Design context: `<SPEC_DIR>/design/design-spec.md` when UI work exists.
+- Stack commands and conventions: `input/tech/stack.md`.
+- Prior failure notes: `<SPEC_DIR>/tasks/T-*-error-report.md` when relevant.
+- Implementation evidence: the scoped diff, source, tests, and command output.
+
+These are useful sources, not prerequisites. If an artifact is missing, use the
+request and repository evidence that exists. Review only the relevant scope and
+return the direct human-readable response defined by the loaded QA agent. Do not
+write a QA report or change project state.

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/spec-driven/specification.md

@@ -0,0 +1,112 @@
+<!-- ${CLAUDE_PLUGIN_ROOT}/references/agents/shared/modes/spec-driven/specification.md: spec-driven-mode-only content for specification-agent. Loaded by agents/specification-agent.md when MODE=spec-driven. T-002 of SPEC-002. -->
+
+> **Mode:** spec-driven
+> **Loaded by:** `agents/specification-agent.md` when the orchestrator passes `MODE=spec-driven` and `SPEC_DIR`.
+
+## Path Resolution
+
+The orchestrator (`/plan`) passes `MODE=spec-driven` and `SPEC_DIR`:
+
+- Output goes to `<SPEC_DIR>/{stories/US-NNN-{slug}.md, tasks/T-NNN-{slug}.md}` (slug-based filenames and a flat tasks/ directory).
+
+`<SPEC_DIR> = .planr/specs/SPEC-NNN-${ARGUMENTS}/`. Protocol 1.7 `SPEC-NNN`, `US-NNN`, and `T-NNN` IDs are project-global, monotonic, and never reused. Schema content is identical in both modes.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `<SPEC_DIR>/SPEC-NNN-{slug}.md` or explicit request | User / Product Owner | Use strongest available |
+| `input/tech/stack.md` | Tech Lead | Load when present |
+| `output/db/schema.json` | DB Agent | If DB interaction required |
+| `<SPEC_DIR>/design/design-spec.md` | Designer Agent | If PNGs were present |
+
+---
+
+## Outputs
+
+| Output | Path | Description |
+|--------|------|-------------|
+| User Story N | `<SPEC_DIR>/stories/US-NNN-{slug}.md` | One file per US (project-global ID) |
+| Task M (UI) | `<SPEC_DIR>/tasks/T-NNN-{slug}.md` | UI layer task (Type=UI) |
+| Task M (Tech) | `<SPEC_DIR>/tasks/T-NNN-{slug}.md` | Tech layer task (Type=Tech) |
+
+The flat `tasks/` directory is intentional — `storyId` frontmatter on each task links it back to its parent US-NNN.
+
+---
+
+## Deterministic execution
+
+```
+0. Resolve $ARGUMENTS and `<SPEC_DIR>` as
+   `.planr/specs/SPEC-NNN-$ARGUMENTS/`.
+1. Load `<SPEC_DIR>/SPEC-NNN-$ARGUMENTS.md`. If it is absent, use the explicit
+   request when it contains enough product intent; otherwise report the missing
+   path and the specific decision still needed.
+2. Load `input/tech/stack.md` when present.
+   a. Read its `ActiveStackFiles` entries in declared order.
+   b. For each entry, load the installed default from
+      `${CLAUDE_PLUGIN_ROOT}/references/pipeline/stacks/...` first, then load the matching
+      `.openplanr/stacks/...` file when present. The project file overrides
+      the installed file on a filename collision.
+   c. Apply the resulting folder, naming, framework, testing, and integration
+      conventions when selecting task paths. If a declared stack file cannot be
+      resolved in either location, report that exact entry and continue with the
+      remaining valid context.
+3. Detect design intent deterministically:
+   a. load `<SPEC_DIR>/design/design-spec.md` when it exists; or
+   b. when no design spec exists, inspect `<SPEC_DIR>/design/*.png`, followed by
+      the designer's documented `UIFiles` and default-mode fallbacks.
+   Set `has_design = true` when either a design spec or valid design input exists.
+4. Load `output/db/schema.json` when the spec or stack indicates database work.
+   If it is expected but absent, identify the affected story/task and record the
+   missing schema as an implementation note rather than inventing tables.
+5. Decompose the source into independently valuable User Stories and write each
+   story to `<SPEC_DIR>/stories/US-NNN-{slug}.md`. Use `specId: "SPEC-NNN"` and
+   allocate story IDs from the project-global sequence.
+6. Apply R2 to each story while assigning the next task IDs under the flat
+   `<SPEC_DIR>/tasks/` directory:
+   a. `has_design = true`: write one `type: "UI"` /
+      `agent: "frontend-agent"` task and one `type: "Tech"` /
+      `agent: "backend-agent"` task;
+   b. `has_design = false`: write one `type: "Tech"` /
+      `agent: "backend-agent"` task;
+   c. never write a third task for the story.
+7. Populate every task with its required schema fields, `storyId`, mode parent
+   `specId`, 1–3 sentence `rationale`, concrete Create/Modify paths,
+   verification, and `preserve` block maps with exact `repositoryKey` and `path`
+   fields (or `preserve: []`). The task body remains readable task context; it
+   does not replace the canonical frontmatter fields.
+8. Assign stable `AC-NNN` story criteria. Populate task `reviewRisks`,
+   `browserSurfaces`, and `acceptanceRefs` arrays; map every criterion to at
+   least one task and repeat its verification statement under Test Requirements.
+9. Set `dependsOn` only when a task consumes another task's output. Task IDs and
+   dependencies are project-global. Empty or absent means parallel;
+   do not derive dependencies from file overlap, shared paths, or write sets and
+   do not bury a hard dependency only in prose.
+10. Validate the written paths and frontmatter against the output table,
+   Protocol 1.7 `story.schema.json` and `task.schema.json`, and complete
+   acceptance coverage. Report every path, then end with the exact ready task
+   selector and `/planr:ship T-NNN`. Do not start Ship.
+```
+
+---
+
+## Error Handling (mode-specific paths)
+
+| Error | Response |
+|-------|----------|
+| `<SPEC_DIR>/SPEC-NNN-{slug}.md` missing | Name the missing path; use explicit product intent when sufficient, otherwise ask for the one missing decision |
+| `stack.md` missing | Report the path, infer conventions from the repository, and mark material assumptions |
+| Active stack entry missing or malformed | Name the exact entry and both lookup roots; continue with other valid entries |
+| Design input exists but `design-spec.md` is missing | Keep `has_design = true`, create the UI task, and report that design extraction/context is incomplete |
+| Ambiguous scope in spec | Decompose unaffected scope and identify the exact ambiguity in Delivery Notes |
+| DB schema missing but DB tasks needed | Identify the affected task and note `schema.json not found — verify the data contract before implementation` |
+| Story/task schema mismatch | Report the artifact path, field, expected shape, and correction; do not present malformed output as complete |
+
+---
+
+*Reads: spec · stack · design-spec · schema.json (all under `<SPEC_DIR>/...`)*
+*Writes: `<SPEC_DIR>/stories/` · `<SPEC_DIR>/tasks/`*
+*Produces schema-compatible planning artifacts and a concise diagnostic summary.*

package/lib/host-packages/claude/openplanr/references/pipeline/stacks/backend/nestjs.md

@@ -0,0 +1,130 @@
+# Stack: NestJS
+
+> **Category:** backend
+> **Version:** 10.x
+> **Docs:** https://docs.nestjs.com
+> **Created:** Template — copy to `.claude/stacks/backend/nestjs.md` in your project to override.
+
+---
+
+## Overview
+
+NestJS is a progressive Node.js framework for building server-side applications.
+Uses TypeScript, decorators, and dependency injection.
+Modular architecture with feature modules.
+
+---
+
+## Project Structure
+
+```
+src/
+├── main.ts                      ← Entry point
+├── app.module.ts                ← Root module
+├── common/
+│   ├── decorators/              ← Custom decorators
+│   ├── filters/                 ← Exception filters
+│   ├── guards/                  ← Auth guards
+│   ├── interceptors/            ← Request/response interceptors
+│   ├── middleware/              ← Middleware
+│   └── pipes/                   ← Validation pipes
+├── config/
+│   └── configuration.ts         ← App config (env vars)
+└── features/
+    └── {feature}/
+        ├── {feature}.module.ts
+        ├── {feature}.controller.ts
+        ├── {feature}.service.ts
+        ├── dto/
+        │   ├── create-{feature}.dto.ts
+        │   └── update-{feature}.dto.ts
+        ├── entities/
+        │   └── {feature}.entity.ts
+        └── {feature}.service.spec.ts
+```
+
+---
+
+## Code Patterns
+
+### Module
+```typescript
+// features/{feature}/{feature}.module.ts
+@Module({
+  imports: [TypeOrmModule.forFeature([{Feature}Entity])],
+  controllers: [{Feature}Controller],
+  providers: [{Feature}Service],
+  exports: [{Feature}Service],
+})
+export class {Feature}Module {}
+```
+
+### Controller
+```typescript
+// features/{feature}/{feature}.controller.ts
+@ApiTags('{feature}')
+@Controller('{feature}')
+export class {Feature}Controller {
+  constructor(private readonly service: {Feature}Service) {}
+
+  @Get()
+  findAll(): Promise<{Feature}Entity[]> {
+    return this.service.findAll()
+  }
+
+  @Post()
+  @HttpCode(201)
+  create(@Body() dto: Create{Feature}Dto): Promise<{Feature}Entity> {
+    return this.service.create(dto)
+  }
+}
+```
+
+### Service
+```typescript
+// features/{feature}/{feature}.service.ts
+@Injectable()
+export class {Feature}Service {
+  constructor(
+    @InjectRepository({Feature}Entity)
+    private readonly repo: Repository<{Feature}Entity>,
+  ) {}
+
+  async findAll(): Promise<{Feature}Entity[]> {
+    return this.repo.find()
+  }
+}
+```
+
+### DTO
+```typescript
+// features/{feature}/dto/create-{feature}.dto.ts
+import { IsString, IsNotEmpty, IsEmail } from 'class-validator'
+import { ApiProperty } from '@nestjs/swagger'
+
+export class Create{Feature}Dto {
+  @ApiProperty()
+  @IsString()
+  @IsNotEmpty()
+  name: string
+}
+```
+
+---
+
+## Integration Points
+
+- Database: TypeORM (configured in app.module.ts)
+- Validation: class-validator + class-transformer via ValidationPipe
+- Auth: Passport.js strategies + JWT guard
+- Docs: Swagger via @nestjs/swagger
+- Config: @nestjs/config + .env files
+
+---
+
+## Agent Usage Notes
+
+- Module path: `src/features/{feature}/{feature}.module.ts`
+- Always create module + controller + service + dto as a unit
+- Test file: `{feature}.service.spec.ts` co-located with service
+- Register new module in `app.module.ts` imports array