--- ## How to read this document - **Dependencies** list task IDs that must be complete before this task starts - **Parallel group** identifies tasks that can run simultaneously within a phase - **Target** identifies which repo and branch the work goes into - Tasks are numbered `P{phase}-{sequence}` (e.g., P0-3) - Acceptance criteria are binary — pass or fail, no judgment calls --- ## Phase 0: Proof of Concept **Goal:** Validate the two core technical risks: git on EFS via Lambda, and MCP OAuth via WorkOS. **Two independent tracks** that can run with separate managers: - Track A: EFS + Lambda (P0-1 → P0-5) - Track B: WorkOS + MCP auth (P0-6 → P0-8) ### P0-1: Pulumi Scaffold **Parallel group:** Track A start **Dependencies:** None **Target:** `wikibot-io` repo, `feat/P0-1-pulumi-scaffold` **Description:** Create the Pulumi project with foundational AWS infrastructure: VPC with 1 public and 1 private subnet (single AZ for dev), security groups, route tables, and gateway endpoints for DynamoDB and S3. **Deliverables:** - `infra/__main__.py` with top-level composition - `infra/components/vpc.py` — VPC, subnets, security groups, route tables, gateway endpoints - Unit tests verifying resource creation and security group rules - `pulumi up` succeeds against the dev stack **Acceptance criteria:** - [ ] VPC created with correct CIDR, 1 public + 1 private subnet - [ ] Gateway endpoints for DynamoDB and S3 attached to private subnet route table - [ ] Security group allows Lambda → EFS (NFS port 2049) and Lambda → internet (egress) - [ ] All resources tagged with `project: wikibot-io`, `environment: dev` - [ ] Unit tests pass with `pulumi.runtime.set_mocks()` - [ ] `pulumi up` succeeds --- ### P0-2: EFS + Lambda Basic **Parallel group:** Track A **Dependencies:** P0-1 **Target:** `wikibot-io` repo, `feat/P0-2-efs-lambda` **Description:** Add EFS filesystem with mount target in the private subnet. Create a Lambda function (Python 3.12, VPC-attached) that mounts EFS and performs basic file read/write. This validates the core infrastructure pattern. **Deliverables:** - `infra/components/efs.py` — EFS filesystem, mount target, access point - `infra/components/lambda_functions.py` — Lambda function with VPC config and EFS mount - `app/poc/efs_test.py` — Lambda handler that writes a file, reads it back, returns timing - IAM role with EFS and VPC permissions - Integration test that invokes the Lambda and verifies file persistence **Acceptance criteria:** - [ ] Lambda can write a file to EFS at `/mnt/efs/test.txt` - [ ] Lambda can read the file back and content matches - [ ] File persists across Lambda invocations (cold and warm) - [ ] Integration test passes - [ ] Lambda execution time logged --- ### P0-3: Git on EFS **Parallel group:** Track A **Dependencies:** P0-2 **Target:** `wikibot-io` repo, `feat/P0-3-git-efs` **Description:** Lambda function that initializes a bare git repo on EFS, commits a markdown file, reads it back, and lists commits. Validates that git operations work correctly on NFS-mounted storage. Investigate git library choice: gitpython (shells out to `git` binary — verify availability in Lambda runtime) vs. dulwich (pure Python, no binary dependency). If `git` is not available in the Lambda runtime, use dulwich. Document the decision. **Deliverables:** - `app/poc/git_test.py` — Lambda handler: init bare repo, commit file, read file, list history - Decision documented: gitpython vs. dulwich, with rationale - Integration test that exercises the full git lifecycle **Acceptance criteria:** - [ ] Bare git repo created on EFS at a specified path - [ ] Markdown file committed with author, message, and timestamp - [ ] File content readable from the repo - [ ] Commit history retrievable - [ ] Repo persists across Lambda invocations - [ ] Concurrent read test: 3 simultaneous Lambda invocations reading the same repo - [ ] Git library decision documented with rationale --- ### P0-4: X-Ray Tracing **Parallel group:** Track A (can run parallel with P0-3) **Dependencies:** P0-2 **Target:** `wikibot-io` repo, `feat/P0-4-xray` **Description:** Enable AWS X-Ray tracing on Lambda and API Gateway. Add custom subsegments for git operations (init, commit, read) so that Phase 0 benchmarks can break down latency by operation. **Deliverables:** - X-Ray tracing enabled on Lambda function(s) via Pulumi - Custom subsegment instrumentation in git test Lambda - API Gateway stage with X-Ray enabled (if API Gateway exists at this point; otherwise, just Lambda tracing) **Acceptance criteria:** - [ ] X-Ray traces visible in AWS console after Lambda invocation - [ ] Custom subsegments for git operations appear in trace timeline - [ ] Cold start vs. warm start distinguishable in traces --- ### P0-5: Performance Benchmarks **Parallel group:** Track A (final) **Dependencies:** P0-3, P0-4 **Target:** `wikibot-io` repo, `feat/P0-5-benchmarks` **Description:** Benchmark script that invokes the git Lambda repeatedly and collects timing data. Measures cold start latency, warm read latency, warm write latency, and concurrent access behavior. Results compared against Phase 0 exit criteria. **Deliverables:** - `scripts/benchmark_efs.py` — invokes Lambda N times, collects X-Ray data or Lambda response times - Results written to `Dev/Phase 0 — EFS Benchmarks` wiki note - Concurrent write test: 5 simultaneous Lambda invocations writing to the same repo **Acceptance criteria:** - [ ] Warm page read < 500ms (measured over 20+ invocations) - [ ] Warm page write < 1s (measured over 20+ invocations) - [ ] Cold start < 5s total (measured over 5+ cold starts) - [ ] Concurrent reads succeed without errors - [ ] Concurrent writes succeed (git locking handles serialization) - [ ] Results written to Dev/Phase 0 Summary per Agent Conventions documentation loop --- ### P0-6: WorkOS AuthKit Setup **Parallel group:** Track B start (independent of Track A) **Dependencies:** None **Target:** `wikibot-io` repo, `feat/P0-6-workos-setup` **Description:** Set up WorkOS AuthKit with Google OAuth provider. Configure the WorkOS dashboard, obtain API keys, and write a minimal test that authenticates a user and retrieves their profile including raw OAuth provider `sub` claim. **Deliverables:** - WorkOS AuthKit configuration (documented, not in code — dashboard setup) - `app/poc/workos_test.py` — script that initiates OAuth flow and prints user profile - WorkOS API key stored in Pulumi config (`pulumi config set --secret workos_api_key`) - Documentation of provider sub retrieval (especially Apple, if testable) **Acceptance criteria:** - [ ] Google OAuth login flow completes successfully - [ ] User profile retrieved with email, name, and raw Google `sub` claim - [ ] API key securely stored in Pulumi config - [ ] Apple provider sub retrieval status documented (verified or flagged as unavailable) --- ### P0-7: FastMCP + WorkOS on Lambda **Parallel group:** Track B **Dependencies:** P0-2, P0-6 **Target:** `wikibot-io` repo, `feat/P0-7-mcp-workos-lambda` **Description:** Deploy a minimal FastMCP server on Lambda with WorkOS OAuth 2.1 authentication. The MCP server exposes a single test tool (e.g., `echo`) that returns its input. Uses Streamable HTTP transport (not SSE). Validates that the FastMCP + WorkOS integration works on Lambda behind API Gateway. Reference the existing `otterwiki-mcp` auth implementation for patterns (MultiAuth, InMemoryOAuthProvider, StaticTokenVerifier). **Deliverables:** - `app/poc/mcp_server.py` — minimal FastMCP server with WorkOS auth and one test tool - Mangum adapter wrapping the MCP server for Lambda - API Gateway route for MCP endpoint - Unit tests for auth setup (mock WorkOS) - Integration test that calls the echo tool with a valid token **Acceptance criteria:** - [ ] MCP server deploys to Lambda successfully - [ ] API Gateway routes to MCP endpoint - [ ] OAuth 2.1 flow completes (WorkOS issues token, MCP server validates) - [ ] Test tool callable with valid auth token - [ ] Invalid/missing tokens rejected - [ ] Bearer token auth works alongside OAuth (if MCP_AUTH_TOKEN configured) --- ### P0-8: Claude.ai MCP End-to-End **Parallel group:** Track B (final) **Dependencies:** P0-7 **Target:** Manual testing (no code deliverable) **Description:** Connect Claude.ai to the MCP endpoint deployed in P0-7. Verify that Claude.ai can authenticate via WorkOS OAuth and call the test tool. This is a manual test performed by the human or the manager. **Acceptance criteria:** - [ ] Claude.ai MCP connection configured with the endpoint URL - [ ] OAuth flow completes in Claude.ai - [ ] Claude.ai can call the echo tool and receive a response - [ ] Results written to Dev/Phase 0 Summary per Agent Conventions documentation loop --- ### P0-9: Billing Alarm **Parallel group:** Can run anytime after P0-1 **Dependencies:** P0-1 **Target:** `wikibot-io` repo, `feat/P0-9-billing-alarm` **Description:** Set up AWS Budgets billing alarm with a $50/month threshold. Email notification to the project owner. **Deliverables:** - Pulumi resource for AWS Budget with email alert - Alert threshold: $50/month **Acceptance criteria:** - [ ] Budget alarm created - [ ] Email notification configured - [ ] `pulumi up` succeeds