feat(persona-kit): add side-effect-free ./spec validation entrypoint

[willwashburn]

Companion to AgentWorkforce/cloud#2194 (cloud issue #2192).

Why

The package barrel (index.ts) re-exports the orchestration modules — mount, execute, plan, skills, skill-runner, config-files, interactive-spec, … — so importing it just to validate a persona/agent spec EVALUATES every one of those modules' top-level code: node:child_process, node:fs, and the deferred @relayfile/local-mount → @parcel/watcher edge. None of that is needed by a pure validation consumer such as AgentWorkforce Cloud's deploy route (which centralizes persona-kit behind @cloud/core in the companion PR).

What

• Add @agentworkforce/persona-kit/spec — a narrow entrypoint (src/spec.ts) that re-exports only the parsers, type guards, constants, and spec types from parse.ts / constants.ts / types.ts.
• These three modules have zero external (non-relative) imports, so the emitted dist/spec.js likewise has no external requires — no @relayfile/*, no native bindings, no Node process/fs APIs at module-eval time. Verified against the build output.
• Additive export only — the . barrel is unchanged. Versioning is left to CI (no manual version bump in this PR).
• Add src/spec.test.ts covering the re-exported validation surface (incl. the grok harness).

Tests

• pnpm --filter @agentworkforce/persona-kit typecheck: clean.
• pnpm --filter @agentworkforce/persona-kit test: 281/281 pass (4 new spec-entrypoint tests).

Follow-up

Once a version carrying ./spec is published, @cloud/core/proactive-runtime/persona-spec.ts can switch its import from the barrel @agentworkforce/persona-kit to @agentworkforce/persona-kit/spec, eliminating orchestration-module evaluation from the Cloud validation path entirely.

https://claude.ai/code/session_01CsCeMqBz8roJSvgpJeqCt7

[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!

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new ./spec subpath export to @agentworkforce/persona-kit (version bump to 4.1.0). The new spec.ts entrypoint re-exports constants, types, and parsing/validation utilities from existing internal modules without importing any orchestration or Node/process/fs-dependent barrel modules. Tests cover the exported surface and parsing behavior.

Changes

persona-kit ./spec subpath entrypoint

Layer / File(s)	Summary
spec.ts entrypoint and package manifest wiring packages/persona-kit/src/spec.ts, packages/persona-kit/package.json	spec.ts re-exports constants (HARNESS_VALUES, PERSONA_INTENTS, etc.), all public types, and parser/type-guard/sidecar utilities from constants.js, types.js, and parse.js. package.json adds the ./spec subpath mapping to ./dist/spec.js / ./dist/spec.d.ts and bumps the version to 4.1.0.
spec entrypoint tests packages/persona-kit/src/spec.test.ts	Adds Node.js tests verifying parsePersonaSpec, parseAgentSpec, isIntent, isHarness, and HARNESS_VALUES are exported, that parsePersonaSpec round-trips a minimal spec and accepts the grok harness, and that parseAgentSpec returns an object.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 A new little door in the package map,
./spec opens clean — no side-effect trap!
Constants and parsers hop right on through,
No fs or process to muddy the view.
Tests confirm every export's in place —
This rabbit approves of the narrowed interface! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a new side-effect-free validation entrypoint to the persona-kit package.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description clearly explains the motivation (avoiding unnecessary orchestration module evaluation during spec validation) and details the implementation (new spec entrypoint with re-exports of validation-only code).

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/exciting-maxwell-7dsgfm

---

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 and usage tips.}