KArtSell.Aegis/docs/COMMON_WORKFLOWS.md

Common Workflows

Reference: For quick commands, see CLAUDE.md "Quick Start" section.
Governance: All work follows AGENTS.md v16.0 and VIBE Coding Guardrails.

Adding a New Vertical Slice

1. Scaffold the structure:

   python tools/scaffold_vertical_slice.py --name MyFeature --module ModelOperations
   

2. Define the contract (before code):

   • Request/Response DTOs in Contracts/
   • Event schema in Contracts/Events/ if async coupling needed
   • Validation rules (vee-validate schema on FE, Fluent on BE)

3. Implement backend slice:

   • Handler.cs: Orchestration, transaction handling
   • Policy.cs: Pure business logic
   • Sql.cs: Dapper queries (schema-qualified, no SELECT *)
   • Endpoint.cs: HTTP routing & status codes
   • README.md: Traceability link to requirement/ADR

4. Write tests:

   • Unit: Policy, Mapper logic
   • Integration: Handler + Dapper + real DB
   • Verify Outbox events are created if async

5. Implement frontend feature:

   • Feature module under features/<feature>/
   • Use features/<feature>/pages/ for route-level components
   • Use shared/ui/adapter/ for any UI component usage
   • Form validation with vee-validate + Zod schema from BE contract

6. Validation gates (pre-merge):

   • Architecture tests pass
   • DB migration is idempotent (fresh/upgrade test)
   • No SELECT *, no direct cross-module queries
   • Outbox/Inbox tests if async
   • Frontend typecheck + test + build
   • E2E smoke test (if user-facing)

Refactoring (Characterized, Isolated, Verified)

1. Characterize: Lock current behavior with tests + perf baseline + Golden data.
2. Isolate: Separate I/O (Dapper queries, HTTP) from logic (Policy).
3. Transform: One small change at a time (rename, extract, move).
4. Verify: All tests pass, no perf regression, backtest algorithm changes against Golden.
5. Simplify: Delete dead abstractions, feature flags, branches.
6. Observe: Post-release SLO/DQ/model drift monitoring.
7. Close Debt: Update Debt ID, leave ADR for future maintainers.

Creating a Background Job

1. Define the command:

   public class MyJobCommand : ICommand
   {
       public Guid IdempotencyKey { get; set; }
       public Guid CorrelationId { get; set; }
       public string InputData { get; set; }
   }
   

2. Implement the handler:

   • Idempotent: Re-run should be safe and produce same result.
   • Classify failures: transient/permanent/dq/business-hold.
   • Emit events to Outbox for async notifications.

3. Schedule via Hangfire:

   await backgroundJobClient.EnqueueAsync<MyJobHandler>(h => h.Handle(command));
   

4. Test retry & replay scenarios:

   • Job runs successfully.
   • Job fails and is retried (verify idempotency).
   • Job is replayed from cold state (verify determinism).

Testing Strategy

xUnit Backend Tests

dotnet test KArtSell.sln -c Release
dotnet test --filter "Category=Integration" -c Release
dotnet test --filter "FullyQualifiedName~UnitTests" -c Release --verbosity quiet

Test Levels:

1. Unit: Pure functions (Policy, Mapper), no I/O. Fast, deterministic.
2. Integration: Handler + Dapper + real PostgreSQL. Validates transaction boundaries, Outbox/Inbox.
3. Data: SQL query validation, schema conformance, index effectiveness.
4. E2E: Full HTTP stack; used sparingly for critical paths.
5. Golden/Frozen OOS: Before merging algorithm changes, lock baseline and diff against new run.

Vitest Frontend Tests

cd frontend
pnpm test                           # Run all tests
pnpm test -- --reporter=verbose     # Verbose output
pnpm test -- <test-file-pattern>    # Run subset
pnpm test -- --coverage             # Coverage report

Playwright E2E

cd frontend
pnpm e2e                            # Run all E2E tests headless
pnpm e2e -- --debug                 # Debug mode (browser stays open)
pnpm exec playwright test --headed  # Run with browser UI

Tools & Scripts

Scaffolding

python tools/scaffold_vertical_slice.py --name MyFeature --module ModelOperations
python tools/scaffold_ui_screen.py --name MyScreen --feature MyFeature

Validation

python tools/validate_v16.py          # Full v16 validation (contracts, migrations, Python tests)
python -m unittest discover           # Run all Python unit tests