planning-standards

Planning Standards Skill

Tech-specific plan generation guidance for the fullstack-typescript stack. Provides agent assignment rules, architecture patterns, and dependency ordering that the core planning skill uses when generating PLAN.md files for this tech pack.

Agent Assignment Rules

Each plan phase is assigned to the agent best suited for that component type. Agents are defined in the tech pack manifest (techpack.yaml under components.<type>.agent and lifecycle.<phase>.agent).

| Phase Type | Agent | Notes | |------------|-------|-------| | API / Contract design | api-designer | OpenAPI spec authoring, schema design, type generation | | Backend / Server implementation | backend-dev | CMDO architecture, Node.js/TypeScript services | | Frontend / Webapp implementation | frontend-dev | MVVM architecture, React/TanStack/TailwindCSS | | Database / Migration work | backend-dev | Load database-standards skill alongside backend standards | | Testing (integration, E2E) | tester | Vitest integration suites, Playwright E2E flows | | Infrastructure / Helm / CI/CD | devops | Helm charts, GitHub Actions pipelines, Kubernetes | | Review / Verification | reviewer | Not an explicit agent file -- use the lifecycle.verification path in the manifest |

Agent Selection Logic

1. Read components.<type>.agent from techpack.yaml for component implementation phases.
2. Read lifecycle.testing.agent for integration and E2E testing phases.
3. Read lifecycle.verification.agent for review phases.
4. When a phase touches multiple component types, assign the agent for the primary component and list secondary standards as additional skill references.

Architecture Patterns

Backend: CMDO (Controller-Model-DAL-Operator)

All server components follow the CMDO architecture. Plans referencing backend work should assume this layering.

| Layer | Responsibility | |-------|----------------| | Controller | HTTP handlers, request validation, dependency injection. Receives raw I/O from Operator and combines with config to create domain-specific operations. | | Model | Business logic split into definitions/ (TypeScript types only) and use-cases/ (one function per file, receives Dependencies). No external imports. | | DAL | Data Access Layer. One function per file, parameterized queries, maps DB rows to domain objects. No repository pattern. | | Operator | Process lifecycle management. Creates database connections, HTTP servers, telemetry. Manages startup/shutdown state machine and Unix signals. No domain knowledge. |

Plan phases for backend work should follow the implementation order: Contract first, then Model, then DAL, then Controller, then Operator (only if new infrastructure is needed).

Frontend: MVVM (Model-View-ViewModel)

All webapp components follow the MVVM architecture. Plans referencing frontend work should assume this layering.

| Layer | Responsibility | |-------|----------------| | View | React components styled with TailwindCSS and Shadcn UI. No business logic -- only renders data from ViewModel and calls ViewModel handlers. | | ViewModel | TanStack Query hooks for server state management. useReducer + Context for global client state. Connects Views to Models. | | Model | Business logic with no React dependencies. Framework-agnostic functions for formatting, validation, permissions, and transformations. |

Plan phases for frontend work should follow: API types consumed from contract packages first, then Model (business logic), then ViewModel (hooks), then View (components).

Dependency Ordering (API-First)

Plans must order phases by the tech pack's dependency graph. The fullstack-typescript stack follows an API-first approach where contracts define the interface before implementations are built.

| Order | Component Type | Rationale | |-------|---------------|-----------| | 1 | API Contracts / Interfaces | Define the API surface before anything consumes or implements it | | 2 | Data Models / Database | Schema and migrations before services that read/write data | | 3 | Backend Services / Business Logic | Implement API endpoints and business rules using contracts and database | | 4 | Frontend Components / UI | Consume contracts for type-safe API calls, render UI | | 5 | Infrastructure / DevOps | Helm charts and CI/CD pipelines after deployable components exist |

Scaffolding Phase

If any components listed in SPEC.md do not yet exist in sdd-settings.yaml, prepend a Phase 1: Component Scaffolding before the implementation phases. Scaffolding order follows the same dependency ordering above. See the scaffolding skill for orchestration details.

Testing Phases

After all implementation phases:

1. Integration Testing -- after server and database phases are complete.
2. E2E Testing -- after server and webapp phases are complete.

Review Phase

Always the final phase. Uses the verification lifecycle from the manifest, not a dedicated agent file.

Standards per Phase

Each plan phase must reference the applicable standards skills so the assigned agent loads them during implementation.

| Phase | Standards Skills | |-------|-----------------| | Contract | typescript-standards, contract-standards | | Backend | typescript-standards, backend-standards, database-standards, unit-testing | | Frontend | typescript-standards, frontend-standards, unit-testing | | Integration Testing | integration-testing-standards | | E2E Testing | e2e-testing-standards | | Infrastructure | helm-standards, cicd-standards |

Standards are resolved via the skills router: invoke techpacks.routeSkills(phase: implementation, component_type: <type>) to get the exact skill paths for the active tech pack.

Input / Output

This skill defines no input parameters or structured output. It is consumed as guidance by the core planning skill during plan generation.