CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo actually is

A read-only documentation / portability bundle of the Med Tracker agent stack, cloned from arxiv-mcp-server-fe977e538dc24bb2da937c6c9e48febb54083226/ on 2026-05-03 AEDT. Not a runnable application and not a git repo (no .git, no remote, no package.json). Almost everything here is .md plus a few YAML eval tasks.

Two legitimate ways to use it:

1. Drop-into-another-project — copy agents/ → <target>/.claude/agents/, marketing-data/ → <target>/.claude/marketing/, optionally source-files/sync-skills.py → ~/.claude/hooks/. Skills under skills/ are reference copies, not executable — the agents call them by name and the actual implementations must be installed via the marketplace on the target machine.
2. Audit / read — every named skill, plugin agent, and command that the PM / Marketing / QA agents reference is bundled here as a single file so you can read what each does without spelunking through ~/.claude/plugins/cache/....

If a request implies "build", "test", "run", "deploy", "commit", or "PR" against this repo, stop and confirm — those verbs don't apply here. The exception is browser-operator evals (see below).

Layout (only the bits that matter)

Path	Role
agents/	The 4 first-class agents: project-manager.md, marketing-specialist.md, i18n-validator.md, browser-operator.md. README/MANIFEST say 3 — browser-operator.md was added after the initial clone.
agents-extra-omc/	8 oh-my-claudecode core agents the PM/Marketing agents may delegate to (architect, executor, planner, verifier, …).
agents-extra-3d/	6 core-3d-animation plugin agents — referenced for landing-page motion work only.
agents-extra-ideation/	8 auto-claude-ideation-suite subagents (competitor-analysis, roadmap-discovery, …).
commands-extra/	8 visual-explainer slash commands.
skills/plugin/	Marketplace-installed skills — naming <namespace>__<name>.SKILL.md (double underscore, e.g. superpowers__brainstorming.SKILL.md).
skills/project-local/	6 Med-Tracker-specific skills (api-endpoint, e2e-triage, i18n-check, i18n-sync, new-page, tdd-cycle) — only meaningful inside the Med Tracker frontend repo.
skills/user/	~108 personal/global skills mirrored from ~/.claude/skills/user/.
skills/use-browser-operator/SKILL.md	The prompt-template skill that parent Claude invokes before spawning browser-operator.
marketing-data/	19-folder empty skeleton matching marketing-specialist.md §1 read/write surface. See marketing-data/README.md for the full layout + naming convention.
MANIFEST.json	Machine-readable inventory: skills_resolved (180), truly_missing (13), false_positive_terms (13). Read this first before claiming a skill is missing — it may just be in the false-positive list.
eval-tasks/*.yaml	The only executable artefacts in the repo: 3 agent-eval tasks (login-flow, form-submit, data-extract) for browser-operator.

Working rules

Browser automation (the one runnable workflow)

For ANY browser-UI task (clicking, form fill, login, data extraction):

1. Invoke /use-browser-operator skill to compose the structured prompt (GOAL / URL / AUTH / SUCCESS / RETURN / CONSTRAINTS).
2. Spawn Agent(subagent_type="browser-operator").

Do not use browser-operator for API calls or raw HTML fetching — only real UI interaction. For raw HTML use WebFetch; for APIs use Bash + curl.

Auth pattern: write Next-Auth / authjs cookies to /Users/d/Developer/agent/.auth/user.json (this dir does not yet exist — create on first use), then reference it as AUTH: /Users/d/Developer/agent/.auth/user.json in the task YAML.

Running the browser-operator evals

# Edit URL/AUTH in eval-tasks/*.yaml first
agent-eval run \
  --tasks eval-tasks/login-flow.yaml \
  --agents claude-code \
  --runs 3 \
  --output eval-report.json
agent-eval report --input eval-report.json

Tools are pre-installed: agent-browser at ~/.nvm/versions/node/v22.21.0/bin/agent-browser, agent-eval at ~/.local/bin/agent-eval (uv tool). Do NOT npm install or uv tool install — already done.

Agent inventory & interaction map

Four first-class agents live in agents/. Their roles, callers, and contracts:

Agent	Role	Called by	Contract
project-manager	Orchestrator — decides what & when (sprint plan, task triage, RICE-AU prioritisation, AU compliance gating). Does NOT produce ship-able artefacts itself.	User directly	Inline spawn
marketing-specialist	Marketing executor — decides how and produces ship-able copy / image specs / SEO maps / newsletters / ad creative. AHPRA + Privacy Act + Spam Act baked in.	User directly OR project-manager	MarketingTaskHandoff JSON in marketing-specialist.md §8A
i18n-validator	7-locale key consistency check after any i18n string edit.	Dev (post-write hook)	Inline spawn
browser-operator	Real-browser UI automation (agent-browser CLI → Playwright MCP → claude-in-chrome fallback). NOT for API/HTML fetching.	Any parent that needs UI interaction	6-field prompt template from /use-browser-operator skill (GOAL/URL/AUTH/SUCCESS/RETURN/CONSTRAINTS); returns RESULT: block

Closed feedback loop inside this repo: PM ↔ marketing-specialist (two-party).

1. PM decides handoff vs inline (project-manager.md §B.5): if output is for external publication, always handoff. Otherwise PM handles inline.
2. Handoff: PM writes .claude/marketing/handoffs/<task_id>.json matching MarketingTaskHandoff schema (task_id, source, created_at_aedt, target, acceptance_criteria[], …) then spawns marketing-specialist.
3. Completion: marketing-specialist writes <task_id>-completion.json with status ∈ {completed, needs_review, blocked}, deliverable_paths[], compliance_check_results[], time_spent_hours, follow_up_recommendations[].
4. PM reads completion, verifies status == "completed" AND every compliance_check_results is PASS, then closes the sprint task.
5. Handoff/completion files are append-only audit trail — never delete or rename.

qa-agent is NOT in this repo. It exists in the user's global ~/.claude/agents/qa-agent.md (mirrored across ~/.codex/ and ~/.agents/). If the target machine has it installed, the loop extends to PM ↔ marketing-specialist ↔ qa-agent with .claude/marketing/qa-reviews/<task_id>-verdict.json (verdict ∈ approve | revise | block). On a fresh deploy without qa-agent, the two-party loop above still works.

Delegation to second-tier reference agents (agents-extra-omc/, agents-extra-ideation/, agents-extra-3d/): both PM and marketing-specialist reference these by name (e.g. PM → executor for code work, marketing → competitor-analysis for research, marketing → react-three-fiber-architect for landing-page motion). These are reference copies in this repo — actual spawn requires the corresponding marketplace plugin installed on the target machine. Default skill chains (project-manager.md §14):

Workflow	Chain
New feature from idea	brainstorming → product-lens → writing-plans → executing-plans (Dev) → code-review → accessibility → i18n-validator → browser-qa
New marketing post	brand-voice → article-writing OR content-engine → crosspost → §9 compliance gate
Pre-release	code-review → security-review → accessibility → browser-qa → click-path-audit → §9 compliance gate

Editing agents

• The 4 main agents in agents/ are canonical drafts — they get auto-mirrored to ~/.claude/agents/, ~/.codex/agents/, ~/.agents/agents/ via ~/.claude/hooks/sync-skills.py when edited inside Claude Code. Edits made by Codex or other harnesses do NOT auto-mirror — fix drift manually.
• project-manager.md and marketing-specialist.md carry AU/Melbourne Med-Tracker-specific clauses: AHPRA s.133 advertising guidelines, Privacy Act 1988 + APP 1–13, Spam Act 2003, TGA SaMD Class I, AUD pricing, AEST/AEDT defaults. Reuse for non-Med-Tracker projects requires a fork-and-search-replace of those clauses, not in-place edit.

Skill resolution / "missing" diagnostics

Before reporting a skill as missing or broken:

1. Check MANIFEST.json false_positive_terms — terms like query, timeline, references, impact, i18n-validator, marketing-specialist, project-manager are filename/data slugs, not real skills.
2. Check MANIFEST.json truly_missing — these 13 are known unresolved (mostly because they were renamed / merged in upstream plugins after the clone).
3. Skills under skills/plugin/ use double-underscore namespace separators (<namespace>__<name>.SKILL.md), not colons or slashes. oh-my-claudecode:planner becomes oh-my-claudecode__planner.SKILL.md if it existed (currently in truly_missing).

Marketing data folder

The 19-folder skeleton under marketing-data/ is empty by design — a shape contract for the read/write surface declared in marketing-specialist.md §1. Naming convention is YYYY-MM-DD-<slug>.ext (AEDT date of creation, not publish). Decision logs (marketing-data/decisions/) are append-only — never rename or delete entries; they are the permanent audit trail.

Anti-patterns specific to this repo

• Don't run npm test / pytest / cargo build — there is nothing to build. The only executable workflow is agent-eval.
• Don't git commit — not a git repo. To version, copy into a git-managed parent.
• Don't edit skills/plugin/*.SKILL.md expecting behaviour change — those are reference copies; real definitions live in marketplace plugin caches.
• Don't trust the README's "3 agents" count — it is 4 (browser-operator added later); MANIFEST.json is also slightly stale on this.
• Don't fork PM/Marketing agents in-place to strip AU clauses — copy them out first; the originals are intentionally AU-laden.