forge-server 0.1.0

package/plugin/skills/nestjs/workflow-optimization.md

@@ -0,0 +1,229 @@
+# NestJS Skill Workflow Optimization Guide
+
+## Overview
+
+This document outlines optimized workflows for building NestJS applications with Drizzle ORM by leveraging parallel execution, subagent delegation, and dependency management strategies.
+
+## Key Optimization Principles
+
+### 1. Parallel Execution Strategy
+
+Tasks that can be executed simultaneously:
+- **Package Installation**: Install NestJS, Drizzle, testing, and development dependencies in parallel
+- **Module Scaffolding**: Create folder structures for multiple modules concurrently
+- **Interface/Type Definition**: Define DTOs and interfaces while setting up database schemas
+- **Test Preparation**: Set up test configuration while writing implementation code
+
+### 2. Sequential Dependencies
+
+Tasks that must follow a specific order:
+1. **Project Setup**: `npm install → nest new → cd project → install additional packages`
+2. **Database Setup**: `.env → drizzle.config.ts → schema → migrations → database service → repositories`
+3. **Feature Development**: `DTOs → Repository → Service → Controller → Module → Guards`
+4. **Testing**: `Unit tests → Integration tests → E2E tests`
+
+## Optimized Workflow Examples
+
+### Workflow 1: New NestJS Project with Drizzle ORM
+
+```yaml
+Phase 1: Parallel Setup (Agents: 2-3)
+  Agent 1: Project Initialization
+    - Create NestJS project
+    - Install core dependencies
+    - Configure TypeScript
+    - Set up basic folder structure
+
+  Agent 2: Database Preparation
+    - Install Drizzle packages
+    - Configure environment files
+    - Set up drizzle.config.ts
+    - Prepare database connection
+
+Phase 2: Core Configuration (Sequential)
+  - Database schema definition
+  - Migration generation
+  - Database service setup
+
+Phase 3: Parallel Feature Development (Agents: 2-4)
+  Agent 1: Data Layer
+    - Repository implementation
+    - Service layer logic
+    - Unit tests for data layer
+
+  Agent 2: API Layer
+    - Controller implementation
+    - DTOs and validation
+    - Route protection
+
+  Agent 3: Security
+    - Authentication setup
+    - Guards implementation
+    - Security middleware
+
+  Agent 4: Documentation
+    - OpenAPI decorators
+    - API documentation
+    - README generation
+
+Phase 4: Integration & Testing (Parallel)
+  - Integration tests
+  - E2E test scenarios
+  - Performance optimization
+```
+
+### Workflow 2: Adding New Feature Module
+
+```yaml
+Step 1: Parallel Preparation
+  - Define feature requirements
+  - Create module folder structure
+  - Prepare DTOs and interfaces
+  - Set up test files
+
+Step 2: Data Layer (Database Agent)
+  - Create/update schema
+  - Generate migrations
+  - Implement repository
+  - Write repository tests
+
+Step 3: Business Logic (Service Agent)
+  - Implement service methods
+  - Add business validation
+  - Handle transactions
+  - Write unit tests
+
+Step 4: API Layer (Controller Agent)
+  - Create controller endpoints
+  - Add validation pipes
+  - Implement guards
+  - Write integration tests
+
+Step 5: Security Integration (Security Agent)
+  - Add route protection
+  - Implement role-based access
+  - Add audit logging
+  - Security tests
+
+Step 6: Documentation (Documentation Agent)
+  - Add OpenAPI decorators
+  - Update API docs
+  - Create examples
+  - Review documentation
+```
+
+## Subagent Delegation Patterns
+
+### When to Delegate to Database Agent
+- Setting up new database connections
+- Complex schema migrations
+- Query optimization
+- Transaction management
+- Database testing setup
+
+### When to Delegate to Security Agent
+- Implementing authentication
+- Setting up authorization
+- Security audit requirements
+- OAuth integration
+- Vulnerability fixes
+
+### When to Delegate to Testing Agent
+- Comprehensive test suite creation
+- Test infrastructure setup
+- CI/CD test integration
+- Performance testing
+- Test data management
+
+## Best Practices for Optimization
+
+### 1. Dependency Management
+```typescript
+// Use async configuration for parallel setup
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    DatabaseModule,
+    AuthModule,
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Modular Architecture
+```typescript
+// Keep modules independent for parallel development
+@Module({
+  imports: [DatabaseModule],
+  controllers: [UsersController],
+  providers: [UsersService, UsersRepository],
+  exports: [UsersService],
+})
+export class UsersModule {}
+```
+
+### 3. Configuration-Driven Development
+```typescript
+// Enable environment-specific parallel development
+export default () => ({
+  database: {
+    url: process.env.DATABASE_URL,
+    poolSize: parseInt(process.env.DB_POOL_SIZE) || 10,
+  },
+  features: {
+    auth: process.env.ENABLE_AUTH === 'true',
+    caching: process.env.ENABLE_CACHE === 'true',
+  },
+});
+```
+
+### 4. Test-Driven Parallel Development
+```typescript
+// Write tests alongside implementation
+describe('UsersService', () => {
+  // Test setup can run in parallel with service implementation
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [UsersService, MockRepository],
+    }).compile();
+  });
+});
+```
+
+## Performance Optimization Techniques
+
+### 1. Database Optimizations
+- Use connection pooling
+- Implement query batching
+- Add proper indexes
+- Use database transactions wisely
+
+### 2. API Optimizations
+- Implement caching strategies
+- Use pagination
+- Add compression middleware
+- Optimize serialization
+
+### 3. Testing Optimizations
+- Parallel test execution
+- Test database reuse
+- Mock external services
+- Selective test runs
+
+## Monitoring and Feedback
+
+### 1. Workflow Metrics
+- Track time spent in each phase
+- Measure parallel execution efficiency
+- Monitor bottlenecks
+- Collect agent performance data
+
+### 2. Quality Gates
+- Code reviews before merging
+- Automated testing
+- Security scans
+- Performance benchmarks
+
+## Conclusion
+
+By following these optimized workflows and leveraging specialized subagents, NestJS development with Drizzle ORM can be significantly accelerated while maintaining high code quality and architectural integrity. The key is understanding task dependencies, maximizing parallel execution, and delegating specialized work to expert subagents.

package/plugin/skills/parallel-dispatch/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: parallel-dispatch
+description: >
+  This skill should be used when dispatching multiple implementation agents in parallel for
+  concurrent work. Used by the strategist and architect agents to coordinate horizontal scaling
+  of frontend, backend, data, and platform specialists.
+user-invocable: false
+---
+
+# Parallel Dispatch Skill
+
+## When to Parallelize
+
+Parallel dispatch is appropriate when work can be divided into independent units that do not share mutable state, do not depend on each other's outputs, and do not modify the same files. Recognize these opportunities:
+
+- **Independent modules**: two NestJS modules that share no providers, no database tables, and no imports between them. Example: a `notifications` module and a `billing` module can be built in parallel.
+- **Separate service boundaries**: a frontend agent building React pages while a backend agent builds API endpoints, provided the API contract (types, routes, response shapes) is established first.
+- **Isolated UI sections**: a settings page and a dashboard page that share a design system but no local state or cross-page logic.
+- **Separate infrastructure domains**: AWS CDK changes in `aws-infrastructure` and Helm/ArgoCD changes in `eks-addons-gitops` — different repos, different tools, no file conflicts.
+- **Independent test suites**: unit tests for module A and unit tests for module B can be written simultaneously if the modules are independent.
+- **Schema domains**: database tables for the `auth` domain and tables for the `content` domain can be designed in parallel if there are no foreign key relationships between them.
+
+## When NOT to Parallelize
+
+Parallel dispatch creates coordination overhead and merge risk. Avoid it when:
+
+- **Shared state**: two agents need to modify the same file, the same database table schema, or the same shared module. Parallel writes to the same file produce merge conflicts that waste more time than sequential execution would.
+- **Sequential dependencies**: agent B's work requires agent A's output as input. Example: the backend agent must define the API response types before the frontend agent can consume them. Create the shared types sequentially first, then dispatch in parallel.
+- **Cross-cutting concerns**: changes to authentication middleware, global error handling, logging infrastructure, or shared configuration affect all modules. Complete these before dispatching module-level work.
+- **Small scope**: if the total work is less than 30 minutes of sequential effort, parallelization overhead (prompt engineering, coordination, convergence verification) exceeds the time saved.
+- **High coupling**: if modules share many imports, call each other's services, or participate in the same transaction, they are too coupled for safe parallel implementation. Refactor the design to reduce coupling first, or implement sequentially.
+- **Unfamiliar territory**: if the architecture is uncertain or the agents will need to make design decisions that affect each other, sequential implementation with feedback loops is safer than parallel implementation with potential rework.
+
+## Task Isolation Principles
+
+Each dispatched agent must operate in a well-bounded scope with no ambiguity about what it owns.
+
+### The Isolation Checklist
+
+Before dispatching, verify each task against this checklist:
+
+1. **File ownership is exclusive.** No two agents create or modify the same file. If a shared file must be modified (e.g., `app.module.ts` to register new modules), designate one agent as the owner and have others report their additions for that agent to integrate.
+2. **Directory ownership is clear.** Each agent works in a distinct directory subtree. Example: agent A owns `src/modules/auth/`, agent B owns `src/modules/content/`.
+3. **Database table ownership is exclusive.** Each agent creates/modifies only the tables in its domain. If a foreign key crosses domains, define the relationship in the architecture document and have the agent that owns the referencing table create the FK after both tables exist.
+4. **Shared types are pre-created.** Any interfaces, DTOs, or enums used by multiple agents must be created sequentially before parallel dispatch. Place these in `src/shared/` or `src/common/` and instruct all agents to import (not duplicate) them.
+5. **Environment variables are documented.** If an agent needs new env vars, it documents them in its task output rather than modifying `.env` files directly (to avoid merge conflicts).
+
+### The Single-Responsibility Rule
+
+Each dispatched task should have exactly one primary deliverable. Not "build the auth module and also set up the CI pipeline." One agent, one module, one clear scope. If a task feels like it has two parts, split it into two dispatched agents.
+
+## Partition Strategy by Agent Type
+
+### Frontend Partitioning
+
+Partition frontend work by page, feature, or component group. Each agent receives:
+
+- The relevant section of `xd-plan.md` describing the UI for their scope.
+- The API contract (endpoints, request/response types) from `architecture.md` for data fetching.
+- The design system tokens and shared component inventory (so they use existing components, not create duplicates).
+- A list of pages/components they own and explicitly do NOT own.
+
+Example partition for a dashboard application:
+
+| Agent | Scope | Files Owned |
+|-------|-------|-------------|
+| Frontend-A | Dashboard page, widgets, data visualization | `src/pages/dashboard/`, `src/components/widgets/` |
+| Frontend-B | Settings pages, user preferences, profile | `src/pages/settings/`, `src/components/profile/` |
+| Frontend-C | Navigation, layout shell, shared layout components | `src/components/layout/`, `src/components/nav/` |
+
+Frontend-C (layout) should be dispatched first or sequentially, as pages depend on the layout shell.
+
+### Backend Partitioning
+
+Partition backend work by NestJS module or endpoint group. Each agent receives:
+
+- The relevant section of `architecture.md` describing the module's responsibilities, API endpoints, and data model.
+- The database schema for their domain (tables, relationships, indexes).
+- The shared DTOs/interfaces pre-created in `src/common/`.
+- Clear boundaries: which endpoints, which database tables, which service methods.
+
+Example partition for a content management backend:
+
+| Agent | Scope | Files Owned |
+|-------|-------|-------------|
+| Backend-A | Auth module: login, registration, JWT, RBAC | `src/modules/auth/` |
+| Backend-B | Content module: CRUD, versioning, publishing | `src/modules/content/` |
+| Backend-C | Media module: upload, processing, CDN integration | `src/modules/media/` |
+
+### Data Partitioning
+
+Partition data work by schema domain, migration set, or seed data category. Each agent receives:
+
+- The relevant entity-relationship section of `architecture.md`.
+- Clear table ownership (which tables to create, which to reference but not modify).
+- Seed data specifications (what realistic test data to generate for their domain).
+- Migration ordering constraints (if table B references table A, the migration for A must run first — specify this ordering).
+
+Example partition:
+
+| Agent | Scope | Tables Owned |
+|-------|-------|-------------|
+| Data-A | Auth schema: users, roles, permissions, sessions | `users`, `roles`, `user_roles`, `sessions` |
+| Data-B | Content schema: documents, versions, categories, tags | `documents`, `versions`, `categories`, `document_tags` |
+
+### Platform Partitioning
+
+Partition platform/infrastructure work by repository and resource domain. Each agent receives:
+
+- The specific IaC repo to work in (`aws-infrastructure` vs. `eks-addons-gitops`).
+- The resources to create or modify (IAM roles, S3 buckets, Helm charts, ArgoCD apps).
+- The naming conventions from the project's CLAUDE.md (kebab-case identifiers, Helm chart names, namespace names, etc.).
+- Cross-references to the other platform agent's work (e.g., "the IRSA role ARN from aws-infrastructure will be referenced in the Helm values in eks-addons-gitops").
+
+Example partition:
+
+| Agent | Scope | Repo |
+|-------|-------|------|
+| Platform-A | IAM roles, IRSA, ECR, RDS security groups | `aws-infrastructure` |
+| Platform-B | Helm charts, ArgoCD apps, namespace config, service accounts | `eks-addons-gitops` |
+
+## Task Description Format
+
+Each dispatched task must include a structured description that leaves no room for ambiguity. Use this template when constructing Task tool prompts:
+
+```
+TASK: {one-line summary}
+AGENT TYPE: {frontend | backend | data | platform | test}
+SCOPE: {module/page/domain name}
+
+PLAN REFERENCE:
+  Read: docs/plans/YYYY-MM-DD-{TITLE}/architecture.md, section "{Section Name}"
+  Read: docs/plans/YYYY-MM-DD-{TITLE}/xd-plan.md, section "{Section Name}" (frontend only)
+
+DELIVERABLES:
+  Create: {list of files/directories to create}
+  Modify: {list of existing files to modify, and what to add}
+
+SHARED DEPENDENCIES:
+  Import from: {list of shared types/interfaces to use, with file paths}
+  Do NOT create: {types/interfaces that already exist or belong to another agent}
+
+DO NOT TOUCH:
+  - {list of files/directories owned by other agents}
+  - {list of shared files that are off-limits}
+
+CONVENTIONS:
+  - {relevant naming conventions, code style, patterns}
+  - {framework-specific requirements: NestJS module structure, Drizzle schema patterns, etc.}
+
+COMPLETION CRITERIA:
+  - All files listed under DELIVERABLES exist and compile without errors
+  - All exports are properly defined
+  - Unit tests pass (if test agent)
+  - TypeScript strict mode: no any, no ts-ignore, no suppress
+
+HANDOFF:
+  When complete, write a summary to: docs/plans/YYYY-MM-DD-{TITLE}/agent-output/{agent-type}-{scope}.md
+  Include: files created, decisions made, open questions, integration points for other agents
+```
+
+## Coordination Points: The Sequential-Before-Parallel Pattern
+
+Not all work within a parallel dispatch is parallel. Some artifacts must be created sequentially before agents can fan out. Identify and complete these coordination points first.
+
+### Mandatory Sequential Steps
+
+1. **Shared type definitions.** DTOs, interfaces, enums, and Zod schemas used by more than one module. Create these in `src/common/` or `src/shared/` before dispatching.
+2. **Database schema foundation.** If multiple modules reference the same base tables (e.g., a `users` table referenced by both `auth` and `content`), create the base tables first.
+3. **Configuration and environment setup.** Shared configuration (database connection, JWT secret, API keys) must be established before any module that depends on it.
+4. **App module registration skeleton.** Create `app.module.ts` with placeholder imports for all modules, so each agent knows the registration structure.
+5. **API contract definitions.** If frontend and backend agents work in parallel, define the API contracts (routes, request/response types) before dispatching either.
+
+### Execution Pattern
+
+```
+Phase 1 (Sequential): Create shared types, base schema, configuration
+    |
+    v
+Phase 2 (Parallel): Dispatch module-level agents simultaneously
+    |
+    v
+Phase 3 (Sequential): Integration, module registration, cross-module wiring
+    |
+    v
+Phase 4 (Parallel): Dispatch test agents for each module simultaneously
+    |
+    v
+Phase 5 (Sequential): Convergence verification, E2E tests, final integration
+```
+
+## Convergence: Verifying Parallel Work Integrates
+
+After all parallel agents complete, run a convergence check before declaring the dispatch successful.
+
+### Convergence Checklist
+
+1. **Compilation check.** Run `tsc --noEmit` across the entire project. All modules must compile together, not just individually.
+2. **Import verification.** Verify that cross-module imports resolve correctly. Each module should import shared types from `src/common/`, not define its own duplicates.
+3. **Module registration.** Verify that `app.module.ts` imports all new modules and that NestJS bootstrap succeeds.
+4. **Database migration ordering.** Run all migrations in sequence and verify they apply without errors. Foreign key ordering matters.
+5. **API contract adherence.** For each frontend-backend pair, verify that the frontend's API calls match the backend's actual endpoints (route, method, request body, response shape).
+6. **No file conflicts.** Verify that no two agents created or modified the same file. If they did, manually merge and flag the isolation violation for future dispatch improvement.
+7. **Test suite passes.** Run the full test suite (`npm test`) and verify all tests pass together, not just individually.
+
+### The Inspector's Role
+
+After parallel dispatch completes and convergence is verified, the Inspector agent runs the **verification-protocol** skill to perform a deeper quality check. The Inspector examines:
+
+- Code consistency across modules (naming conventions, error handling patterns, logging patterns).
+- Security posture (no hardcoded secrets, proper input validation, correct auth guard usage).
+- Performance concerns (N+1 queries, missing indexes, unbounded queries).
+- Documentation completeness (JSDoc on public APIs, README updates, migration notes).
+
+## Using the Task Tool for Parallel Dispatch
+
+Invoke the Task tool for each parallel agent. Provide the model, a detailed prompt containing the full task description (using the template above), and set `run_in_background` for true parallelism.
+
+### Prompt Construction Guidelines
+
+- **Include the full task description** in the Task prompt. Do not assume the sub-agent has context from the parent conversation. Each sub-agent starts fresh.
+- **Include relevant plan document content.** Either inline the relevant sections of architecture.md/xd-plan.md or instruct the sub-agent to read them. Inlining is more reliable for long plans.
+- **Specify file paths absolutely.** Sub-agents do not share working directory context. Use absolute paths for all file references.
+- **Specify the anti-stub skill.** Instruct each sub-agent to implement fully — no placeholder functions, no TODO comments, no "implement later" stubs.
+- **Specify the test-strategy skill.** If the sub-agent should write tests, reference the test-strategy skill so it follows the project's testing conventions.
+
+### Monitoring and Collecting Results
+
+After dispatching all agents:
+
+1. Wait for all Task tool calls to complete. They run in background and report when finished.
+2. Collect the output from each agent. Check for errors, incomplete work, and open questions.
+3. Run the convergence checklist.
+4. Compile a dispatch report for the Strategist:
+
+```
+DISPATCH REPORT
+Dispatched: {N} agents
+Completed: {N} / {N}
+Failed: {list, if any}
+
+AGENT RESULTS:
+  {Agent-A}: {status} — {summary of deliverables}
+  {Agent-B}: {status} — {summary of deliverables}
+  ...
+
+CONVERGENCE:
+  Compilation: {pass/fail}
+  Imports: {pass/fail}
+  Module Registration: {pass/fail}
+  Migrations: {pass/fail}
+  Tests: {pass/fail}
+
+ISSUES:
+  - {any issues found during convergence}
+
+OPEN QUESTIONS:
+  - {questions raised by individual agents}
+```
+
+## Error Handling
+
+Parallel dispatch must be resilient to individual agent failures.
+
+### Failure Isolation
+
+- If one agent fails, the others continue. Failures are collected and reported, not propagated.
+- A failed agent's scope becomes "incomplete" and is flagged for retry or manual intervention.
+- Other agents' work remains valid as long as it does not depend on the failed agent's output (which it should not, per the isolation principles).
+
+### Common Failure Modes
+
+| Failure | Cause | Recovery |
+|---------|-------|----------|
+| Compilation error in one module | Missing type, wrong import | Fix the error, re-run only the failed agent |
+| File conflict between agents | Isolation violation — two agents touched the same file | Manually merge, update dispatch partitioning |
+| Agent exceeded scope | Agent modified files outside its designated area | Revert out-of-scope changes, re-run with stricter instructions |
+| Agent produced stubs | Agent left TODO/placeholder code | Re-dispatch with explicit anti-stub instructions |
+| Agent blocked on missing dependency | Sequential dependency not completed before dispatch | Complete the dependency, re-run the blocked agent |
+
+### Retry Strategy
+
+When retrying a failed agent:
+
+1. Do not re-dispatch all agents — only the failed one.
+2. Provide the failed agent with context about what went wrong (error messages, compilation output).
+3. Provide the failed agent with the completed outputs of the successful agents, so it can see what exists now.
+4. If the failure was due to an isolation violation, tighten the task description boundaries before retrying.
+
+## Scaling Considerations
+
+### How Many Agents to Dispatch Simultaneously
+
+- 2-3 agents: safe default for most features. Low coordination overhead, easy convergence.
+- 4-6 agents: appropriate for large features with clearly isolated modules. Higher coordination cost but significant time savings.
+- 7+ agents: rarely justified. Coordination overhead and merge risk dominate. Consider batching into two rounds of 3-4 instead.
+
+### When to Batch Dispatches
+
+If the total work requires more agents than can be safely parallelized:
+
+1. Group agents into batches by dependency order.
+2. Dispatch batch 1 (no cross-batch dependencies).
+3. Wait for batch 1 to complete and converge.
+4. Dispatch batch 2 (may depend on batch 1 outputs).
+5. Repeat until all batches are complete.
+
+This creates a "wave" pattern: sequential between waves, parallel within each wave.