seedproject-web/agents/AGENTS.md

# Agent catalog

> **GENERATED — do not edit.** Regenerate with `node agents/catalog.mjs`
> (source of truth: the `@agent-manifest` header in each script).

An **agent** = an LLM orchestrator script + its role prompt (`prompt:`) + its skills
(MCP servers, `skills:`) + its tools (`api/cli/*.php` bridges and `lib/*.mjs`, `tools:`).
To port an agent to another SeedProject clone, satisfy its manifest: copy its prompts, ensure
its tools exist, migrate each table in `reads:`/`writes:`, configure its MCP servers.
`agents.json` is the machine-readable version — diff it against a clone to find gaps.

## content

Cron/manual-triggered producers of gated drafts (events auto-publishes).

| agent | trigger | model | skills | tools | reads → writes | description |
|---|---|---|---|---|---|---|
| **news-radar** ([agents/scripts/news-radar.mjs](../agents/scripts/news-radar.mjs)) | manual / cron-capable (maintains news-queue.json for the writer) | research=claude-opus-4-8 | — | lib/claude.mjs | — → — | Discover timely niche news and maintain news-queue.json; the daily writer drains it first. |
| **research** ([agents/scripts/research.mjs](../agents/scripts/research.mjs)) | manual (auto-invoked by writer when the evergreen backlog runs low) | research=claude-opus-4-8 | — | lib/claude.mjs, lib/calendar.mjs | — → — | Top up the evergreen backlog in calendar.json (additive, deduped); timely news is the news radar's job. |
| **reviser** ([agents/scripts/revise.mjs](../agents/scripts/revise.mjs)) | manual <slug> (auto-invoked when the SEO gate fails and autoRevise is on) | writer=claude-sonnet-4-6 | — | lib/claude.mjs | — → — | Feed the SEO audit's fixes back to the writer and re-audit until the draft passes or attempts run out. |
| **seo-review** ([agents/scripts/seo-review.mjs](../agents/scripts/seo-review.mjs)) | manual <slug> (auto-invoked by writer/approve gates) | reviewer=claude-opus-4-8 | — | lib/claude.mjs | — → — | Audit one article for EEAT / spam-policy / on-page SEO / AEO / readability → seo-review.json. |
| **writer** ([agents/scripts/write-daily.mjs](../agents/scripts/write-daily.mjs)) | cron:run.sh write-daily.mjs(daily) | writer=claude-sonnet-4-6 | mcp__claude_ai_Higgsfield | lib/claude.mjs, lib/calendar.mjs | — → — | Draft one article (MDX + cover + sources) — today's news first, else next evergreen calendar topic. |

## runtime

HTTP-triggered agents answering live user requests.

| agent | trigger | model | skills | tools | reads → writes | description |
|---|---|---|---|---|---|---|
| **in-page-console** ([agents/console/agents/in-page-console.mjs](../agents/console/agents/in-page-console.mjs)) | POST /run; GET /stream; POST /publish; POST /rebuild; POST /discard | claude-sonnet-4-6 | — | Read, Write, Edit, Glob, Grep, WebSearch | — → — | Freeform ▲ editor: describe a change on any page; the agent edits, the console builds an isolated preview, then publish/discard. |
| **project-builder** ([agents/console/agents/project-builder.mjs](../agents/console/agents/project-builder.mjs)) | POST /draft; POST /build-project | claude-sonnet-4-6 | — | Read | cja_projects → cja_projects | Drafts copy and authors a full structured project record (reads uploaded images) for the New Project admin form. Returns JSON; never mutates the repo. |
| **qa** ([agents/console/agents/qa.mjs](../agents/console/agents/qa.mjs)) | POST /qa/run; schedule(heartbeatMin) | claude-sonnet-4-6 | qa | Read, Skill, api/cli/qa-start.php, api/cli/qa-finish.php, api/cli/qa-routes.php, api/cli/qa-autofix.php | cja_qa_runs, cja_qa_findings → cja_qa_runs, cja_qa_findings | Crawls the live site (links, images, forms, API, SEO/meta, a11y); auto-fixes safe findings via the Web Designer queue; runs on a heartbeat. |
| **web-designer** ([agents/console/agents/web-designer.mjs](../agents/console/agents/web-designer.mjs)) | POST /tasks/run | claude-sonnet-4-6 | brand, ui-ux, changelog | Read, Write, Edit, Glob, Grep, WebSearch, Skill, api/cli/tasks-next.php, api/cli/tasks-finish.php, api/cli/seed-changelog.php | cja_tasks, cja_changelog, cja_projects → cja_tasks, cja_changelog, cja_projects | Durable design queue (cja_tasks): runs the full-builder agent on any page from a brief, auto-publishes (build-gated scoped commit), and self-logs to the changelog. Fed by the admin and by QA autofix. |

## plumbing

Deterministic helpers — not agents (no LLM), catalogued for completeness.

| agent | trigger | model | skills | tools | reads → writes | description |
|---|---|---|---|---|---|---|
| **approve** ([agents/scripts/approve.mjs](../agents/scripts/approve.mjs)) | manual <slug> [--force] | - | — | lib/publish.mjs | — → — | Approve a draft: SEO gate, then promote it into the blog, build, go live. No LLM. |
| **list-drafts** ([agents/scripts/list-drafts.mjs](../agents/scripts/list-drafts.mjs)) | manual | - | — | — | — → — | List pending drafts awaiting review. No LLM. |
| **publish-tick** ([agents/scripts/publish-tick.mjs](../agents/scripts/publish-tick.mjs)) | cron:run.sh publish-tick.mjs(15m) | - | — | lib/publish.mjs | — → — | Once per day after the morning floor, publish ONE eligible draft (SEO-gated) with a randomized earlier-today timestamp. No LLM. |
feat: content-pipeline/ → agents/ — formalize the agent system in the seed Adopt the agents/ architecture proven on medellin.co (reference impl): - Move the content engine to a top-level agents/ dir: orchestrators, prompts, config, run.sh, admin console, shared libs. All content-pipeline literals repointed (config paths, scripts, admin, LLM-facing prompts/image.md string, configure.mjs, new-site.sh, astroagent tokenFile, .gitignore runtime block). - Every script carries a parseable @agent-manifest header: name, title, class (content\|operational\|runtime\|plumbing), trigger, model, prompts, skills (MCP), tools, reads/writes tables. 5 content agents + 3 plumbing scripts. - New agents/catalog.mjs generates the catalog from the headers: agents/AGENTS.md (human, grouped by class) + agents/agents.json (machine manifest — a clone diffs it against a source to find missing tools/tables/MCP before running). configure.mjs regenerates the catalog on every identity stamp. No DB table, no watcher. - config.json gains paths.stateDir/newsDir; publish-tick, write-daily, and news-radar read them instead of hardcoding. - Full cut: content-pipeline/ deleted (the seed has no live crons, so no hybrid period needed). Docs updated (AGENTS.md structure + pipeline section, README paths). Clones migrating from content-pipeline/: see medellin.co's .memory/handoffs/agents-directory-migration.md for the cutover playbook (one cron set active at a time; migrate drafts/state after repointing cron). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FMQeUnUrAeexcZ7P2Hxa6G 2026-07-11 20:33:48 +00:00			`# Agent catalog`

			> GENERATED — do not edit. Regenerate with `node agents/catalog.mjs`
			> (source of truth: the `@agent-manifest` header in each script).

			An agent = an LLM orchestrator script + its role prompt (`prompt:`) + its skills
			(MCP servers, `skills:`) + its tools (`api/cli/.php` bridges and `lib/.mjs`, `tools:`).
			`To port an agent to another SeedProject clone, satisfy its manifest: copy its prompts, ensure`
			its tools exist, migrate each table in `reads:`/`writes:`, configure its MCP servers.
			`agents.json` is the machine-readable version — diff it against a clone to find gaps.

			`## content`

			`Cron/manual-triggered producers of gated drafts (events auto-publishes).`

			`\| agent \| trigger \| model \| skills \| tools \| reads → writes \| description \|`
			`\|---\|---\|---\|---\|---\|---\|---\|`
			`\| news-radar ([agents/scripts/news-radar.mjs](../agents/scripts/news-radar.mjs)) \| manual / cron-capable (maintains news-queue.json for the writer) \| research=claude-opus-4-8 \| — \| lib/claude.mjs \| — → — \| Discover timely niche news and maintain news-queue.json; the daily writer drains it first. \|`
			`\| research ([agents/scripts/research.mjs](../agents/scripts/research.mjs)) \| manual (auto-invoked by writer when the evergreen backlog runs low) \| research=claude-opus-4-8 \| — \| lib/claude.mjs, lib/calendar.mjs \| — → — \| Top up the evergreen backlog in calendar.json (additive, deduped); timely news is the news radar's job. \|`
			`\| reviser ([agents/scripts/revise.mjs](../agents/scripts/revise.mjs)) \| manual <slug> (auto-invoked when the SEO gate fails and autoRevise is on) \| writer=claude-sonnet-4-6 \| — \| lib/claude.mjs \| — → — \| Feed the SEO audit's fixes back to the writer and re-audit until the draft passes or attempts run out. \|`
			`\| seo-review ([agents/scripts/seo-review.mjs](../agents/scripts/seo-review.mjs)) \| manual <slug> (auto-invoked by writer/approve gates) \| reviewer=claude-opus-4-8 \| — \| lib/claude.mjs \| — → — \| Audit one article for EEAT / spam-policy / on-page SEO / AEO / readability → seo-review.json. \|`
			`\| writer ([agents/scripts/write-daily.mjs](../agents/scripts/write-daily.mjs)) \| cron:run.sh write-daily.mjs(daily) \| writer=claude-sonnet-4-6 \| mcp__claude_ai_Higgsfield \| lib/claude.mjs, lib/calendar.mjs \| — → — \| Draft one article (MDX + cover + sources) — today's news first, else next evergreen calendar topic. \|`

framework(core): per-project agent roster + unified registry Phase 3. - server.mjs loads only site.agents.enabled, passing per-agent settings - each console agent exports a manifest + register(host, settings); QA reads heartbeatMin/autofix from settings (env fallback) - catalog.mjs folds the runtime (console) agents into agents.json/AGENTS.md via their manifest exports — one registry for pipeline + runtime agents Verified: disabling 'qa' in the roster removes /qa/run + the heartbeat. 2026-07-24 12:03:00 +00:00			`## runtime`

			`HTTP-triggered agents answering live user requests.`

			`\| agent \| trigger \| model \| skills \| tools \| reads → writes \| description \|`
			`\|---\|---\|---\|---\|---\|---\|---\|`
			`\| in-page-console ([agents/console/agents/in-page-console.mjs](../agents/console/agents/in-page-console.mjs)) \| POST /run; GET /stream; POST /publish; POST /rebuild; POST /discard \| claude-sonnet-4-6 \| — \| Read, Write, Edit, Glob, Grep, WebSearch \| — → — \| Freeform ▲ editor: describe a change on any page; the agent edits, the console builds an isolated preview, then publish/discard. \|`
			`\| project-builder ([agents/console/agents/project-builder.mjs](../agents/console/agents/project-builder.mjs)) \| POST /draft; POST /build-project \| claude-sonnet-4-6 \| — \| Read \| cja_projects → cja_projects \| Drafts copy and authors a full structured project record (reads uploaded images) for the New Project admin form. Returns JSON; never mutates the repo. \|`
			`\| qa ([agents/console/agents/qa.mjs](../agents/console/agents/qa.mjs)) \| POST /qa/run; schedule(heartbeatMin) \| claude-sonnet-4-6 \| qa \| Read, Skill, api/cli/qa-start.php, api/cli/qa-finish.php, api/cli/qa-routes.php, api/cli/qa-autofix.php \| cja_qa_runs, cja_qa_findings → cja_qa_runs, cja_qa_findings \| Crawls the live site (links, images, forms, API, SEO/meta, a11y); auto-fixes safe findings via the Web Designer queue; runs on a heartbeat. \|`
			\| web-designer ([agents/console/agents/web-designer.mjs](../agents/console/agents/web-designer.mjs)) \| POST /tasks/run \| claude-sonnet-4-6 \| brand, ui-ux, changelog \| Read, Write, Edit, Glob, Grep, WebSearch, Skill, api/cli/tasks-next.php, api/cli/tasks-finish.php, api/cli/seed-changelog.php \| cja_tasks, cja_changelog, cja_projects → cja_tasks, cja_changelog, cja_projects \| Durable design queue (cja_tasks): runs the full-builder agent on any page from a brief, auto-publishes (build-gated scoped commit), and self-logs to the changelog. Fed by the admin and by QA autofix. \|

feat: content-pipeline/ → agents/ — formalize the agent system in the seed Adopt the agents/ architecture proven on medellin.co (reference impl): - Move the content engine to a top-level agents/ dir: orchestrators, prompts, config, run.sh, admin console, shared libs. All content-pipeline literals repointed (config paths, scripts, admin, LLM-facing prompts/image.md string, configure.mjs, new-site.sh, astroagent tokenFile, .gitignore runtime block). - Every script carries a parseable @agent-manifest header: name, title, class (content\|operational\|runtime\|plumbing), trigger, model, prompts, skills (MCP), tools, reads/writes tables. 5 content agents + 3 plumbing scripts. - New agents/catalog.mjs generates the catalog from the headers: agents/AGENTS.md (human, grouped by class) + agents/agents.json (machine manifest — a clone diffs it against a source to find missing tools/tables/MCP before running). configure.mjs regenerates the catalog on every identity stamp. No DB table, no watcher. - config.json gains paths.stateDir/newsDir; publish-tick, write-daily, and news-radar read them instead of hardcoding. - Full cut: content-pipeline/ deleted (the seed has no live crons, so no hybrid period needed). Docs updated (AGENTS.md structure + pipeline section, README paths). Clones migrating from content-pipeline/: see medellin.co's .memory/handoffs/agents-directory-migration.md for the cutover playbook (one cron set active at a time; migrate drafts/state after repointing cron). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FMQeUnUrAeexcZ7P2Hxa6G 2026-07-11 20:33:48 +00:00			`## plumbing`

			`Deterministic helpers — not agents (no LLM), catalogued for completeness.`

			`\| agent \| trigger \| model \| skills \| tools \| reads → writes \| description \|`
			`\|---\|---\|---\|---\|---\|---\|---\|`
			`\| approve ([agents/scripts/approve.mjs](../agents/scripts/approve.mjs)) \| manual <slug> [--force] \| - \| — \| lib/publish.mjs \| — → — \| Approve a draft: SEO gate, then promote it into the blog, build, go live. No LLM. \|`
			`\| list-drafts ([agents/scripts/list-drafts.mjs](../agents/scripts/list-drafts.mjs)) \| manual \| - \| — \| — \| — → — \| List pending drafts awaiting review. No LLM. \|`
			`\| publish-tick ([agents/scripts/publish-tick.mjs](../agents/scripts/publish-tick.mjs)) \| cron:run.sh publish-tick.mjs(15m) \| - \| — \| lib/publish.mjs \| — → — \| Once per day after the morning floor, publish ONE eligible draft (SEO-gated) with a randomized earlier-today timestamp. No LLM. \|`