Run 1: hypothesis-mcp Extension

Overview

Extend the hypothesis-mcp server to support target with CssSelector in createAnnotation, enabling W3C Web Annotation-compliant DOM-element annotations.

Repository & Branch Setup

• Repository: /hypothesis-mcp
• Base branch: main (ensure up-to-date with origin/main)
• Working branch: jmpicnic/integrate-agentation-hypothesis
• Worktree: Not needed (single agent, single repo)

Entry Criteria

#	Criterion	Verification Command	Expected Output
1	hypothesis-mcp main is up-to-date with origin	git -C /Users/jmp/code/arda/hypothesis-mcp fetch origin && git -C /Users/jmp/code/arda/hypothesis-mcp diff main origin/main --stat	No output (no diff)
2	All existing tests pass	cd /Users/jmp/code/arda/hypothesis-mcp && npm test	All tests pass
3	Working branch does not already exist	git -C /Users/jmp/code/arda/hypothesis-mcp branch --list jmpicnic/integrate-agentation-hypothesis	Empty output

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
1.1	Update main from origin and create working branch	back-end	—	Pending	Branch exists, based on latest main
1.2	Extend RawSelector in types.ts with value?: string field	back-end	1.1	Pending	value field available for CssSelector
1.3	Add optional target parameter to createAnnotation in client.ts	back-end	1.2	Pending	When target is provided, it is included in POST body; when absent, existing behavior preserved
1.4	Add unit tests for target/CssSelector in client.test.ts	back-end	1.3	Pending	Tests cover: target with CssSelector, target with TextQuoteSelector, target omitted (backward compat)
1.5	Update CHANGELOG.md with new version entry	back-end	1.4	Pending	v1.3.0 entry documenting target parameter support
1.6	Run all checks, commit, push, create PR	back-end	1.5	Pending	npm test passes, npx tsc --noEmit passes, PR created targeting main
1.7	Monitor PR (10-minute wait), handle check failures and reviewer comments	back-end	1.6	Pending	PR checks green; reviewer comments addressed per user guidance

Internal Dependency Graph

All tasks are sequential (1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6 → 1.7). No parallelization within this run.

Exit Criteria

#	Criterion	Verification Command	Expected Output
1	All tests pass	cd /Users/jmp/code/arda/hypothesis-mcp && npm test	All tests pass
2	TypeScript compiles	cd /Users/jmp/code/arda/hypothesis-mcp && npx tsc --noEmit	No errors
3	PR created and checks passing	gh pr list -R Arda-cards/hypothesis-mcp --head jmpicnic/integrate-agentation-hypothesis --json state,statusCheckRollup	PR exists, checks passing
4	CHANGELOG updated	grep -c 'v1.3.0|1.3.0' /Users/jmp/code/arda/hypothesis-mcp/CHANGELOG.md	At least 1 match

Agent Prompt Templates

Back-End Engineer — be-hypothesis-mcp

You are working in /Users/jmp/code/arda/hypothesis-mcp.

Goal: Extend the createAnnotation function to support an optional target parameter with W3C Web Annotation selectors (CssSelector, TextQuoteSelector).

Base branch: main (pull latest from origin first). Working branch: jmpicnic/integrate-agentation-hypothesis

Tasks: See Run 1 task list in the project plan.

Specification: Read /documentation/src/content/docs/roadmap/completed/integrate-agentation-hypothesis/specification.md, Component 6.

PR workflow: After pushing, create a PR. Wait 10 minutes, then check for:

• Check failures: fix them.
• Reviewer comments: Present the user with a numbered table summarizing each comment and your recommendation. Fix comments the user approves, then reply to all and resolve threads.

CHANGELOG: Update with a v1.3.0 entry before committing.

Handoff

Artifacts Consumed (from previous runs)

None — this is the first run.

Artifacts Produced (for subsequent runs)

Artifact	Consumer Run	Path
Extended createAnnotation API contract	Run 2 (ux-prototype bridge)	/hypothesis-mcp/src/client.ts
Merged PR on main	Run 2 (optional — bridge works without it)	Arda-cards/hypothesis-mcp repo