Run 7: Release — Project Plan

Author: Technical Writer / Team Lead Date: 2026-04-07 Status: Planning Phase: 3.7 — Release Branch: jmpicnic/image-upload-frontend

Summary

Final release activities for the image-upload-frontend project: produce project closing documents, update CHANGELOGs, create PRs for arda-frontend-app and documentation, follow merge ordering, move project docs to completed/, and present worktree cleanup commands for user-initiated execution. The api-proxy and ux-prototype PRs are already merged from Runs 1 and 4.

Entry Criteria

Criterion	Verification
All Runs 1-6 complete and reviewed and approved	Run plan completion records present; all review gates passed
Run 1 PR merged: `api-proxy`	GitHub: PR to `api-proxy` merged
Run 4 PR merged: `ux-prototype`	GitHub: PR to `ux-prototype` merged
Run 6 exit gate passed: SPA integration reviewed and approved	`npm run lint && npx tsc --noEmit && npx jest --no-coverage --watchAll=false --forceExit && npm run build` passes in `arda-frontend-app` worktree
`arda-frontend-app` branch has no uncommitted changes	`git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/arda-frontend-app status` — clean
`documentation` branch has no uncommitted changes	`git -C /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation status` — clean

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
T-1	Project closing documents (`byproducts/`)	front-end-engineer	Entry criteria	Pending	Six files created under `3-frontend-implementation/byproducts/` in documentation worktree: `changelog.md` (consolidated commit log by phase), `learnings.md` (TanStack patterns, FD-01 practical experience, `useDraft<T>` usage, BFF route structure, deviations), `suggestions.md` (future improvements), `alternatives.md` (design alternatives considered during implementation), `skipped.md` (deferred items with rationale and ticket refs), `specification-post.md` (deviations from specification: what was specified vs implemented vs why)
T-2	`arda-frontend-app` CHANGELOG update	front-end-engineer	T-1	Pending	CHANGELOG.md Added section includes: `@tanstack/react-query` integration, `@aws-sdk/client-secrets-manager`, BFF routes (`/api/image-upload`, `/api/storage/check-url`, `/api/storage/fetch-url`, `/api/storage/cdn-cookies`), CDN cookie lifecycle manager, TanStack hooks (`useImageUpload`, `useCheckReachability`, `useFetchExternalImage`, `useCdnCookies`), image components wired in grid and forms, `ITEM_IMAGE_CONFIG`, `src/server/` and `src/api/` directory structure (FD-02), `src/server/lib/aws-naming.ts`, `src/server/lib/secrets.ts`, `useImageWithCdnRecovery`, `NEXT_PUBLIC_INFRASTRUCTURE`, `NEXT_PUBLIC_PARTITION`, `NEXT_PUBLIC_CDN_COOKIE_TTL_MS`; Changed section includes: item grid image column, `ItemFormPanel` image field
T-3	`arda-frontend-app` PR	front-end-engineer	T-2	Pending	PR created from `jmpicnic/image-upload-frontend` to `dev`; includes attribution block; description summarizes all phases; `/pr-steward <pr-url>` run and CI checks monitored; reviewer comments resolved; PR merged
T-4	`documentation` CHANGELOG update	front-end-engineer	T-1	Pending	CHANGELOG.md Added section includes: frontend implementation planning documents (goal, analysis, requirements, verification, 7 phase specifications), architectural exploration documents (TanStack adoption, component binding, lifecycle framework, code organization, architectural review), edit lifecycle architecture documentation, project byproducts
T-5	`documentation` PR	front-end-engineer	T-4	Pending	`make pr-checks` passes before pushing; PR created from `jmpicnic/image-upload-frontend` to `main`; attribution block included; `/pr-steward <pr-url>` run; CI checks pass; reviewer comments resolved; PR merged
T-6	Move project docs to `completed/`	front-end-engineer	T-5	Pending	Directory `roadmap/completed/item-image-upload/3-frontend-implementation/` moved to `roadmap/completed/item-image-upload/3-frontend-implementation/`; committed and pushed as follow-up to documentation PR
T-7	Merge ordering	front-end-engineer	T-3, T-5	Pending	`documentation` PR merged first; `arda-frontend-app` PR merged after documentation; merge order recorded
T-8	Worktree cleanup commands (user-initiated — do NOT execute automatically)	front-end-engineer	T-7	Pending	Cleanup commands presented to user; commands not executed until user explicitly confirms

Merge Ordering

Per release-lifecycle skill conventions for multi-repository projects:

documentation PR — merge first (no code dependencies)
arda-frontend-app PR — merge after documentation

The api-proxy and ux-prototype PRs were already merged in Runs 1 and 4.

Worktree Cleanup Commands

Present these commands to the user and wait for explicit confirmation before running. Do not execute automatically.

# Remove worktrees
git -C /Users/jmp/code/arda/api-proxy worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/api-proxy
git -C /Users/jmp/code/arda/ux-prototype worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/ux-prototype
git -C /Users/jmp/code/arda/arda-frontend-app worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/arda-frontend-app
git -C /Users/jmp/code/arda/documentation worktree remove \
  /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation

# Remove worktree parent directory
rmdir /Users/jmp/code/arda/projects/image-upload-frontend-worktrees

# Clean up local branches
git -C /Users/jmp/code/arda/api-proxy branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/ux-prototype branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/arda-frontend-app branch -d jmpicnic/image-upload-frontend
git -C /Users/jmp/code/arda/documentation branch -d jmpicnic/image-upload-frontend

Exit Criteria

Criterion	Verification
All project byproducts produced (6 files)	`ls /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation/src/content/docs/roadmap/completed/item-image-upload/3-frontend-implementation/byproducts/`
`arda-frontend-app` CHANGELOG updated	CHANGELOG.md includes all Added and Changed entries from T-2
`arda-frontend-app` PR created, reviewed, and merged	GitHub: PR merged to `dev`
`documentation` CHANGELOG updated	CHANGELOG.md includes all Added entries from T-4
`documentation` PR created, reviewed, and merged	GitHub: PR merged to `main`
Merge ordering followed (documentation first, then arda-frontend-app)	GitHub merge timestamps confirm order
Project documentation moved to `completed/`	`ls documentation/src/content/docs/roadmap/completed/item-image-upload/3-frontend-implementation/`
Worktree cleanup commands presented to user (not executed automatically)	Commands displayed in run output

Handoff

This is the terminal run. There is no consumer of this run’s output other than the merged production code and the completed project documentation.

Artifacts Consumed

Artifact	Source	Produced By
All `arda-frontend-app` commits (BFF routes + SPA integration)	`arda-frontend-app` worktree	Runs 5, 6
All `documentation` commits (specifications, explorations, byproducts)	`documentation` worktree	Runs 1-6
`api-proxy` PR already merged	GitHub	Run 1
`ux-prototype` PR already merged	GitHub	Run 4

Artifacts Produced

Artifact	Location
`arda-frontend-app` PR merged to `dev`	GitHub
`documentation` PR merged to `main`	GitHub
Project byproducts (6 files)	`documentation/roadmap/completed/item-image-upload/3-frontend-implementation/byproducts/`
Project docs in `completed/` status	`documentation/roadmap/completed/item-image-upload/3-frontend-implementation/`

Agent Prompt Template

Use the following prompt to spawn the front-end-engineer agent for this run. Paste the full text as the Task tool input.

You are a front-end-engineer executing the release run for the
image-upload-frontend project.

**arda-frontend-app worktree**: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/arda-frontend-app
**documentation worktree**: /Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation
**Branch**: jmpicnic/image-upload-frontend

Load the following skills before starting:
- release-lifecycle
- path-conventions
- document-writing

Read the specification before beginning:
/Users/jmp/code/arda/projects/image-upload-frontend-worktrees/documentation/src/content/docs/roadmap/completed/item-image-upload/3-frontend-implementation/37-release/specification.md

Your task is to execute Run 7 of the image-upload-frontend project (Phase 3.7 —
Release). Complete the following tasks in order:

T-1: Produce project byproducts in the documentation worktree under
     3-frontend-implementation/byproducts/:
     - changelog.md: consolidated commit log across all repos, organized by phase
     - learnings.md: key insights (TanStack Query patterns, FD-01 practical
       experience, useDraft<T> usage, BFF route structure, deviations)
     - suggestions.md: improvement recommendations for future projects
     - alternatives.md: design alternatives considered during implementation
     - skipped.md: deferred items with rationale and ticket references
     - specification-post.md: post-implementation spec (deviations: what was
       specified vs implemented vs why)

T-2: Update CHANGELOG.md in the arda-frontend-app worktree. See specification
     §T-2 for the full list of Added and Changed entries.

T-3: Create a PR from jmpicnic/image-upload-frontend to dev in arda-frontend-app.
     Include attribution block in the PR description. Run /pr-steward <pr-url>
     to monitor CI and resolve reviewer comments. Wait for approval before
     merging.

T-4: Update CHANGELOG.md in the documentation worktree. See specification §T-4
     for the full list of Added entries.

T-5: Run `make pr-checks` in the documentation worktree. Create a PR from
     jmpicnic/image-upload-frontend to main. Include attribution block. Run
     /pr-steward <pr-url>. Wait for approval before merging.

T-6: After all PRs are merged, move the project documentation:
     From: roadmap/completed/item-image-upload/3-frontend-implementation/
     To:   roadmap/completed/item-image-upload/3-frontend-implementation/
     Commit and push.

T-7: MERGE ORDERING — documentation PR first, then arda-frontend-app PR.
     Record merge order and timestamps.

T-8: STOP. Present the worktree cleanup commands to the user (from the
     specification §T-8). Do NOT execute them. Wait for explicit user
     confirmation before running any cleanup commands.

All tool calls must use absolute paths. Never use `cd` — use absolute paths
or `git -C <path>` for git commands.

Report completion with: (a) both PR URLs and their merge status, (b) a list of
all 6 byproduct files created, (c) confirmation that project docs were moved to
completed/, and (d) the worktree cleanup commands ready for user review.