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.