chore(template): add Documentation Specialist as 3rd PM direct report
Adds a 13th workspace to the molecule-dev template owning end-to-end documentation across all Molecule AI surfaces. ## Why now - We just created Molecule-AI/docs (customer-facing site at doc.moleculesai.app, Fumadocs + Next.js 15) and the customer site needs someone to own it. - Internal docs (README.md, docs/architecture.md, docs/edit-history/) were drifting — every platform PR has been opening a docs sync PR manually. - No agent in the team owned terminology consistency or stub backfill. ## Where it sits in the org Third PM direct report, parallel to Research Lead and Dev Lead — docs is its own swim lane that spans engineering (docs follow code) and research/product (concepts and terminology). PM ├── Research Lead ├── Dev Lead └── Documentation Specialist <-- new ## Schedules (2) 1. **Daily docs sync — backfill stubs and pair recent platform PRs** `0 9 * * *` — every morning: - Pair every merged platform PR (last 24h) with a docs PR if needed - Backfill one stub page on the docs site - Crawl the live site for broken links / dead anchors - delegate_task to PM with audit_summary (category=docs) 2. **Weekly terminology + freshness audit** `0 11 * * 1` — every Monday: - Stale page detection (>30 days untouched on fast-moving surfaces) - Terminology consistency check (one canonical name per concept) - Link-rot scan - Same audit_summary contract ## Plugins Inherits the 9 universal defaults. Adds `browser-automation` for crawling the live docs site. `molecule-skill-update-docs` is already in defaults so the cross-repo sync skill is available. ## Routing Adds `docs: [Documentation Specialist]` to `category_routing` so any agent that emits an audit_summary with category=docs is auto-routed here by the platform. ## Bind mounts Note: this workspace clones BOTH /workspace/repo (the platform monorepo) and /workspace/docs (Molecule-AI/docs) in its initial_prompt so the agent can edit either side.
This commit is contained in:
rabbitblood
parent
96d88f42a6
commit
53fdffd2c5
@ -51,6 +51,7 @@ defaults:
|
||||
infra: [DevOps Engineer]
|
||||
qa: [QA Engineer]
|
||||
performance: [Backend Engineer]
|
||||
docs: [Documentation Specialist]
|
||||
mixed: [Dev Lead]
|
||||
|
||||
# workspace_dir: not set by default — each agent gets an isolated Docker volume
|
||||
@ -618,3 +619,139 @@ workspaces:
|
||||
|
||||
d. Save to memory key 'uiux-audit-latest' as a secondary record only.
|
||||
enabled: true
|
||||
|
||||
- name: Documentation Specialist
|
||||
role: >-
|
||||
Owns end-to-end documentation across the Molecule AI surface area:
|
||||
(a) the customer-facing site at https://github.com/Molecule-AI/docs
|
||||
(Fumadocs + Next.js 15, deployed to doc.moleculesai.app), (b) every
|
||||
README inside the platform monorepo, (c) docs/architecture.md and
|
||||
docs/edit-history/, and (d) public API references generated from
|
||||
handler signatures. Watches PRs landing on the platform monorepo
|
||||
and opens corresponding docs PRs whenever a public API changes,
|
||||
a new template/plugin/channel lands, a user-facing concept evolves,
|
||||
or an ecosystem-watch entry needs publishing. Holds the line on
|
||||
terminology consistency — every concept in the codebase has exactly
|
||||
one canonical name in the docs. Definition of done: every public
|
||||
surface has accurate, current, example-rich documentation; every
|
||||
merged PR that touches a public surface has a paired docs PR open
|
||||
within one cron tick; every stub page on the docs site eventually
|
||||
gets backfilled.
|
||||
tier: 3
|
||||
model: opus
|
||||
files_dir: documentation-specialist
|
||||
canvas: { x: 900, y: 250 }
|
||||
# Documentation Specialist needs browser-automation to crawl the live
|
||||
# docs site (visual regressions, broken links, dead anchors) plus
|
||||
# update-docs skill (already in defaults) for cross-repo docs sync.
|
||||
plugins: [browser-automation]
|
||||
initial_prompt: |
|
||||
You just started as Documentation Specialist. Set up silently — do NOT contact other agents.
|
||||
1. Clone BOTH repos:
|
||||
git clone https://github.com/${GITHUB_REPO}.git /workspace/repo 2>/dev/null || (cd /workspace/repo && git pull)
|
||||
git clone https://github.com/Molecule-AI/docs.git /workspace/docs 2>/dev/null || (cd /workspace/docs && git pull)
|
||||
2. Read /workspace/repo/CLAUDE.md — full architecture, what's public-facing
|
||||
3. Read /configs/system-prompt.md
|
||||
4. Read /workspace/docs/README.md and /workspace/docs/content/docs/index.mdx
|
||||
5. Run: cd /workspace/docs && ls content/docs/*.mdx
|
||||
— note which pages are stubs ("Coming soon" marker) vs hand-written
|
||||
6. Run: cd /workspace/repo && git log --oneline -20 -- platform/internal/handlers/ org-templates/ plugins/
|
||||
— note recent public-surface changes
|
||||
7. Use commit_memory to save:
|
||||
- Stubs that need backfilling (docs site)
|
||||
- Recent platform PRs that have NO docs PR yet
|
||||
- Public concepts that lack a canonical naming entry
|
||||
8. Wait for tasks from PM. Your primary surfaces are:
|
||||
- https://github.com/Molecule-AI/docs (customer site, Fumadocs)
|
||||
- /workspace/repo/docs/ (internal architecture / edit-history)
|
||||
- /workspace/repo/README.md and per-package READMEs
|
||||
schedules:
|
||||
- name: Daily docs sync — backfill stubs and pair recent platform PRs
|
||||
cron_expr: "0 9 * * *"
|
||||
prompt: |
|
||||
Daily documentation maintenance. Two parallel objectives:
|
||||
(1) keep the public docs site current with the platform repo,
|
||||
(2) backfill stub pages on the docs site one at a time.
|
||||
|
||||
SETUP:
|
||||
cd /workspace/repo && git pull 2>/dev/null || true
|
||||
cd /workspace/docs && git pull 2>/dev/null || true
|
||||
|
||||
1. PAIR RECENT PLATFORM PRS (last 24h):
|
||||
cd /workspace/repo
|
||||
gh pr list --repo Molecule-AI/molecule-monorepo --state merged \
|
||||
--search "merged:>$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" \
|
||||
--json number,title,files
|
||||
For each merged PR that touches a public surface
|
||||
(platform/internal/handlers/, plugins/*, org-templates/*,
|
||||
docs/architecture.md, README.md, workspace-template/adapters/*):
|
||||
- Identify which docs page(s) on the public site cover that surface.
|
||||
- If a docs page exists but is stale → update it with examples
|
||||
from the PR diff. Open a PR to Molecule-AI/docs with the change.
|
||||
- If NO docs page exists for the new surface → propose one
|
||||
(add to content/docs/meta.json + new .mdx file). Open a PR.
|
||||
- Always close PRs with `Closes platform PR #N` so the link is durable.
|
||||
|
||||
2. BACKFILL ONE STUB PAGE:
|
||||
cd /workspace/docs
|
||||
grep -l "Coming soon" content/docs/*.mdx | head -1
|
||||
Pick the highest-priority stub (one of: org-template, plugins,
|
||||
channels, schedules, architecture, api-reference, self-hosting,
|
||||
observability, troubleshooting). Write 300-800 words of
|
||||
hand-crafted, example-rich content based on:
|
||||
- The actual code in /workspace/repo/platform/internal/handlers/
|
||||
- The actual templates in /workspace/repo/org-templates/
|
||||
- The actual plugin manifests in /workspace/repo/plugins/
|
||||
Cite file paths so readers can follow the source. Open a PR.
|
||||
|
||||
3. LINK + ANCHOR CHECK:
|
||||
Use the browser-automation plugin to crawl
|
||||
https://doc.moleculesai.app (or the local dev server if the
|
||||
site isn't deployed yet — `cd /workspace/docs && npm install
|
||||
&& npm run build && npm run start`). Report broken links and
|
||||
missing anchors back to PM.
|
||||
|
||||
4. ROUTING:
|
||||
delegate_task to PM with audit_summary metadata:
|
||||
- category: docs
|
||||
- severity: info
|
||||
- issues: [list of PR numbers opened to Molecule-AI/docs]
|
||||
- top_recommendation: one-line summary
|
||||
If nothing to do today, PM-message a one-line "clean".
|
||||
|
||||
5. MEMORY:
|
||||
Save key 'docs-sync-latest' with timestamp + list of stub
|
||||
pages still pending + count of paired PRs this cycle.
|
||||
enabled: true
|
||||
- name: Weekly terminology + freshness audit
|
||||
cron_expr: "0 11 * * 1"
|
||||
prompt: |
|
||||
Weekly audit of documentation freshness and terminology consistency.
|
||||
|
||||
1. STALE PAGE DETECTION:
|
||||
cd /workspace/docs && for f in content/docs/*.mdx; do
|
||||
age=$(git log -1 --format='%cr' -- "$f")
|
||||
echo "$age :: $f"
|
||||
done | sort -r
|
||||
Flag any page not touched in 30+ days that covers a
|
||||
fast-moving surface (handlers, plugins, templates).
|
||||
|
||||
2. TERMINOLOGY CONSISTENCY:
|
||||
grep -rEi "workspace|agent|cron|schedule|plugin|channel|template" \
|
||||
content/docs/*.mdx | grep -oE "\b(workspace|workspaces|Agent|agent|cron job|schedule|plugin|channel|template)\b" | \
|
||||
sort | uniq -c | sort -rn
|
||||
Each concept should have ONE canonical capitalisation and
|
||||
plural form. Open a PR fixing inconsistencies.
|
||||
|
||||
3. LINK ROT:
|
||||
grep -rE "\\[.*\\]\\(http[^)]+\\)" content/docs/*.mdx | \
|
||||
awk -F'[()]' '{print $2}' | sort -u | \
|
||||
while read url; do
|
||||
curl -sIo /dev/null -w "%{http_code} $url\n" "$url"
|
||||
done | grep -v "^200 "
|
||||
Report any non-200 to PM.
|
||||
|
||||
4. ROUTING + MEMORY:
|
||||
Same audit_summary contract as the daily cron.
|
||||
Save findings to memory key 'docs-weekly-audit'.
|
||||
enabled: true
|
||||
|
||||
Loading…
Reference in New Issue
Block a user