690404:1139 Modify ADR
This commit is contained in:
@@ -0,0 +1,85 @@
|
||||
---
|
||||
description: Run the full speckit pipeline from specification to analysis in one command.
|
||||
---
|
||||
|
||||
# Workflow: speckit.all
|
||||
|
||||
This meta-workflow orchestrates the **complete development lifecycle**, from specification through implementation and validation. For the preparation-only pipeline (steps 1-5), use `/speckit.prepare` instead.
|
||||
|
||||
## Preparation Phase (Steps 1-5)
|
||||
|
||||
1. **Specify** (`/speckit.specify`):
|
||||
- Use the `view_file` tool to read: `.agents/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: `.agents/skills/speckit.clarify/SKILL.md`
|
||||
- Execute to resolve ambiguities
|
||||
- Updates: `spec.md`
|
||||
|
||||
3. **Plan** (`/speckit.plan`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.plan/SKILL.md`
|
||||
- Execute to create technical design
|
||||
- Creates: `plan.md`
|
||||
|
||||
4. **Tasks** (`/speckit.tasks`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.tasks/SKILL.md`
|
||||
- Execute to generate task breakdown
|
||||
- Creates: `tasks.md`
|
||||
|
||||
5. **Analyze** (`/speckit.analyze`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.analyze/SKILL.md`
|
||||
- Execute to validate consistency across spec, plan, and tasks
|
||||
- Output: Analysis report
|
||||
- **Gate**: If critical issues found, stop and fix before proceeding
|
||||
|
||||
## Implementation Phase (Steps 6-7)
|
||||
|
||||
6. **Implement** (`/speckit.implement`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.implement/SKILL.md`
|
||||
- Execute all tasks from `tasks.md` with anti-regression protocols
|
||||
- Output: Working implementation
|
||||
|
||||
7. **Check** (`/speckit.checker`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.checker/SKILL.md`
|
||||
- Run static analysis (linters, type checkers, security scanners)
|
||||
- Output: Checker report
|
||||
|
||||
## Verification Phase (Steps 8-10)
|
||||
|
||||
8. **Test** (`/speckit.tester`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.tester/SKILL.md`
|
||||
- Run tests with coverage
|
||||
- Output: Test + coverage report
|
||||
|
||||
9. **Review** (`/speckit.reviewer`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.reviewer/SKILL.md`
|
||||
- Perform code review
|
||||
- Output: Review report with findings
|
||||
|
||||
10. **Validate** (`/speckit.validate`):
|
||||
- Use the `view_file` tool to read: `.agents/skills/speckit.validate/SKILL.md`
|
||||
- Verify implementation matches spec requirements
|
||||
- Output: Validation report (pass/fail)
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/speckit.all "Build a user authentication system with OAuth2 support"
|
||||
```
|
||||
|
||||
## Pipeline Comparison
|
||||
|
||||
| Pipeline | Steps | Use When |
|
||||
| ------------------ | ------------------------- | -------------------------------------- |
|
||||
| `/speckit.prepare` | 1-5 (Specify → Analyze) | Planning only — you'll implement later |
|
||||
| `/speckit.all` | 1-10 (Specify → Validate) | Full lifecycle in one pass |
|
||||
|
||||
## 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")
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
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
|
||||
|
||||
// turbo
|
||||
|
||||
1. **Verify requirements exist** — confirm the feature is in `specs/01-Requirements/` before starting
|
||||
|
||||
// turbo 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`.
|
||||
|
||||
// turbo 10. **Write unit test** — cover service methods with Jest mocks. Run:
|
||||
|
||||
```bash
|
||||
pnpm test:watch
|
||||
```
|
||||
|
||||
// turbo 11. **Citation** — confirm implementation references `specs/01-Requirements/` and `specs/05-Engineering-Guidelines/05-02-backend-guidelines.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`
|
||||
@@ -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 |
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
auto_execution_mode: 0
|
||||
description: Review code changes for bugs, security issues, and improvements
|
||||
---
|
||||
|
||||
You are a senior software engineer performing a thorough code review to identify potential bugs.
|
||||
|
||||
Your task is to find all potential bugs and code improvements in the code changes. Focus on:
|
||||
|
||||
1. Logic errors and incorrect behavior
|
||||
2. Edge cases that aren't handled
|
||||
3. Null/undefined reference issues
|
||||
4. Race conditions or concurrency issues
|
||||
5. Security vulnerabilities
|
||||
6. Improper resource management or resource leaks
|
||||
7. API contract violations
|
||||
8. Incorrect caching behavior, including cache staleness issues, cache key-related bugs, incorrect cache invalidation, and ineffective caching
|
||||
9. Violations of existing code patterns or conventions
|
||||
|
||||
## 🔴 Tier 1 Critical Rules (CI Blockers)
|
||||
|
||||
The following are **CI-blocking issues** that must be caught in code review. These align with project specs in `specs/05-Engineering-Guidelines/` and `specs/06-Decision-Records/`:
|
||||
|
||||
### ADR-019: UUID Handling
|
||||
|
||||
- **❌ NEVER use `parseInt()`, `Number()`, or `+` operator on UUID values**
|
||||
- Example of violation: `parseInt(projectId)` where `projectId` is UUID string
|
||||
- ✅ Correct: Use UUID string directly without conversion
|
||||
- **❌ NEVER expose internal INT PK in API responses**
|
||||
- API must expose only `publicId` (transformed to `id` via `@Expose()`)
|
||||
- Verify DTOs have `@Exclude()` on `id: number` field
|
||||
|
||||
### TypeScript Strict Rules
|
||||
|
||||
- **❌ ZERO `any` types allowed** — use proper types or `unknown` + narrowing
|
||||
- **❌ ZERO `console.log`** — must use NestJS `Logger` (backend) or remove (frontend)
|
||||
- **❌ NO `req: any` in controllers** — use `RequestWithUser` typed interface
|
||||
|
||||
### Database & Architecture
|
||||
|
||||
- **❌ NO SQL Triggers for business logic** — use NestJS Service methods instead
|
||||
- **❌ NO `.env` files in production** — use Docker environment variables
|
||||
- **❌ NO direct table/column name invention** — verify against `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`
|
||||
|
||||
### Security (ADR-016)
|
||||
|
||||
- Idempotency validation for critical `POST`/`PUT`/`PATCH` endpoints
|
||||
- Two-phase file upload pattern (Upload → Temp → Commit → Permanent)
|
||||
- Input validation with class-validator (backend) and Zod (frontend)
|
||||
|
||||
### Test Coverage Requirements
|
||||
|
||||
- **Backend Services:** 80% minimum
|
||||
- **Backend Overall:** 70% minimum
|
||||
- **Business Logic:** 80% minimum
|
||||
|
||||
Make sure to:
|
||||
|
||||
1. If exploring the codebase, call multiple tools in parallel for increased efficiency. Do not spend too much time exploring.
|
||||
2. If you find any pre-existing bugs in the code, you should also report those since it's important for us to maintain general code quality for the user.
|
||||
3. Do NOT report issues that are speculative or low-confidence. All your conclusions should be based on a complete understanding of the codebase.
|
||||
4. Remember that if you were given a specific git commit, it may not be checked out and local code states may be different.
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
description: Manage database schema changes following ADR-009 (no migrations, modify SQL directly)
|
||||
---
|
||||
|
||||
# Schema Change Workflow
|
||||
|
||||
Use this workflow when modifying database schema for LCBP3-DMS.
|
||||
Follows `specs/06-Decision-Records/ADR-009-database-strategy.md` — **NO TypeORM migrations**.
|
||||
|
||||
## Pre-Change Checklist
|
||||
|
||||
- [ ] Change is required by a spec in `specs/01-Requirements/`
|
||||
- [ ] Existing data impact has been assessed
|
||||
- [ ] No SQL triggers are being added (business logic in NestJS only)
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Read current schema** — load the full schema file:
|
||||
|
||||
```
|
||||
specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql
|
||||
```
|
||||
|
||||
2. **Read data dictionary** — understand current field definitions:
|
||||
|
||||
```
|
||||
specs/03-Data-and-Storage/03-01-data-dictionary.md
|
||||
```
|
||||
|
||||
// turbo 3. **Identify impact scope** — determine which tables, columns, indexes, or constraints are affected. List:
|
||||
|
||||
- Tables being modified/created
|
||||
- Columns being added/renamed/dropped
|
||||
- Foreign key relationships affected
|
||||
- Indexes being added/modified
|
||||
- Seed data impact (if any)
|
||||
|
||||
4. **Modify schema SQL** — edit `specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql`:
|
||||
- Add/modify table definitions
|
||||
- Maintain consistent formatting (uppercase SQL keywords, lowercase identifiers)
|
||||
- Add inline comments for new columns explaining purpose
|
||||
- Ensure `DEFAULT` values and `NOT NULL` constraints are correct
|
||||
- Add `version` column with `@VersionColumn()` marker comment if optimistic locking is needed
|
||||
|
||||
> [!CAUTION]
|
||||
> **NEVER use SQL Triggers.** All business logic must live in NestJS services.
|
||||
|
||||
5. **Update data dictionary** — edit `specs/03-Data-and-Storage/03-01-data-dictionary.md`:
|
||||
- Add new tables/columns with descriptions
|
||||
- Update data types and constraints
|
||||
- Document business rules for new fields
|
||||
- Add enum value definitions if applicable
|
||||
|
||||
6. **Update seed data** (if applicable):
|
||||
- `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-basic.sql` — for reference/lookup data
|
||||
- `specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-permissions.sql` — for new CASL permissions
|
||||
|
||||
7. **Update TypeORM entity** — modify corresponding `backend/src/modules/<module>/entities/*.entity.ts`:
|
||||
- Map ONLY columns defined in schema SQL
|
||||
- Use correct TypeORM decorators (`@Column`, `@PrimaryGeneratedColumn`, `@ManyToOne`, etc.)
|
||||
- Add `@VersionColumn()` if optimistic locking is needed
|
||||
|
||||
8. **Update DTOs** — if new columns are exposed via API:
|
||||
- Add fields to `create-*.dto.ts` and/or `update-*.dto.ts`
|
||||
- Add `class-validator` decorators for all new fields
|
||||
- Never use `any` type
|
||||
|
||||
// turbo 9. **Run type check** — verify no TypeScript errors:
|
||||
|
||||
```bash
|
||||
cd backend && npx tsc --noEmit
|
||||
```
|
||||
|
||||
10. **Generate SQL diff** — create a summary of changes for the user to apply manually:
|
||||
|
||||
```
|
||||
-- Schema Change Summary
|
||||
-- Date: <current date>
|
||||
-- Feature: <feature name>
|
||||
-- Tables affected: <list>
|
||||
--
|
||||
-- ⚠️ Apply this SQL to the live database manually:
|
||||
|
||||
ALTER TABLE ...;
|
||||
-- or
|
||||
CREATE TABLE ...;
|
||||
```
|
||||
|
||||
11. **Notify user** — present the SQL diff and remind them:
|
||||
- Apply the SQL change to the live database manually
|
||||
- Verify the change doesn't break existing data
|
||||
- Run `pnpm test` after applying to confirm entity mappings work
|
||||
|
||||
## Common Patterns
|
||||
|
||||
| Change Type | Template |
|
||||
| ----------- | -------------------------------------------------------------- |
|
||||
| Add column | `ALTER TABLE \`table\` ADD COLUMN \`col\` TYPE DEFAULT value;` |
|
||||
| Add table | Full `CREATE TABLE` with constraints and indexes |
|
||||
| Add index | `CREATE INDEX \`idx_table_col\` ON \`table\` (\`col\`);` |
|
||||
| Add FK | `ALTER TABLE \`child\` ADD CONSTRAINT ... FOREIGN KEY ...` |
|
||||
| Add enum | Add to data dictionary + `ENUM('val1','val2')` in column def |
|
||||
|
||||
## On Error
|
||||
|
||||
- If schema SQL has syntax errors → fix and re-validate with `tsc --noEmit`
|
||||
- If entity mapping doesn't match schema → compare column-by-column against SQL
|
||||
- If seed data conflicts → check unique constraints and foreign keys
|
||||
@@ -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 `.agents/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 `.agents/skills/speckit.clarify/SKILL.md`.
|
||||
|
||||
3. **Step 3: Plan (Skill 04)**
|
||||
- Goal: Generate `plan.md` from the finalized spec.
|
||||
- Action: Read and execute `.agents/skills/speckit.plan/SKILL.md`.
|
||||
|
||||
4. **Step 4: Tasks (Skill 05)**
|
||||
- Goal: Generate actionable `tasks.md` from the plan.
|
||||
- Action: Read and execute `.agents/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 `.agents/skills/speckit.analyze/SKILL.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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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
|
||||
@@ -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: `.agents/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`).
|
||||
@@ -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: `.agents/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."
|
||||
@@ -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: `.agents/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
|
||||
Reference in New Issue
Block a user