Run 1: Foundation — Shared Infrastructure, Tenant Reference, CI/CD

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	api-proxy worktree exists	test -d /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && echo OK	OK
2	Worktree is on correct branch	git -C /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy branch --show-current	jmpicnic/initial-implementation
3	Repository is clean	git -C /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy status --porcelain	(empty)
4	Node.js 22+ available	node --version	v22. prefix
5	Staging API reachable (for OpenAPI specs)	curl -sf -o /dev/null https://stage.alpha002.io.arda.cards/v1/tenant/docs/openApi.json && echo OK	OK

Artifact Specifications

Artifact	Path	Format	Description
Package manifest	package.json	JSON	Per specification § package.json
TypeScript config	tsconfig.json	JSON	Per specification § tsconfig.json
Vitest config	vitest.config.ts	TypeScript	Per specification § Coverage
ESLint config	eslint.config.js	JavaScript	typescript-eslint strictTypeChecked
Prettier config	.prettierrc	JSON	Matches api-mcp conventions
Git ignore	.gitignore	Text	Excludes dist/, node_modules/, coverage/
HttpClient	src/shared/http-client.ts	TypeScript	Composable HTTP client class
Common types	src/shared/types.ts	TypeScript	EntityRecord, PageResult, Query, Filter, etc.
Error handling	src/shared/errors.ts	TypeScript	ArdaApiError, parseErrorResponse
Shared barrel	src/shared/index.ts	TypeScript	Re-exports shared surface
TenantProxy	src/system/tenant.ts	TypeScript	Reference proxy implementation
Tenant types	src/system/tenant.types.ts	TypeScript	Types derived from live OpenAPI spec
System barrel	src/system/index.ts	TypeScript	Re-exports system proxies
HttpClient tests	tests/shared/http-client.test.ts	TypeScript	Mock-fetch tests for HttpClient
Tenant tests	tests/system/tenant.test.ts	TypeScript	Mock-fetch tests for TenantProxy
CI workflow	.github/workflows/ci.yml	YAML	Format, typecheck, lint, test+coverage
Publish workflow	.github/workflows/publish.yml	YAML	Build + publish to GitHub Packages

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.1	Correct specification paths to match endpoint catalog (per DQ-001)	back-end-engineer	—	Pending	Specification and requirements path tables updated; paths match endpoint catalog
1.2	Initialize repository: package.json, tsconfig.json, eslint.config.js, vitest.config.ts, .prettierrc, .gitignore	back-end-engineer	—	Pending	npm install succeeds; npm run typecheck succeeds on empty src
1.3	Implement src/shared/types.ts — extract common types from api-mcp/packages/shared/src/types.ts	back-end-engineer	1.2	Pending	All types from REQ-CORE-007 exported; npm run typecheck passes
1.4	Implement src/shared/errors.ts — ArdaApiError and parseErrorResponse	back-end-engineer	1.2	Pending	ArdaApiError class and parseErrorResponse function; REQ-CORE-004
1.5	Implement src/shared/http-client.ts — composable HttpClient with ProxyConfig	back-end-engineer	1.3, 1.4	Pending	REQ-CORE-001 through REQ-CORE-003; composition not inheritance (REQ-PROXY-002)
1.6	Create src/shared/index.ts barrel export	back-end-engineer	1.3, 1.4, 1.5	Pending	All shared types and classes re-exported
1.7	Fetch tenant OpenAPI spec from staging and derive src/system/tenant.types.ts	back-end-engineer	1.2	Pending	Types match OpenAPI spec; use Kotlin source as tiebreaker if ambiguous (DQ-004)
1.8	Implement src/system/tenant.ts — TenantProxy with standard CRUD	back-end-engineer	1.5, 1.6, 1.7	Pending	REQ-SYS-001, REQ-PROXY-001, REQ-PROXY-003; all 7 standard methods
1.9	Create src/system/index.ts barrel export	back-end-engineer	1.8	Pending	TenantProxy and tenant types re-exported
1.10	Write tests/shared/http-client.test.ts	back-end-engineer	1.5	Pending	Covers URL building, headers, time coordinates, error handling; REQ-CORE-001 through REQ-CORE-004
1.11	Write tests/system/tenant.test.ts	back-end-engineer	1.8	Pending	Covers construction, all 7 CRUD methods, time coordinates, error propagation; REQ-SYS-001
1.12	Set up CI workflows: .github/workflows/ci.yml and publish.yml	back-end-engineer	1.2	Pending	Workflow YAML matches specification § CI/CD
1.13	Verify full toolchain: npm run format:check && npm run typecheck && npm run lint && npm run test:coverage && npm run build	back-end-engineer	1.1–1.12	Pending	All commands pass; coverage meets 80% line and branch thresholds; dist/ contains compiled output

Internal Dependency Graph

1.1 (spec fix) ──────────────────────────────────────────────┐
1.2 (repo init) ─┬─ 1.3 (types) ─┬─ 1.5 (HttpClient) ─┬─ 1.8 (TenantProxy) ─ 1.9 (barrel)
                  │               │                      │
                  ├─ 1.4 (errors)─┘                      ├─ 1.10 (HttpClient tests)
                  │                                      │
                  ├─ 1.7 (tenant types) ─────────────────┘─ 1.11 (tenant tests)
                  │
                  └─ 1.12 (CI workflows)
                                                              All ──── 1.13 (verify)

Tasks 1.1 and 1.2 can start in parallel. Tasks 1.3, 1.4, 1.7, and 1.12 can start once 1.2 is done. The dependency chain then flows through 1.5 → 1.8 → tests → verify.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	npm install succeeds	cd /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && npm ci	Exit code 0
2	Format check passes	cd /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && npm run format:check	Exit code 0
3	Typecheck passes	cd /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && npm run typecheck	Exit code 0
4	Lint passes	cd /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && npm run lint	Exit code 0
5	Tests pass with coverage	cd /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && npm run test:coverage	Exit code 0; 80%+ lines and branches
6	Build succeeds	cd /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy && npm run build	Exit code 0; dist/ exists
7	Shared barrel exports correct types	node -e "import('./dist/shared/index.js')"	No errors
8	System barrel exports TenantProxy	node -e "import('./dist/system/index.js')"	No errors
9	No runtime dependencies	node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));process.exit(p.dependencies?1:0)"	Exit code 0
10	No MCP imports	grep -r '@modelcontextprotocol' src/ && echo FAIL || echo OK	OK
11	All changes committed	git -C /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy status --porcelain	(empty)
12	Specification paths corrected (per DQ-001)	Visual review of specification.md path tables	Paths match endpoint catalog

Agent Prompt Templates

Back-End Engineer — be-api-proxy-foundation

You are implementing the foundation for the @arda-cards/api-proxy TypeScript package.

Working directory: /Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy
Branch: jmpicnic/initial-implementation

## Context
- Read the project goal: /Users/jmp/code/arda/projects/api-proxy-worktrees/documentation/src/content/docs/roadmap/in-progress/api-proxy/goal.md
- Read the specification: /Users/jmp/code/arda/projects/api-proxy-worktrees/documentation/src/content/docs/roadmap/in-progress/api-proxy/specification.md
- Read the decision log: /Users/jmp/code/arda/projects/api-proxy-worktrees/documentation/src/content/docs/roadmap/in-progress/api-proxy/decision-log.md
- Reference implementation: /Users/jmp/code/arda/api-mcp/packages/shared/src/ (consultative only)
- Tenant reference: /Users/jmp/code/arda/api-mcp/packages/tenant-mcp/src/ (consultative only)

## Type Derivation (DQ-004)
Fetch OpenAPI specs from live staging server: https://stage.alpha002.io.arda.cards/v1/{module}/docs/openApi.json
Fall back to Kotlin source in operations/ or accounts-component/ for ambiguities.

## Tasks
Complete tasks 1.1 through 1.13 from this project plan in order.

## Key Constraints
- Composition over inheritance (REQ-PROXY-002)
- No runtime dependencies (REQ-CORE-005)
- No MCP imports (REQ-CORE-006)
- TypeScript strict mode with verbatimModuleSyntax (REQ-PKG-003)
- 80% line and branch coverage (REQ-PKG-005)

Handoff

Artifacts Consumed (from previous runs)

Artifact	Source	Path
Empty api-proxy repository	Initial setup	/Users/jmp/code/arda/projects/api-proxy-worktrees/api-proxy/
Project specification	Planning	documentation/.../api-proxy/specification.md
Decision log	Planning	documentation/.../api-proxy/decision-log.md
api-mcp shared source	Consultative reference	/Users/jmp/code/arda/api-mcp/packages/shared/src/

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
Initialized repo with working toolchain	Run 2	api-proxy/ (all config files)
Shared utilities (HttpClient, types, errors)	Run 2	api-proxy/src/shared/
Tenant reference proxy + types	Run 2	api-proxy/src/system/tenant.*
Test patterns	Run 2	api-proxy/tests/shared/, api-proxy/tests/system/
CI/CD workflows	Run 2	api-proxy/.github/workflows/
Corrected specification	Run 2	documentation/.../api-proxy/specification.md