260224:1606 20260224:1600 V1.8.0

.agents/workflows/00-speckit.all.md

@@ -0,0 +1,47 @@
+---
+description: Run the full speckit pipeline from specification to analysis in one command.
+---
+
+# Workflow: speckit.all
+
+This meta-workflow orchestrates the complete specification pipeline.
+
+## Pipeline Steps
+
+1. **Specify** (`/speckit.specify`):
+   - Use the `view_file` tool to read: `.agent/skills/speckit.specify/SKILL.md`
+   - Execute with user's feature description
+   - Creates: `spec.md`
+
+2. **Clarify** (`/speckit.clarify`):
+   - Use the `view_file` tool to read: `.agent/skills/speckit.clarify/SKILL.md`
+   - Execute to resolve ambiguities
+   - Updates: `spec.md`
+
+3. **Plan** (`/speckit.plan`):
+   - Use the `view_file` tool to read: `.agent/skills/speckit.plan/SKILL.md`
+   - Execute to create technical design
+   - Creates: `plan.md`
+
+4. **Tasks** (`/speckit.tasks`):
+   - Use the `view_file` tool to read: `.agent/skills/speckit.tasks/SKILL.md`
+   - Execute to generate task breakdown
+   - Creates: `tasks.md`
+
+5. **Analyze** (`/speckit.analyze`):
+   - Use the `view_file` tool to read: `.agent/skills/speckit.analyze/SKILL.md`
+   - Execute to validate consistency
+   - Output: Analysis report
+
+## Usage
+
+```
+/speckit.all "Build a user authentication system with OAuth2 support"
+```
+
+## On Error
+
+If any step fails, stop the pipeline and report:
+- Which step failed
+- The error message
+- Suggested remediation (e.g., "Run `/speckit.clarify` to resolve ambiguities before continuing")

.agents/workflows/01-speckit.constitution.md

@@ -0,0 +1,18 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+---
+
+# Workflow: speckit.constitution
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.constitution/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `.specify/` directory doesn't exist: Initialize the speckit structure first

.agents/workflows/02-speckit.specify.md

@@ -0,0 +1,19 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+# Workflow: speckit.specify
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+   - This is typically the starting point of a new feature.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.specify/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the feature description for the skill's logic.
+
+4. **On Error**:
+   - If no feature description provided: Ask the user to describe the feature they want to specify

.agents/workflows/03-speckit.clarify.md

@@ -0,0 +1,18 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+---
+
+# Workflow: speckit.clarify
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.clarify/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first to create the feature specification

.agents/workflows/04-speckit.plan.md

@@ -0,0 +1,18 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+# Workflow: speckit.plan
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.plan/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first to create the feature specification

.agents/workflows/05-speckit.tasks.md

@@ -0,0 +1,19 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+# Workflow: speckit.tasks
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.tasks/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `plan.md` is missing: Run `/speckit.plan` first
+   - If `spec.md` is missing: Run `/speckit.specify` first

.agents/workflows/06-speckit.analyze.md

@@ -0,0 +1,22 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+// turbo-all
+
+# Workflow: speckit.analyze
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.analyze/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first
+   - If `plan.md` is missing: Run `/speckit.plan` first
+   - If `tasks.md` is missing: Run `/speckit.tasks` first

.agents/workflows/07-speckit.implement.md

@@ -0,0 +1,20 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+# Workflow: speckit.implement
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.implement/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `tasks.md` is missing: Run `/speckit.tasks` first
+   - If `plan.md` is missing: Run `/speckit.plan` first
+   - If `spec.md` is missing: Run `/speckit.specify` first

.agents/workflows/08-speckit.checker.md

@@ -0,0 +1,21 @@
+---
+description: Run static analysis tools and aggregate results.
+---
+
+// turbo-all
+
+# Workflow: speckit.checker
+
+1. **Context Analysis**:
+   - The user may specify paths to check or run on entire project.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.checker/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no linting tools available: Report which tools to install based on project type
+   - If tools fail: Show raw error and suggest config fixes

.agents/workflows/09-speckit.tester.md

@@ -0,0 +1,21 @@
+---
+description: Execute tests, measure coverage, and report results.
+---
+
+// turbo-all
+
+# Workflow: speckit.tester
+
+1. **Context Analysis**:
+   - The user may specify test paths, options, or just run all tests.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.tester/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no test framework detected: Report "No test framework found. Install Jest, Vitest, Pytest, or similar."
+   - If tests fail: Show failure details and suggest fixes

.agents/workflows/10-speckit.reviewer.md

@@ -0,0 +1,19 @@
+---
+description: Perform code review with actionable feedback and suggestions.
+---
+
+# Workflow: speckit.reviewer
+
+1. **Context Analysis**:
+   - The user may specify files to review, "staged" for git staged changes, or "branch" for branch diff.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.reviewer/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no files to review: Ask user to stage changes or specify file paths
+   - If not a git repo: Review current directory files instead

.agents/workflows/11-speckit.validate.md

@@ -0,0 +1,19 @@
+---
+description: Validate that implementation matches specification requirements.
+---
+
+# Workflow: speckit.validate
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.validate/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `tasks.md` is missing: Run `/speckit.tasks` first
+   - If implementation not started: Run `/speckit.implement` first

.agents/workflows/create-backend-module.md

@@ -0,0 +1,49 @@
+---
+description: Create a new NestJS backend feature module following project standards
+---
+
+# Create NestJS Backend Module
+
+Use this workflow when creating a new feature module in `backend/src/modules/`.
+Follows `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md` and ADR-005.
+
+## Steps
+
+1. **Verify requirements exist** — confirm the feature is in `specs/01-Requirements/` before starting
+
+2. **Check schema** — read `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql` for relevant tables
+
+3. **Scaffold module folder**
+
+```
+backend/src/modules/<module-name>/
+├── <module-name>.module.ts
+├── <module-name>.controller.ts
+├── <module-name>.service.ts
+├── dto/
+│   ├── create-<module-name>.dto.ts
+│   └── update-<module-name>.dto.ts
+├── entities/
+│   └── <module-name>.entity.ts
+└── <module-name>.controller.spec.ts
+```
+
+4. **Create Entity** — map ONLY columns defined in the schema SQL. Use TypeORM decorators. Add `@VersionColumn()` if the entity needs optimistic locking.
+
+5. **Create DTOs** — use `class-validator` decorators. Never use `any`. Validate all inputs.
+
+6. **Create Service** — inject repository via constructor DI. Use transactions for multi-step writes. Add `Idempotency-Key` guard for POST/PUT/PATCH operations.
+
+7. **Create Controller** — apply `@UseGuards(JwtAuthGuard, CaslAbilityGuard)`. Use proper HTTP status codes. Document with `@ApiTags` and `@ApiOperation`.
+
+8. **Register in Module** — add to `imports`, `providers`, `controllers`, `exports` as needed.
+
+9. **Register in AppModule** — import the new module in `app.module.ts`.
+
+10. **Write unit test** — cover service methods with Jest mocks. Run:
+
+```bash
+pnpm test:watch
+```
+
+11. **Citation** — confirm implementation references `specs/01-Requirements/` and `specs/05-Engineering-Guidelines/05-02-backend-guidelines.md`

.agents/workflows/create-frontend-page.md

@@ -0,0 +1,64 @@
+---
+description: Create a new Next.js App Router page following project standards
+---
+
+# Create Next.js Frontend Page
+
+Use this workflow when creating a new page in `frontend/app/`.
+Follows `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`, ADR-011, ADR-012, ADR-013, ADR-014.
+
+## Steps
+
+1. **Determine route** — decide the route path, e.g. `app/(dashboard)/documents/page.tsx`
+
+2. **Classify components** — decide what is Server Component (default) vs Client Component (`'use client'`)
+   - Server Component: initial data load, static content, SEO
+   - Client Component: interactivity, forms, TanStack Query hooks, Zustand
+
+3. **Create page file** — Server Component by default:
+
+```typescript
+// app/(dashboard)/<route>/page.tsx
+import { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: '<Page Title> | LCBP3-DMS',
+};
+
+export default async function <PageName>Page() {
+  return (
+    <div>
+      {/* Page content */}
+    </div>
+  );
+}
+```
+
+4. **Create API hook** (if client-side data needed) — add to `hooks/use-<feature>.ts`:
+
+```typescript
+'use client';
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '@/lib/api-client';
+
+export function use<Feature>() {
+  return useQuery({
+    queryKey: ['<feature>'],
+    queryFn: () => apiClient.get('<endpoint>'),
+  });
+}
+```
+
+5. **Build UI components** — use Shadcn/UI primitives. Place reusable components in `components/<feature>/`.
+
+6. **Handle forms** — use React Hook Form + Zod schema validation. Never access form values without validation.
+
+7. **Handle errors** — add `error.tsx` alongside `page.tsx` for route-level error boundaries.
+
+8. **Add loading state** — add `loading.tsx` for Suspense fallback if page does async work.
+
+9. **Add to navigation** — update sidebar/nav config if the page should appear in the menu.
+
+10. **Access control** — ensure page checks CASL permissions. Redirect unauthorized users via middleware or `notFound()`.
+
+11. **Citation** — confirm implementation references `specs/01-Requirements/` and `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`

.agents/workflows/deploy.md

@@ -0,0 +1,71 @@
+---
+description: Deploy the application via Gitea Actions to QNAP Container Station
+---
+
+# Deploy to Production
+
+Use this workflow to deploy updated backend and/or frontend to QNAP via Gitea Actions CI/CD.
+Follows `specs/04-Infrastructure-OPS/` and ADR-015.
+
+## Pre-deployment Checklist
+
+- [ ] All tests pass locally (`pnpm test:watch`)
+- [ ] No TypeScript errors (`tsc --noEmit`)
+- [ ] No `any` types introduced
+- [ ] Schema changes applied to `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql`
+- [ ] Environment variables documented (NOT in `.env` files)
+
+## Steps
+
+1. **Commit and push to Gitea**
+
+```bash
+git status
+git add .
+git commit -m "feat(<scope>): <description>"
+git push origin main
+```
+
+2. **Monitor Gitea Actions** — open Gitea web UI → Actions tab → verify pipeline starts
+
+3. **Pipeline stages (automatic)**
+   - `build-backend` → Docker image build + push to registry
+   - `build-frontend` → Docker image build + push to registry
+   - `deploy` → SSH to QNAP → `docker compose pull` + `docker compose up -d`
+
+4. **Verify backend health**
+
+```bash
+curl http://<QNAP_IP>:3000/health
+# Expected: { "status": "ok" }
+```
+
+5. **Verify frontend**
+
+```bash
+curl -I http://<QNAP_IP>:3001
+# Expected: HTTP 200
+```
+
+6. **Check logs in Grafana** — navigate to Grafana → Loki → filter by container name
+   - Backend: `container_name="lcbp3-backend"`
+   - Frontend: `container_name="lcbp3-frontend"`
+
+7. **Verify database** — confirm schema changes are reflected (if any)
+
+8. **Rollback (if needed)**
+
+```bash
+# SSH into QNAP
+docker compose pull <service>=<previous-image-tag>
+docker compose up -d <service>
+```
+
+## Common Issues
+
+| Symptom           | Cause                 | Fix                                 |
+| ----------------- | --------------------- | ----------------------------------- |
+| Backend unhealthy | DB connection failed  | Check MariaDB container + env vars  |
+| Frontend blank    | Build error           | Check Next.js build logs in Grafana |
+| 502 Bad Gateway   | Container not started | `docker compose ps` to check status |
+| Pipeline stuck    | Gitea runner offline  | Restart runner on QNAP              |

.agents/workflows/speckit.prepare.md

@@ -0,0 +1,27 @@
+---
+description: Execute the full preparation pipeline (Specify -> Clarify -> Plan -> Tasks -> Analyze) in sequence.
+---
+
+# Workflow: speckit.prepare
+
+This workflow orchestrates the sequential execution of the Speckit preparation phase skills (02-06).
+
+1. **Step 1: Specify (Skill 02)**
+   - Goal: Create or update the `spec.md` based on user input.
+   - Action: Read and execute `.agent/skills/speckit.specify/SKILL.md`.
+
+2. **Step 2: Clarify (Skill 03)**
+   - Goal: Refine the `spec.md` by identifying and resolving ambiguities.
+   - Action: Read and execute `.agent/skills/speckit.clarify/SKILL.md`.
+
+3. **Step 3: Plan (Skill 04)**
+   - Goal: Generate `plan.md` from the finalized spec.
+   - Action: Read and execute `.agent/skills/speckit.plan/SKILL.md`.
+
+4. **Step 4: Tasks (Skill 05)**
+   - Goal: Generate actional `tasks.md` from the plan.
+   - Action: Read and execute `.agent/skills/speckit.tasks/SKILL.md`.
+
+5. **Step 5: Analyze (Skill 06)**
+   - Goal: Validate consistency across all design artifacts (spec, plan, tasks).
+   - Action: Read and execute `.agent/skills/speckit.analyze/SKILL.md`.

.agents/workflows/util-speckit.checklist.md

@@ -0,0 +1,18 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+# Workflow: speckit.checklist
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.checklist/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `spec.md` is missing: Run `/speckit.specify` first to create the feature specification

.agents/workflows/util-speckit.diff.md

@@ -0,0 +1,19 @@
+---
+description: Compare two versions of a spec or plan to highlight changes.
+---
+
+# Workflow: speckit.diff
+
+1. **Context Analysis**:
+   - The user has provided an input prompt (optional file paths or version references).
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.diff/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no files to compare: Use current feature's `spec.md` vs git HEAD
+   - If `spec.md` doesn't exist: Run `/speckit.specify` first

.agents/workflows/util-speckit.migrate.md

@@ -0,0 +1,19 @@
+---
+description: Migrate existing projects into the speckit structure by generating spec.md, plan.md, and tasks.md from existing code.
+---
+
+# Workflow: speckit.migrate
+
+1. **Context Analysis**:
+   - The user has provided an input prompt (path to analyze, feature name).
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.migrate/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If path doesn't exist: Ask user to provide valid directory path
+   - If no code found: Report that no analyzable code was detected

.agents/workflows/util-speckit.quizme.md

@@ -0,0 +1,20 @@
+---
+description: Challenge the specification with Socratic questioning to identify logical gaps, unhandled edge cases, and robustness issues.
+---
+
+// turbo-all
+
+# Workflow: speckit.quizme
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.quizme/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If required files don't exist, inform the user which prerequisite workflow to run first (e.g., `/speckit.specify` to create `spec.md`).

.agents/workflows/util-speckit.status.md

@@ -0,0 +1,20 @@
+---
+description: Display a dashboard showing feature status, completion percentage, and blockers.
+---
+
+// turbo-all
+
+# Workflow: speckit.status
+
+1. **Context Analysis**:
+   - The user may optionally specify a feature to focus on.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.status/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If no features exist: Report "No features found. Run `/speckit.specify` to create your first feature."

.agents/workflows/util-speckit.taskstoissues.md

@@ -0,0 +1,18 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+---
+
+# Workflow: speckit.taskstoissues
+
+1. **Context Analysis**:
+   - The user has provided an input prompt. Treat this as the primary input for the skill.
+
+2. **Load Skill**:
+   - Use the `view_file` tool to read the skill file at: `.agent/skills/speckit.taskstoissues/SKILL.md`
+
+3. **Execute**:
+   - Follow the instructions in the `SKILL.md` exactly.
+   - Apply the user's prompt as the input arguments/context for the skill's logic.
+
+4. **On Error**:
+   - If `tasks.md` is missing: Run `/speckit.tasks` first