AI Coding Skills: PIV Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• CHANGELOG.md
• REVIEW.md
• packages/web/CLAUDE.md
• packages/api.tests/Users/UserServiceTests.cs
• packages/api.tests/Contracts/ContractServiceTests.cs
• packages/web/src/routes/_authed/admin/users/-components/form.tsx
• packages/web/src/routes/_authed/admin/contracts/-components/form.tsx

The PIV Workflow (Plan, Implement, Validate) is a structured development methodology utilized within the tsz repository to ensure consistent, high-quality feature delivery. It synchronizes the efforts of AI agents and developers by breaking down tasks into three distinct phases: architectural planning, technical implementation, and comprehensive validation through testing and documentation.

This workflow is evidenced by the project's development history, where features like S3 Contracts, S4 Leave Types, and S5 User Leave Configurations were introduced through specific "chore(skills)" updates adding piv-plan, piv-implement, and piv-validate capabilities to the AI agents.
Sources: CHANGELOG.md:15-20, CHANGELOG.md:23-24

Workflow Phases

1. Plan (P)

The planning phase involves defining the scope, technical requirements, and architectural impact of a new feature. In this project, planning typically focuses on monorepo structure, ensuring .NET backend modules are properly decoupled and TanStack Start frontend routes are correctly mapped.

Key planning considerations identified in code reviews include:

• Module Separation: Moving configuration responsibility to individual modules rather than a monolithic Program.cs.
• DTO Definition: Planning API endpoints to use Data Transfer Objects (DTOs) instead of exposing full database entities.
• Validation Strategy: Defining Zod schemas that are shared between frontend forms and server functions.
  Sources: REVIEW.md:3-8, REVIEW.md:57-59, packages/web/CLAUDE.md:15-18

2. Implement (I)

The implementation phase follows strict coding conventions for both the C# backend and TypeScript frontend. Implementation details are governed by component-specific guidelines like using shadcn/ui for the interface and @tanstack/react-form for data entry.

Layer	Technology / Pattern	Key Implementation Requirement
Backend	.NET / C#	Use per-module configuration extensions; avoid hardcoded strings.
Frontend	TanStack Start	Use createServerFn with .inputValidator (Zod).
UI	shadcn/ui	Use established components; avoid raw HTML.
Database	Entity Framework	Use Migrations and specific Table mappings (e.g., Counters, Tasks).
Sources: REVIEW.md:10-30, packages/web/CLAUDE.md:3-12, packages/api/Migrations/AppDb/20260515084245_AddContractsAndCounters.Designer.cs:25-50

3. Validate (V)

Validation ensures the feature meets business requirements and adheres to safety standards. This involves automated testing (unit and integration) and adherence to a validation document (e.g., VALIDATION.md).

The validation logic for core services includes:

• Service Tests: Testing variations of operations (sorting, pagination, archiving) and verifying business rules (e.g., end date cannot be before start date).
• Error Handling: Verifying that specific exceptions (like DuplicateEmailException or InvalidContractRequestException) are thrown correctly.
• Schema Consistency: Ensuring frontend Zod validation matches backend expectations.
  Sources: CHANGELOG.md:24, packages/api.tests/Users/UserServiceTests.cs:130-145, packages/api.tests/Contracts/ContractServiceTests.cs:140-155

Logic Flow and Architecture

The following diagram illustrates how a feature request flows through the PIV methodology into the project's technical layers.

The PIV flow ensures that schema definitions from the planning phase directly inform both the UI form logic and the backend service validation.
Sources: packages/web/CLAUDE.md:15-21, REVIEW.md:73-85

Data Interaction Pattern

When implementing a feature under PIV, the data flow between the client and server is strictly typed and validated at multiple points.

This sequence ensures that invalid data is caught as early as possible—first in the browser, then at the API edge via server functions.
Sources: packages/web/CLAUDE.md:15-18, packages/web/src/routes/_authed/admin/users/-components/form.tsx:47-58, packages/api.tests/Contracts/ContractServiceTests.cs:120-135

Key Validation Requirements

Technical debt and architectural integrity are monitored during the Validation phase. Code reviews highlight specific patterns that must be validated:

• Global Exception Handling: Moving away from catching every exception individually to using a global handler.
• DTO Usage: Ensuring API responses do not expose the internal database schema.
• Naming Conventions: Enforcing descriptive naming (e.g., cancellationToken instead of ct).
  Sources: REVIEW.md:46-55, CLAUDE.md:8-10

Conclusion

The PIV Workflow in the tsz project acts as a roadmap for scaling the application. By enforcing rigorous planning (through shared schemas), modular implementation (via per-module .NET extensions), and strict validation (through comprehensive service tests), the system remains maintainable even as complex features like multi-entity contracts and leave management are added.