chore(template): Documentation Specialist also watches private molecule-controlplane
Per CEO 2026-04-15: the SaaS controlplane (Molecule-AI/molecule-controlplane, PRIVATE Go/Fly.io provisioner) needs documentation coverage too. Updates the agent's role description, initial_prompt, and daily docs-sync cron to handle a third repo with a strict public/private split. ## Privacy rule (the critical addition) molecule-controlplane is private. Two-bucket model: Internal-only changes (handlers, schemas, infra config, billing logic, fly.toml, provisioner internals) → docs go INSIDE the controlplane repo itself (README.md, PLAN.md, docs/internal/*.md). NEVER mentioned in the public docs site. Customer-facing changes (new tier, new region, new SLA, pricing change, signup flow change) → sanitized PUBLIC description on doc.moleculesai.app. Describes the PRODUCT, never the implementation. When unsure: default to internal-only and ask PM before publishing. The privacy rule is repeated three times in the prompt (top of initial_prompt, 1b inside the daily cron, and the role description) so the agent can't miss it. ## Changes - role: extended to mention all three repos + privacy split - initial_prompt: clones controlplane in step 1, reads README+PLAN in step 5, scans recent commits in step 8, lists the four owned surfaces with public/private labels in step 10 - Daily cron: adds step 1b "PAIR RECENT CONTROLPLANE PRS" with the (i)/(ii) internal/customer-facing branching logic - SETUP block: adds controlplane git pull
This commit is contained in:
rabbitblood
parent
53fdffd2c5
commit
41e39c2626
@ -622,21 +622,29 @@ workspaces:
|
||||
|
||||
- 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.
|
||||
Owns end-to-end documentation across THREE Molecule AI repos:
|
||||
(1) the platform monorepo (public, Molecule-AI/molecule-monorepo) —
|
||||
internal architecture, READMEs, edit-history, public API references;
|
||||
(2) the docs site (public, Molecule-AI/docs) — Fumadocs + Next.js 15,
|
||||
deployed to doc.moleculesai.app, customer-facing;
|
||||
(3) the SaaS controlplane (PRIVATE, Molecule-AI/molecule-controlplane) —
|
||||
Go service that provisions tenants on Fly Machines, with the strict
|
||||
rule that private implementation details NEVER leak into the public
|
||||
docs site. Documents controlplane changes only in its own internal
|
||||
README and the platform monorepo's docs/saas/ section (which itself
|
||||
is gated). Public docs only describe the SaaS PRODUCT (signup, billing,
|
||||
tenant lifecycle, multi-tenant data isolation guarantees) — not the
|
||||
provisioner's internals.
|
||||
Watches PRs landing on all three repos 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 has exactly one canonical name across all three repos.
|
||||
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; controlplane
|
||||
internal docs stay current; nothing private leaks to public.
|
||||
tier: 3
|
||||
model: opus
|
||||
files_dir: documentation-specialist
|
||||
@ -647,24 +655,41 @@ workspaces:
|
||||
plugins: [browser-automation]
|
||||
initial_prompt: |
|
||||
You just started as Documentation Specialist. Set up silently — do NOT contact other agents.
|
||||
1. Clone BOTH repos:
|
||||
|
||||
⚠️ PRIVACY RULE (read first, never violate):
|
||||
molecule-controlplane is a PRIVATE repo. Its source code, file paths,
|
||||
internal endpoints, schema details, infra config, billing/auth
|
||||
implementation — none of that goes into the public docs site
|
||||
(Molecule-AI/docs) or the public README in molecule-monorepo. Public
|
||||
docs may describe the SaaS PRODUCT (signup, billing, tenant isolation
|
||||
guarantees) but never the provisioner's internals. When in doubt:
|
||||
don't publish.
|
||||
|
||||
1. Clone all three 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)
|
||||
git clone https://github.com/Molecule-AI/molecule-controlplane.git /workspace/controlplane 2>/dev/null || (cd /workspace/controlplane && 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
|
||||
5. Read /workspace/controlplane/README.md and /workspace/controlplane/PLAN.md
|
||||
— understand what the SaaS provisioner does (private) vs what users see (public)
|
||||
6. 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:
|
||||
7. Run: cd /workspace/repo && git log --oneline -20 -- platform/internal/handlers/ org-templates/ plugins/
|
||||
— note recent public-surface changes in the platform repo
|
||||
8. Run: cd /workspace/controlplane && git log --oneline -20
|
||||
— note recent controlplane changes (these need internal docs only)
|
||||
9. Use commit_memory to save:
|
||||
- Stubs that need backfilling (docs site)
|
||||
- Recent platform PRs that have NO docs PR yet
|
||||
- Recent controlplane PRs whose internal README needs an update
|
||||
- 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
|
||||
10. Wait for tasks from PM. Your owned surfaces are:
|
||||
- https://github.com/Molecule-AI/docs (customer site, Fumadocs) — PUBLIC
|
||||
- /workspace/repo/docs/ (internal architecture / edit-history) — PUBLIC
|
||||
- /workspace/repo/README.md and per-package READMEs — PUBLIC
|
||||
- /workspace/controlplane/README.md, PLAN.md, internal docs — PRIVATE
|
||||
schedules:
|
||||
- name: Daily docs sync — backfill stubs and pair recent platform PRs
|
||||
cron_expr: "0 9 * * *"
|
||||
@ -676,8 +701,9 @@ workspaces:
|
||||
SETUP:
|
||||
cd /workspace/repo && git pull 2>/dev/null || true
|
||||
cd /workspace/docs && git pull 2>/dev/null || true
|
||||
cd /workspace/controlplane && git pull 2>/dev/null || true
|
||||
|
||||
1. PAIR RECENT PLATFORM PRS (last 24h):
|
||||
1a. 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)" \
|
||||
@ -692,6 +718,26 @@ workspaces:
|
||||
(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.
|
||||
|
||||
1b. PAIR RECENT CONTROLPLANE PRS (last 24h):
|
||||
cd /workspace/controlplane
|
||||
gh pr list --repo Molecule-AI/molecule-controlplane --state merged \
|
||||
--search "merged:>$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)" \
|
||||
--json number,title,files
|
||||
⚠️ PRIVATE REPO. Two cases:
|
||||
(i) Internal-only change (handler, schema, infra, fly.toml,
|
||||
billing logic): update README.md + PLAN.md + any
|
||||
docs/internal/*.md inside molecule-controlplane itself.
|
||||
Open the PR against Molecule-AI/molecule-controlplane.
|
||||
NEVER mention these changes in /workspace/docs.
|
||||
(ii) Customer-facing change (new tier, new region, new SLA,
|
||||
pricing change, signup flow change): write a sanitized
|
||||
description for the PUBLIC docs site (e.g. "We now offer
|
||||
EU-region tenants" — NOT "controlplane reads FLY_REGION
|
||||
from env and passes it to provisioner.go:142"). Open a
|
||||
PR against Molecule-AI/docs.
|
||||
When unsure which category a change falls into: default to
|
||||
INTERNAL-only and ask PM for explicit approval before publishing.
|
||||
|
||||
2. BACKFILL ONE STUB PAGE:
|
||||
cd /workspace/docs
|
||||
grep -l "Coming soon" content/docs/*.mdx | head -1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user