docs(creating-cloud-persona): correct to the v4 event model + field-tested gotchas

[khaliqgant]

Why

Authoring two real cloud personas against this skill (on runtime 4.1.14 / persona-kit & cli 4.1.12) surfaced several instructions that are now stale and fail to typecheck, compile, or deploy. This PR brings the skill in line with the shipped runtime.

What changed (SKILL.md only)

• Event model (v4). The pre-v4 event.source / event.payload / event.name shape — and WorkforceProviderEvent — were removed. Handlers branch on the provider-prefixed event.type (slack.message.created, linear.issue.create, cron.tick, …) and read the payload via await event.expand('full') (async). Added an authoritative "Event model (v4)" section and updated the trigger model, the canonical starter agent.ts, the event-shape guidance, and the handler-pattern guards.
• Cron has no schedule name. Branch on event.type === 'cron.tick'; the only fields are event.schedule / event.scheduledFor. Removed the event.name discrimination guidance (it became a permanent silent no-op).
• New "Field gotchas" section for things that each cost a compile/deploy failure:
  • intent must be a PERSONA_INTENTS value (planning is a valid tag, not an intent);
  • an input can't set both optional: true and default;
  • agentworkforce deploy takes the persona.json file path, not the directory (a dir → EISDIR);
  • memory is append-only (no delete/upsert; recall ranks by relevance) → tightness needs single-author + newest-by-createdAt + carry-forward + short TTLs + consolidation;
  • teamSolve fan-out is all-or-nothing on the lead's fire (and wired to the GitHub-issue path), so prefer an independent shared-memory collective when teammates need distinct cadences.

Net: +153 / -55 lines, docs only.

🤖 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 42 minutes and 30 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: 7f48f811-77a8-4e87-9f95-f0c5faa892d3

📥 Commits

Reviewing files that changed from the base of the PR and between dd83a81 and f4dd86e.

📒 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 fix/creating-cloud-persona-v4-event-model

---

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]

Code Review

This pull request updates the SKILL.md documentation to align with the new Event model (v4) for cloud personas, replacing deprecated properties like event.source and event.payload with event.type and async payload expansion. It also adds a new section on field gotchas and updates deploy commands to use the persona.json file path. The reviewer correctly noted a factual inaccuracy in the updated text, which still claimed that inline examples used the old shape, and provided a helpful suggestion to fix it.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The sentence states that "most of the inline examples further down still use it [the pre-v4 shape]", but this pull request actually updates all the inline examples in this file to use the new v4 event model. To avoid confusing the reader, this sentence should be updated to reflect that the examples have been updated.

Suggested change

	The handler branches on `event.type` (a provider-prefixed dotted string like
	`slack.message.created`, `linear.issue.create`, or `cron.tick`) and reads the
	payload via `await event.expand('full')`. **See "Event model (v4)" below — the
	pre-v4 `event.source` / `event.payload` / `event.name` shape is GONE in
	runtime ≥ 4, and most of the inline examples further down still use it.**
	The handler branches on `event.type` (a provider-prefixed dotted string like
	`slack.message.created`, `linear.issue.create`, or `cron.tick`) and reads the
	payload via `await event.expand('full')`. **See "Event model (v4)" below — the
	pre-v4 `event.source` / `event.payload` / `event.name` shape is GONE in
	runtime ≥ 4, and the inline examples further down have been updated to reflect this.**

[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 PR touches only SKILL.md. The reference types were not updated, so the contradiction between the new v4 prose and the vendored runtime/src/types.ts (and most example agents) is real and remains in the tree.

There is no CI/build/test for this docs repo (no .github/workflows, no package.json test). There are no bot or human review comments supplied in the harness. I made no edits — the only substantive findings are doc-consistency/accuracy matters that require human judgment (verifying which event model is actually correct against runtime 4.1.14, which I cannot do from this checkout).

Here is my review.

---

Review summary

PR #84 is documentation-only: it rewrites skills/creating-cloud-persona/SKILL.md to describe a "v4 event model" (event.type discriminant, cron.tick, async event.expand('full'), no event.source/event.payload/event.name) and adds a "Field gotchas" section (G1–G6). 153 insertions / 55 deletions, one file. No code, tests, or build are affected, and the repo has no CI workflow.

I made no edits. The added prose is mechanically clean (no typos, no broken markdown, all internal cross-references — "Event model (v4)", G2, §7 — resolve). The remaining findings are accuracy/consistency matters that require human judgment, so I'm leaving them as comments rather than changing files.

Findings (review comments — not auto-fixed)

1. The new v4 prose contradicts the vendored reference types this same skill calls the source of truth. SKILL.md:57-76 ("the pre-v4 { source, payload, workspaceId } shape — and WorkforceProviderEvent / WorkforceCronEvent — were removed … Authoring against them fails to typecheck") directly conflicts with references/workforce/packages/runtime/src/types.ts, which still exports WorkforceCronEvent (source: 'cron', name, cron), WorkforceProviderEvent (source, type, payload), and WorkforceEvent = WorkforceCronEvent | LinearAgentSessionEvent | WorkforceProviderEvent. The doc's "First read" section (SKILL.md:58-66) tells authors to treat those vendored types as "current types." An author who follows the doc will read types that say the opposite of the new prose. Either the reference types need re-vendoring from runtime 4.1.14, or the "GONE/removed/fails to typecheck" claims are overstated. I can't verify which from this checkout (runtime 4.1.14 isn't present), so this is a human decision.

2. event.expand('full') is asserted as the only payload access, but the vendored types expose no expand method and most examples use event.payload. The reference agents are mixed: references/agents/review/agent.ts:85, weekly-digest/agent.ts:28, linear-slack/agent.ts:67 use event.source/event.payload/event.name; only hn-monitor/agent.ts:82 uses event.expand('full'). The PR acknowledges this ("most of the inline examples further down still use it"), but shipping a doc whose canonical example uses an API absent from the bundled types is a correctness risk worth a human confirming against the real runtime before merge.

3. Advisory (see below). The mismatch in docs(skill): improve headless orchestrator broker guidance #1/bump: writing-agent-relay-workflows → 1.0.5 #2 suggests the references/ snapshot should be re-vendored from runtime 4.1.14 in the same change, so the doc and its own cited types agree.

Advisory Notes

• Re-vendoring references/workforce/packages/runtime/src/types.ts and updating the pre-v4 example agent.ts files to the v4 shape would make this skill internally consistent. That touches files outside this PR's stated purpose (the prose correction) and is a larger change, so it does not belong in this PR — recording it here rather than editing.

Addressed comments

• No bot or human review comments were supplied to the harness (.workforce/ contains only pr.diff, changed-files.txt, context.json; no review/comment payloads). Nothing to reconcile.

Verification

• Confirmed the diff and working tree touch only SKILL.md (git diff --stat vs base: 1 file). No reference types were updated alongside.
• No CI: repo has no .github/workflows and no test/build script, so there is no canonical build/test command to run for a Markdown change.
• Internal cross-references and code-fence/markdown structure of the added sections verified intact; no typos in added lines.

I am not printing READY: findings #1 and #2 are unresolved accuracy questions that need the author/human to confirm the v4 event model against the actual runtime (and likely re-vendor the reference types). Those require human judgment, and I could not verify the underlying claims from this checkout.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f4dd86ebc1

ℹ️ 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]

Update the vendored event references

This caveat only points readers away from inline examples, but the skill still tells agents to read the vendored examples and “current types” first, and listed files such as references/workforce/packages/runtime/src/types.ts and references/workforce/examples/weekly-digest/agent.ts still export/use the removed WorkforceProviderEvent, event.source, and event.name shape. In practice, following the First read section can still lead authors to copy the exact APIs this section says fail to typecheck, so either update those vendored references or explicitly mark them stale here too.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid calling deployment tags open

For personas deployed with the current persona-kit/cloud flow, tags are only leniently parsed locally; deployment validates them against the closed PERSONA_TAGS vocabulary, so off-vocabulary tags can still be rejected with 400 invalid_persona. Calling tags “open-ish” here can make generated personas use arbitrary catalog tags that compile locally but fail at deploy time; this should instead say that planning is a valid member of the closed tag vocabulary.

Useful? React with 👍 / 👎.