Choreography: Multi-PDF Print and Bugs

Execution Sequence

Order	Run	Directory	Trigger	Agents	Repos
1	Bug Fixes	run-1-bug-fixes/	Manual	be-bug-fixes, fe-bug-fixes	operations, arda-frontend-app, documentation
2	Multi-Template	run-2-multi-template/	After Run 1 exit gate	be-multi-template, fe-multi-template	operations, arda-frontend-app, documentation
3	Diagnostics	run-3-diagnostics/	After Run 2 exit gate	be-diagnostics	operations, documentation
4	API Tests	run-4-api-tests/	After Run 3 exit gate + local deployment	ate-api-tests	api-test
5	API Proxy	run-5-api-proxy/	After Run 3 exit gate	ts-api-proxy	api-proxy

Runs 1→2→3 are strictly sequential. Runs 4 and 5 can execute in parallel after Run 3 — they operate on independent repositories with no code dependencies.

Worktree Strategy

All runs share the existing worktrees — no additional worktrees are needed. Runs commit sequentially to the same branch (jmpicnic/multi-pdf-print-and-bugs) in each repository.

Repository	Worktree Path	Branch
operations	/Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/operations	jmpicnic/multi-pdf-print-and-bugs
arda-frontend-app	/Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/arda-frontend-app	jmpicnic/multi-pdf-print-and-bugs
documentation	/Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/documentation	jmpicnic/multi-pdf-print-and-bugs
api-test	/Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/api-test	jmpicnic/multi-pdf-print-and-bugs
api-proxy	/Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/api-proxy	jmpicnic/multi-pdf-print-and-bugs

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
Fixed KanbanCardPrinter (notes)	Run 1	Run 2, Run 4	operations/src/.../KanbanCardPrinter.kt	Kotlin
UNMARK event type + endpoint	Run 1	Run 4	operations/src/.../KanbanCard.kt, KanbanCardEndpoint.kt	Kotlin
Frontend unmark action	Run 1	—	arda-frontend-app/src/.../CardInfo.tsx	TSX
CompositeRenderResult types	Run 2	Run 3, Run 4	operations/src/.../RenderResult.kt	Kotlin
PdfRenderService.renderGroups()	Run 2	Run 3	operations/src/.../PdfRenderService.kt	Kotlin
Printing config pattern	Run 2	Run 3	operations/src/.../application.conf	HOCON
Frontend composite handling	Run 2	—	arda-frontend-app/src/.../page.tsx	TSX
Diagnostic parameters	Run 3	Run 4	operations/src/.../ItemEndpoint.kt	Kotlin
debugPayload in GroupRenderResult	Run 3	Run 4	operations/src/.../RenderResult.kt	Kotlin
Bruno API tests	Run 4	—	api-test/collections/	Bruno
Updated api-proxy types + methods	Run 5	—	api-proxy/src/	TypeScript

Hand-Off Protocol

All hand-offs are filesystem-only — no in-memory state is shared between runs. Each run reads committed code from the worktree and writes its changes as new commits.

Between Runs

1. Current run completes all tasks.
2. Run validate-exit.sh — all checks must pass.
3. User reviews exit gate output.
4. Next run’s entry criteria are checked.
5. Next run is launched.

PR and Deployment Gates

The following actions require explicit user authorization:

• Pushing branches to remote
• Creating pull requests
• Deploying to dev environment (shared resource)
• Running helmInstallToLocal for local K8s deployment (Run 4 entry)

Agents must stop and request user authorization before any of these actions.

CHANGELOG Convention

Each run that modifies operations appends to CHANGELOG.md using the format:

## [X.Y.Z-jmpicnic-MMDD]

Where MMDD is the current date. This pre-release version format enables PR deployment to dev before merge.

Recovery Procedures

Run N fails mid-execution

1. Check which tasks completed (review git log and task status).
2. Fix the failing task.
3. Re-run validate-exit.sh to confirm recovery.
4. Continue to next run.

Run N exit gate fails

1. Read the specific check that failed.
2. Diagnose: build failure → fix code; test failure → fix test or code; clean worktree → commit changes.
3. Re-run validate-exit.sh.

Run N+1 entry criteria fail

1. The entry criteria reference Run N’s exit gate — if Run N passed, Run N+1 should too.
2. If the worktree state has changed (e.g., manual edits between runs), re-run the previous exit gate to confirm.

Launch Commands

Run	Command
1	/launch-team run-1-bug-fixes/project-plan.md
2	/launch-team run-2-multi-template/project-plan.md
3	/launch-team run-3-diagnostics/project-plan.md
4	/launch-team run-4-api-tests/project-plan.md
5	/launch-team run-5-api-proxy/project-plan.md

All project plan paths are relative to: /Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/documentation/src/content/docs/roadmap/in-progress/multi-pdf-print-and-bugs/

Post-Project Cleanup

After all runs complete, PRs are merged, and the project is verified:

1. Move project docs from roadmap/in-progress/ to roadmap/completed/
2. Remove worktrees:

   for repo in operations arda-frontend-app documentation api-test api-proxy; do
     git -C /Users/jmp/code/arda/$repo worktree remove \
       /Users/jmp/code/arda/projects/multi-pdf-print-and-bugs-worktrees/$repo
   done

3. Delete local branches (after PR merge):

   for repo in operations arda-frontend-app documentation api-test api-proxy; do
     git -C /Users/jmp/code/arda/$repo branch -d jmpicnic/multi-pdf-print-and-bugs
   done

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved