Choreography: Arda API Proxy

Execution Sequence

Order	Run	Directory	Trigger	Description
1	Run 1: Foundation	run-1-foundation/	Manual	Repo scaffolding, shared infra, TenantProxy reference, CI/CD, spec path corrections
2	Run 2: Proxies and Publish	run-2-proxies-and-publish/	After Run 1 exit gate passes	Remaining 7 proxies + types + tests, barrel exports, README, CHANGELOG

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
Package toolchain (package.json, tsconfig, eslint, vitest, prettier)	Run 1	Run 2	api-proxy/ root	JSON/JS/TS
Shared utilities (HttpClient, types, errors)	Run 1	Run 2 (all proxies)	api-proxy/src/shared/	TypeScript
TenantProxy + types (reference pattern)	Run 1	Run 2 (template for remaining proxies)	api-proxy/src/system/tenant.*	TypeScript
Tenant test (test pattern)	Run 1	Run 2 (template for remaining tests)	api-proxy/tests/system/tenant.test.ts	TypeScript
CI/CD workflows	Run 1	PR review after Run 2	api-proxy/.github/workflows/	YAML
Corrected specification	Run 1 (task 1.1)	Run 2 (path reference)	documentation/.../specification.md	Markdown
Complete package	Run 2	PR → merge → publish	api-proxy/	TypeScript/npm

Hand-Off Protocol

All hand-offs are filesystem-only — no in-memory state is shared between runs. Each run reads its inputs from files produced by prior runs and writes its outputs to files for subsequent runs.

Between Run 1 and Run 2

1. Run 1 completes and run-1-foundation/validate-exit.sh passes all 10 checks.
2. The user verifies the exit gate output and reviews the foundation code.
3. Run 2’s entry criteria are checked (which reference Run 1’s output files: shared utilities, TenantProxy, CI workflows).
4. Run 2 is launched in the same worktree, same branch — it picks up where Run 1 left off.

After Run 2

1. Run 2 completes and run-2-proxies-and-publish/validate-exit.sh passes all 13 checks.
2. The user reviews the complete package.
3. Push the branch and create a PR against main for api-proxy.
4. After CI passes and PR is approved, merge to main.
5. The publish.yml workflow publishes @arda-cards/api-proxy@0.1.0 to GitHub Packages.
6. Commit and push documentation changes from the documentation worktree; create PR.

Recovery Procedures

Run 1 fails mid-execution

1. Check which tasks completed by reviewing git log and file state.
2. Fix the failing task (most likely: npm install issues, TypeScript compilation errors, or test failures).
3. Re-run the remaining tasks from the point of failure.
4. Re-run validate-exit.sh to confirm all criteria pass.

Run 1 exit gate fails

1. Read the validate-exit.sh output to identify which criteria failed.
2. Common failures:
   • Coverage below 80%: Add more test cases to tests/shared/http-client.test.ts or tests/system/tenant.test.ts.
   • Lint/format failures: Run npm run format and npm run lint -- --fix.
   • Uncommitted changes: Stage and commit remaining files.
3. Re-run validate-exit.sh after fixes.

Run 2 fails mid-execution

1. The repetitive proxy pattern means failures are usually isolated to a single proxy.
2. Check which proxy failed by reviewing the error output.
3. Compare the failing proxy against the TenantProxy reference to identify deviations.
4. Fix and re-run tests for that specific proxy: npx vitest run tests/{domain}/{proxy}.test.ts.
5. Continue with remaining tasks.

Run 2 exit gate fails

1. Most likely causes: missing files, coverage regression, or import resolution failures.
2. Check the specific failing criterion and address it.
3. Re-run the full verification: npm run format:check && npm run typecheck && npm run lint && npm run test:coverage && npm run build.

Worktree Strategy

Single directory — no worktrees needed within the api-proxy repository. Both runs operate on the same worktree:

• Worktree: /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy
• Branch: jmpicnic/initial-implementation

The documentation worktree is separate:

• Worktree: /Users/jmp/code/arda/projects/api-proxy-worktrees/documentation
• Branch: jmpicnic/initial-implementation

Launch Commands

Run	Command
1	Single-agent launch against run-1-foundation/project-plan.md
2	Single-agent launch against run-2-proxies-and-publish/project-plan.md