docs(creating-cloud-persona): optional integrations + dual-transport pattern

[khaliqgant]

Documents the workforce#252 optional integrations feature in the creating-cloud-persona skill, which previously described PersonaIntegrationConfig as just { source, scope, config } and had no dual-transport guidance.

• Adds optional?: boolean + enabledByInput?: string to the type signature in §3.
• New §3b covering opt-in integrations (persona-kit ≥4.1.12): how enabledByInput prunes a provider's connection/trigger/mount when the input is empty, the gate-on-id semantics, keeping data sources non-optional, and the version requirement.
• Documents the canonical dual-transport agent (one agent declaring both slack + telegram, dispatch by event.type, reply-on-origin) — the pattern now shipping in the agents repo (inbox-buddy, joke-bot, spotify-releases, hn-monitor).

Companion to AgentWorkforce/agents#91.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@khaliqgant, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 53 minutes and 35 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6324eb76-81b5-4117-a912-7e1c203d91ae

📥 Commits

Reviewing files that changed from the base of the PR and between 9bb65fe and 5c4427b.

📒 Files selected for processing (1)

• skills/creating-cloud-persona/SKILL.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch doc-optional-integrations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5c4427bc4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Align optional integration docs with bundled persona-kit

The skill tells authors to use the vendored “current” references, but this advertised type does not match them: skills/creating-cloud-persona/references/workforce/packages/persona-kit/src/types.ts still defines PersonaIntegrationConfig with only source, scope, and config, and the schema mirrors that. With the self-contained refs/references/agents/package.json still on @agentworkforce/persona-kit ^3.0.47, examples using optional and enabledByInput will either fail TypeScript checks or be compiled without the gating fields, so the supposedly optional provider can still connect unconditionally. Please update the vendored persona-kit/schema/package references alongside this guidance or explicitly scope it to repos that have already upgraded.

Useful? React with 👍 / 👎.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

Confirmed: the inline type string in SKILL.md:165 (updated by this PR) now lists 5 fields, but the vendored reference type at types.ts:250 lists only 3. The SKILL.md prose is the only place updated.

My review is complete. This is a documentation-only PR with no buildable code, no CI workflows, and no review comments to address. There is nothing mechanical to auto-fix (formatting and markdown are clean). The one substantive finding — the vendored reference type/schema not matching the newly-documented fields — requires human judgment (regenerating snapshots from persona-kit 4.1.12 or confirming the exact shipped shape), so I'm leaving it as a review comment rather than fabricating type definitions.

I made no edits to the working tree.

---

Review: PR #83 — docs(creating-cloud-persona): document workforce#252 optional integrations + dual-transport pattern

Scope: Documentation-only change to skills/creating-cloud-persona/SKILL.md. Adds a new §3b describing optional: true + enabledByInput for gating conditional integrations, plus a dual-transport (Slack/Telegram) example, and extends the inline PersonaIntegrationConfig type string in §3.

Repo nature: This is a prompt/skills content package (prpm.json), not a buildable codebase. There is no package.json, no .github/workflows, and no canonical build/test/typecheck/lint command to run. So "verify the way CI does" reduces to content/internal-consistency verification, which I performed against the checked-out references.

Findings

1. (Comment — needs human judgment) Vendored reference type & schema don't carry the newly-documented fields.
The skill's "First read" section instructs authors to trust the vendored snapshots as the shipped source of truth, and §4 specifically warns that persona-kit silently strips fields it doesn't recognize. But this PR documents optional/enabledByInput on PersonaIntegrationConfig while the vendored copies still show the old 3-field shape:

• skills/creating-cloud-persona/references/workforce/packages/persona-kit/src/types.ts:250-254 — interface has only source, scope, config.
• .../schemas/persona.schema.json:417-433 — PersonaIntegrationConfig properties are only source, scope, config.
• No reference agent demonstrates the new fields on an integration. The granola example (references/agents/granola/persona.ts:44) uses optional only on an input, not an integration; it is not the dual-transport agent the PR's §3b and commit message describe.

An author following the skill would compare §3b against the vendored type/schema, see the fields missing, and reasonably conclude (per §4's own warning) that the feature isn't real or would be stripped. I did not edit the type/schema/add an example, because doing so would mean fabricating the exact shipped TS shape, JSON-schema entries, and parser behavior (e.g. the "parser rejects optional without enabledByInput" claim at SKILL.md:200) that I cannot verify from the checkout. Recommendation for the author: regenerate the vendored types.ts + persona.schema.json from persona-kit ≥ 4.1.12, and ideally vendor a real dual-transport example, so the self-contained references match the new prose.

2. (Advisory) Resolution-order framing differs between §3b and §3.
§3b (SKILL.md:198) states deploy-time resolution as --input flag > env var > input default. The existing §3 handler accessor (SKILL.md:793-797) resolves env var > ctx.persona.inputs > default. These describe different layers (deploy-time CLI vs in-handler accessor) and aren't strictly contradictory, but a reader may find the two orderings confusing. Optional: a one-line note distinguishing the two layers. Left unchanged.

Mechanical fixes auto-applied

None. The added markdown is well-formed (code fences balanced, headings/anchors consistent, §3→§3b→§1 cross-references resolve). No spelling/format/import issues.

Addressed comments

• No bot or human review comments were present in .workforce/context.json or PR metadata, so there are none to account for.

Advisory Notes

• Finding bump: writing-agent-relay-workflows → 1.0.5 #2 above (resolution-order framing) is advisory and was left unchanged.
• Regenerating the vendored persona-kit types.ts/persona.schema.json snapshots is the proper fix for Finding docs(skill): improve headless orchestrator broker guidance #1 but depends on the actual 4.1.12 source, which is outside this checkout — flagged for the author rather than fabricated here.

Verification

• No build/test/CI command exists in this content repo; nothing to run.
• I made no edits, so the working tree is unchanged from the PR head — nothing to discard.

The PR is internally clean as prose, but Finding #1 is a real documentation-vs-reference inconsistency that a human author should resolve (vendor the matching type/schema/example) before this merges. I'm not printing READY because that finding needs an author decision and content I can't verify, not just a human sign-off on an otherwise-complete change.