feat(factory): software factory pipeline — ready-for-agent → scope → team spawn → implement

[khaliqgant]

Summary

• writeRemoteFile IPC — renderer/agents can now create/update Linear issues via the integration mount (the Phase 2 write primitive from the issue-control-center spec)
• ready-for-agent 4th band in Attention Inbox — issues with that status/label surface between "Needs you" and "In motion", expanded by default, with repo detection badges and a live Spawn Team button
• spawnTeamForIssue() — spawns coordinated codex-impl + claude-review pairs with task prompts referencing the issue, wired to the Spawn Team button
• issue-scoping module — detectRepo() keyword-scores issue text to detect repo (relay/pear/workforce), suggestTeamSize() estimates complexity, labelIssueWithRepo() writes the label via writeRemoteFile
• board-steward persona — proactive agent that watches for ready-for-agent issues, auto-scopes them, spawns teams, and moves cards through the pipeline

The Pipeline

User chat → creates Linear issue (ready-for-agent)
    ↓
Board steward scopes it → detects repo → adds Repo: relay label
    ↓
Board steward spawns team → codex-impl + claude-review pair
    ↓
Agents implement → open PR → issue moves to In Review

Test plan

• npm run build:web — verify mock ready-for-agent issues appear in the new Inbox band with repo badges
• Verify Spawn Team button renders on ready-for-agent cards (inert in web build, live in Electron)
• tsc -p tsconfig.web.json --noEmit passes (renderer gate)
• In Electron: create a Linear issue with ready-for-agent label → confirm it appears in the correct band
• In Electron: click Spawn Team → confirm codex + claude agents spawn with task prompts
• Launch board-steward persona from Spawn Agent dialog → confirm it's discoverable

🤖 Generated with Claude Code

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

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 13 minutes and 11 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

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

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

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: 7345971a-e2c2-47b9-b656-5f43d32dd2e3

📥 Commits

Reviewing files that changed from the base of the PR and between 7d4f324 and b083ecb.

📒 Files selected for processing (12)

• .agentworkforce/workforce/personas/slack-comms.json
• AGENTS.md
• src/main/broker.ts
• src/main/ipc-handlers.ts
• src/preload/index.ts
• src/renderer/src/components/issues/AttentionInbox.tsx
• src/renderer/src/lib/ipc-mock.ts
• src/renderer/src/lib/terminal-reconciler.test.ts
• src/renderer/src/lib/terminal-reconciler.ts
• src/renderer/src/lib/terminal-runtime-registry.ts
• src/renderer/src/stores/issues-store.ts
• src/shared/types/ipc.ts

📝 Walkthrough

Walkthrough

This PR introduces the ready-for-agent issue dispatch workflow: a new issue band classification, heuristic-based repo detection and team-size suggestion utilities, a dual-agent spawning mechanism, UI enhancements to the Attention Inbox component, and a backend board-steward automation persona. The changes span IPC infrastructure for remote file writes, classification logic, team composition, and end-to-end testing fixtures.

Changes

Ready-for-agent issue dispatch and team spawning

Layer / File(s)	Summary
IPC contract and remote file write API src/shared/types/ipc.ts, src/main/integrations.ts, src/main/ipc-handlers.ts, src/preload/index.ts	Shared IPC contract adds writeRemoteFile signature. Integrations manager validates normalized path within project scope and writes via Relayfile. IPC handler routes renderer requests. Preload exposes method to renderer processes.
Issue scoping heuristics for repo and team size detection src/renderer/src/lib/issue-scoping.ts, src/renderer/src/lib/issue-scoping.test.ts	New module exports detectRepo to score repositories by keyword matching and suggestTeamSize to classify issues as solo/pair/swarm based on keywords and description length; comprehensive test coverage validates tie handling and no-match cases.
Team composition and dual-agent spawning src/renderer/src/lib/spawn-agent.ts	Introduces TeamComposition type capturing issue metadata. spawnTeamForIssue spawns implementation and review agents using deterministic naming, constructs prompts including optional detected repo, and returns agent names. Legacy spawnProjectPersona removed.
Issue band classification for ready-for-agent status src/renderer/src/stores/issues-store.ts	IssueBand type adds 'ready-for-agent' member. BAND_ORDER includes ranking between needs-you and in-motion. classifyIssue adds early-return rule for issues with ready-for-agent stage or label variants.
Attention Inbox UI for ready-for-agent band and team spawning src/renderer/src/components/issues/AttentionInbox.tsx	Adds ready-for-agent band metadata, icon, and empty-state messaging. Issue card extends with optional onSpawnTeam callback and renders computed detectedRepo as a purple pill. Conditional "Spawn Team" button dispatches handleSpawnTeam handler that detects repo, composes team, spawns agents, and updates nav notice. Band section renders with default expanded state and issue subset.
Test fixtures and mocks for remote write and issue workflows src/main/integrations.test.ts, src/renderer/src/lib/ipc-mock.ts	Integrations test adds writeFileCalls recorder to mock Relayfile writeFile with scope validation cases (in-scope success and out-of-scope rejection). IPC mock adds new Linear issue fixtures and writeRemoteFile implementation that normalizes paths and stores parsed JSON to mock remote filesystem.
Board steward automation workflow persona .agentworkforce/workforce/personas/board-steward.json	Defines automated board steward persona with system prompt orchestrating issue scan/triage, repo detection with tie handling, complexity tiering, writeback updates via integration APIs, channel posting, processed-issue tracking, and in-progress PR monitoring. Sets permissions to bypassPermissions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• AgentWorkforce/pear#186: Both PRs modify scope validation in src/main/integrations.ts for Slack DM event paths; this PR's writeRemoteFile also validates against DM-listing-enabled scope.
• AgentWorkforce/pear#183: Previously extended src/renderer/src/components/issues/AttentionInbox.tsx with issue banding and drill-down logic; this PR further extends it with the new ready-for-agent band and spawn-team controls.

Poem

A steward arrives at the board's edge, keen,
Surveys issues ready, their purpose foreseen,
Teams spawn with a click—impl and review,
Repos detected, complexity shines through,
Workflow orchestrated, the dispatch is spun—
chirp chirp 🐰 One more agent run begun!

🚥 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 clearly summarizes the main feature: a software factory pipeline implementing ready-for-agent workflows with team spawning and implementation.
Description check	✅ Passed	The description is directly related to the changeset, providing a comprehensive summary of the new features, implementation details, and test plan for the software factory pipeline.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/software-factory-pipeline

---

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

[agent-relay-code]

Implemented two fixes:

• Fixed detectRepo so it returns null on tied top scores instead of guessing the first matching repo, with regression coverage in issue-scoping.ts and issue-scoping.test.ts.
• Fixed IntegrationsManager.writeRemoteFile to call the Relayfile SDK’s object-form writeFile({ workspaceId, path, baseRevision, content }), with scope and SDK-shape tests in integrations.ts and integrations.test.ts.

Addressed comments

• No bot/reviewer comment artifacts were present under .workforce; there were no external review threads to validate or address.
• Self-review: repo detection tie incorrectly guessed a repo; fixed in src/renderer/src/lib/issue-scoping.ts.
• Self-review: Relayfile SDK write call used the wrong signature; fixed in src/main/integrations.ts.

Advisory Notes

• I did not run the macOS-only packaged smoke job (dist:mac / verify:mcp-spawn) from the Linux sandbox.
• I cannot confirm GitHub-side pending check status or mergeability from this checkout-only workflow, so I am not printing READY.

Local validation passed:

npm ci, npm run verify:mcp-resources-drift, npm run lint, npm run typecheck:web, npm run typecheck:node, npm test, npx vitest run, npm run build, npm run build:web, npx playwright test --config playwright.fidelity.config.ts, and npx playwright test --config playwright.redraw.config.ts.

[coderabbitai]

Actionable comments posted: 8

🧹 Nitpick comments (1)

src/renderer/src/lib/issue-scoping.test.ts (1)

4-16: ⚡ Quick win

Add regression cases for keyword-boundary collisions and suggestTeamSize.

This suite only covers the happy-path detectRepo branches. Please add cases proving build does not score ui, prefix cleanup does not hit fix, and direct coverage for the 200/2000-length and keyword branches in suggestTeamSize; those are the branches most likely to drift.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/renderer/src/lib/issue-scoping.test.ts` around lines 4 - 16, Add tests to
cover keyword-boundary collisions and suggestTeamSize edge cases: add a
detectRepo test ensuring the keyword "build" does not falsely match the "ui"
repo (e.g., title/body containing "build" adjacent to other words), another
detectRepo test ensuring "prefix cleanup" does not match the "fix" repo, and
tests exercising suggestTeamSize's branches (one with ~200 chars and one with
~2000 chars plus a case triggering keyword-based sizing). Use the existing test
file's describe('detectRepo') context and reference the detectRepo and
suggestTeamSize functions so that the new tests assert null or expected sizes
for those specific inputs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agentworkforce/workforce/personas/board-steward.json:
- Around line 22-24: The persona currently sets "permissions": { "mode":
"bypassPermissions" } which grants full tool authority; replace this with a
scoped, least-privilege permission object for the board-steward persona that
enumerates only the actions it needs (e.g., writeback:issues or writeback:tasks,
messaging:send, spawn:agent or spawn:subtask, dispatch:workflow) instead of
bypassPermissions; update the "permissions" entry to list a "mode": "scoped" (or
remove mode) and a "scopes" array containing the exact capabilities (writeback,
messaging, spawn, dispatch) required for its writebacks and dispatch actions so
the persona cannot perform any other tool operations.
- Line 13: The persona's description claims it "spawns codex-impl +
claude-review agent pairs" but the operational steps only post messages/DMs and
contain no spawn action; either implement an actual spawn call to the dispatcher
(e.g., invoke the system's spawnAgentTeam or createAgentPair API with parameters
for codex-impl and claude-review where the persona posts the work) in the
persona's operational steps, or change the "description" field to explicitly
state "triage + announce" (remove "spawns" language) so the contract matches the
implemented behavior; update the JSON key "description" and the persona's
operational steps that currently send messages/DMs so they either call the
dispatcher API or reflect the narrowed scope.
- Line 25: Change the processed-issues contract used by the Board Steward
(currently /tmp/board-steward-processed.json referenced in Core Loop step 2 and
step 10) from a simple JSON array of IDs to an append-only JSON array of
structured records (e.g., { "id": "<issue-id>", "state":
"dispatched|failed|retrying|done", "attempts": N, "lastError": "...", "retry":
true/false, "ts": "<iso>" }); update the "skip any issue whose ID appears" check
to instead skip only when the latest record for that issue has state
"dispatched" or "done", and on failures append a new record with state "failed"
or "retrying" and increment attempts so retries are allowed per the retry flag;
ensure writeback logic that appends records after each dispatch attempt and
reading logic picks the latest record per issue to determine eligibility.

In `@src/main/integrations.ts`:
- Around line 1119-1121: writeRemoteFile is using the read-only handle from
withIntegrationRemoteHandle (which currently pulls
getIntegrationRemoteReaderHandle with scope relayfile:fs:read:/**) and so
client().writeFile can be rejected; change writeRemoteFile to obtain/construct a
writer handle with write scope (relayfile:fs:write:* or the specific path scope)
instead of the reader handle—either add a new getIntegrationRemoteWriterHandle
and a corresponding withIntegrationRemoteWriterHandle helper, or extend
withIntegrationRemoteHandle to accept a scope/mode parameter and pass the write
scope when calling client().writeFile so the call is authorized.

In `@src/renderer/src/components/issues/AttentionInbox.tsx`:
- Around line 573-586: handleSpawnTeam currently calls
useProjectStore.getState().getActiveProject() which can point to a different
project than the one displayed; change it to resolve the project using the
component's resolvedProjectId (instead of getActiveProject()) before calling
spawnTeamForIssue, and if no project is found for resolvedProjectId fail visibly
(e.g. setNavNotice or throw an error) rather than silently returning; update
references inside handleSpawnTeam (project variable) and ensure
spawnTeamForIssue is passed the resolved project.

In `@src/renderer/src/lib/ipc-mock.ts`:
- Around line 1087-1091: The mock writeRemoteFile implementation is too strict
because it JSON.parses every content string; update the writeRemoteFile async
function to store the raw content string into mockRemoteFiles using the
normalized key (use normalizeMockRemotePath(remotePath) and
mockRemoteFiles[normalized] = content) instead of JSON.parse(content) so the
mock matches the production IPC contract that accepts arbitrary string content;
keep the existing console.log and function signature unchanged.

In `@src/renderer/src/lib/issue-scoping.ts`:
- Around line 13-15: The current substring matching (keywords.filter(kw =>
text.includes(kw))) in detectRepo/REPO_KEYWORDS leads to false positives;
replace it with token-aware matching by normalizing text (lowercase, remove
punctuation), splitting into tokens (e.g., /\w+/) or using word-boundary regexes
(\\bkeyword\\b) and then counting token matches per repo; update the scoring
logic where keywords.filter(...) is used (including the similar logic at lines
31-34) so it only increments for whole-token matches and handles multi-word
keywords consistently.

In `@src/renderer/src/lib/spawn-agent.ts`:
- Around line 130-155: spawnTeamForIssue can leave partial state on failure;
make the operation idempotent by using deterministic agent names and atomic
existence checks plus cleanup on abort: before calling spawnProjectAgent, derive
deterministic names (e.g., `${composition.issueIdentifier}-impl` and `-review`)
and check a shared registry/locker (or call spawnProjectAgent in a mode that
returns existing agent if present) so repeated calls return the same
implName/reviewName instead of creating `-2` variants; if any step after
creating an agent fails (e.g., second spawn or pear.broker.sendMessage), perform
compensating cleanup (delete the newly created agent or rollback registry entry)
or persist the mapping atomically so retries see the created pair; update
spawnProjectAgent callers here to use existence-returning/spawn-or-get behavior
and ensure pear.broker.sendMessage failures trigger the cleanup/rollback path.

---

Nitpick comments:
In `@src/renderer/src/lib/issue-scoping.test.ts`:
- Around line 4-16: Add tests to cover keyword-boundary collisions and
suggestTeamSize edge cases: add a detectRepo test ensuring the keyword "build"
does not falsely match the "ui" repo (e.g., title/body containing "build"
adjacent to other words), another detectRepo test ensuring "prefix cleanup" does
not match the "fix" repo, and tests exercising suggestTeamSize's branches (one
with ~200 chars and one with ~2000 chars plus a case triggering keyword-based
sizing). Use the existing test file's describe('detectRepo') context and
reference the detectRepo and suggestTeamSize functions so that the new tests
assert null or expected sizes for those specific inputs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a58eb30b-6dcd-4c6d-9bae-9cc59dfc9983

📥 Commits

Reviewing files that changed from the base of the PR and between 6658bcc and 7d4f324.

📒 Files selected for processing (12)

• .agentworkforce/workforce/personas/board-steward.json
• src/main/integrations.test.ts
• src/main/integrations.ts
• src/main/ipc-handlers.ts
• src/preload/index.ts
• src/renderer/src/components/issues/AttentionInbox.tsx
• src/renderer/src/lib/ipc-mock.ts
• src/renderer/src/lib/issue-scoping.test.ts
• src/renderer/src/lib/issue-scoping.ts
• src/renderer/src/lib/spawn-agent.ts
• src/renderer/src/stores/issues-store.ts
• src/shared/types/ipc.ts

[agent-relay-code]

✅ pr-reviewer applied fixes — committed and pushed e4e2a40 to this PR. The notes below describe what changed.

Implemented fixes for the validated PR findings.

Addressed comments

• gemini-code-assist[bot]: quota warning only; no code issue raised.
• coderabbitai[bot]: board-steward description overstated direct spawning; fixed wording in .agentworkforce/workforce/personas/board-steward.json:13.
• coderabbitai[bot]: board-steward processed issue ledger was too weak for retries; fixed structured append-only record contract in .agentworkforce/workforce/personas/board-steward.json:25.
• coderabbitai[bot]: scoped persona permissions suggestion; not changed because the repo examples/spec use harness permissions directly and I found no supported scoped persona permission schema. See advisory note.
• coderabbitai[bot]: writeRemoteFile used read-scoped Relayfile handle; fixed with a write-scoped handle in src/main/integrations.ts:1122, src/main/integrations.ts:1535, src/main/integrations.ts:1567, and src/main/integrations.ts:1628. Regression assertion added in src/main/integrations.test.ts:400.
• coderabbitai[bot]: spawn team button could use the wrong active project; fixed to resolve resolvedProjectId in src/renderer/src/components/issues/AttentionInbox.tsx:574.
• coderabbitai[bot]: IPC mock parsed every write as JSON; fixed raw string storage/readback in src/renderer/src/lib/ipc-mock.ts:599 and src/renderer/src/lib/ipc-mock.ts:1084.
• coderabbitai[bot]: repo/team-size keyword matching used substrings; fixed token-aware matching in src/renderer/src/lib/issue-scoping.ts:10, src/renderer/src/lib/issue-scoping.ts:14, src/renderer/src/lib/issue-scoping.ts:30, and src/renderer/src/lib/issue-scoping.ts:47.
• coderabbitai[bot]: requested keyword-boundary and suggestTeamSize tests; added in src/renderer/src/lib/issue-scoping.test.ts:17, src/renderer/src/lib/issue-scoping.test.ts:23, src/renderer/src/lib/issue-scoping.test.ts:27, and src/renderer/src/lib/issue-scoping.test.ts:32.
• coderabbitai[bot]: spawnTeamForIssue was not idempotent and could leave partial state; fixed keyed in-flight coalescing, existing-agent reuse, created-agent cleanup, and no duplicate prompt sends in src/renderer/src/lib/spawn-agent.ts:135, src/renderer/src/lib/spawn-agent.ts:150, src/renderer/src/lib/spawn-agent.ts:189, src/renderer/src/lib/spawn-agent.ts:216, and src/renderer/src/lib/spawn-agent.ts:220. Regression tests added in src/renderer/src/lib/spawn-agent.test.ts:61 and src/renderer/src/lib/spawn-agent.test.ts:78.
• coderabbitai[bot]: docstring coverage warning; not changed because this TS repo does not enforce docstrings in CI and adding broad docstrings would be unrelated churn.

Advisory Notes

• Scoped persona permissions would be preferable, but I did not invent a "mode": "scoped" schema because the current repo examples/spec do not show it as supported for AgentWorkforce persona JSON.

Validation

Passed locally: npm ci, npm run verify:mcp-resources-drift, npm run lint, npm run typecheck, npm test, npx vitest run, npm run build, npm run build:web, npx playwright test --config playwright.fidelity.config.ts, and npx playwright test --config playwright.redraw.config.ts.

Could not fully reproduce the macOS packaging CI job on this Linux runner. npm run dist:mac reached the build step, then failed in electron-builder because Linux does not install the Darwin-only optional dmg-license package; consequently npm run verify:mcp-spawn also could not run because dist/ was not produced.

[agent-relay-code]

Reviewed PR #222 against .workforce/pr.diff, changed files, and current checkout. I did not find a reproducible breakage that needed code changes, so I left the working tree code unchanged.

Addressed Comments

• No bot or reviewer comments were present in the provided PR artifacts (.workforce/context.json, .workforce/pr.diff, .workforce/changed-files.txt). Nothing to validate or patch from reviewer threads.

Advisory Notes

• None.

Local verification run:

• npm ci passed
• npm run typecheck passed
• npm run test:all passed: 118 Node tests and 360 Vitest tests
• npm run build passed
• npm run lint passed with warnings only
• npm run verify:mcp-resources-drift passed

I’m not printing READY because I cannot verify GitHub mergeability or live required check status from this sandbox without gh/GitHub access.