fix(cli): digest only the compiled persona in a nested agent dir

[willwashburn]

Follow-up to #316, resolving both review findings.

Launch-plan digest

buildFastLaunchPlan digests one entry per nested agent: <agent>/persona.json. A missing file digests to {size: null, mtimeMs: null}, so that single entry witnesses both the compile that first writes the persona and every later edit to it.

The subdirectory digest that sat alongside it was redundant for that, and harmful in its own right: a directory's mtime moves whenever an entry inside is added, removed, or renamed. agentworkforce persona compile writes agent-card.json next to persona.json, and editors that save by atomic rename touch the handler and README the same way — each of which rebuilt the cached launch plan for a persona that had not changed.

Docs

sources add --position 1 ranks a directory after both fixed working-tree sources, not one.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a4870f6-4a3c-480c-878c-c5dd99c80c81

📥 Commits

Reviewing files that changed from the base of the PR and between 558784d and 0fa1f6d.

📒 Files selected for processing (2)

• packages/cli/README.md
• packages/cli/src/cli-impl.ts

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The CLI now fingerprints nested personas by persona.json and documents the fixed cwd:agents source in source priority and removal rules.

Changes

CLI source and launch behavior

Layer / File(s)	Summary
Persona definition fingerprinting packages/cli/src/cli-impl.ts	Fast-launch digesting tracks each nested persona’s persona.json file instead of the entire persona directory.
Source priority documentation packages/cli/README.md	The sources documentation lists cwd:agents with the fixed sources and describes removal by configurable position or exact path.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 0fa1f

This localized CLI and documentation update is merge-ready after normal checks and review, with no actionable merge-blocking risk remaining.

Possibly related PRs

• AgentWorkforce/workforce#258: Both changes modify fast-launch fingerprinting in packages/cli/src/cli-impl.ts.
• AgentWorkforce/workforce#307: Both changes modify CLI persona-source and registry behavior.

Suggested reviewers: khaliqgant, miyaontherelay

Poem

A rabbit checks the persona file,
And leaves stray siblings in the while.
cwd:agents joins the source parade,
With clear removal rules laid.
Fast launches hop ahead—
By definitions only fed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the launch-plan digest fix and the related documentation correction.
Title check	✅ Passed	The title clearly identifies the main CLI fix: digesting only the compiled persona in a nested agent directory.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.

✨ 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 fix/agent-layer-digest-and-docs

---

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.}

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}