feat: add meta workflows for --agent flag implementation

[khaliqgant]

Summary

Add 5 phase meta workflows for implementing the --agent flag feature in agent-relay.

Meta Workflows

Each phase includes design spec (.spec.md) and implementation workflow (.ts):

Phase	Description
1	SDK persona resolution utilities (resolvePersonaByIdOrIntent, derivePreset, derivePattern)
2	Workflow generator module
3	CLI --agent flag integration
4	Unit and integration tests
5	Documentation

Motivation

The --agent flag will auto-generate workflows from persona profiles (e.g., agent-relay run "review this PR" --agent security-reviewer).

Files Changed

• build-plans/ - 11 new files (specs + workflow implementations)

---

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 7 additional findings in Devin Review.

[devin-ai-integration]

🔴 Phase workflow files use require() on ESM-only SDK package, deviating from established import pattern

Files build-plans/01-sdk-persona-resolution.ts through build-plans/05-documentation.ts all use createRequire(import.meta.url) + require('@agent-relay/sdk/workflows') to import the SDK. However, the SDK package is ESM-only: its package.json has "type": "module" and the "./workflows" export only provides "import" and "default" conditions — no "require" condition (packages/sdk/package.json:48-53). Node.js require() cannot load ESM modules (throws ERR_REQUIRE_ESM) unless running Node.js 22.12+ where this was unflagged.

All existing workflow files in the repo use direct ESM imports instead:

• workflows/ci/cli-observability.ts:1: import { workflow } from '@agent-relay/sdk/workflows';
• workflows/ci/harden-npm-publish.ts:20: import { workflow } from '@agent-relay/sdk/workflows';
• build-plans/00-meta-workflow-coordinator.ts:8: import { workflow } from '@agent-relay/sdk/workflows';

Since these files already use import.meta.url (making them ESM), the createRequire workaround is unnecessary — they should use native ESM imports like all other workflow files.

Prompt for agents

Files build-plans/01-sdk-persona-resolution.ts, 02-workflow-generator.ts, 03-cli-agent-flag.ts, 04-tests.ts, and 05-documentation.ts all have the same issue in their first 4 lines. They use createRequire to require() the SDK, but the SDK is ESM-only (packages/sdk/package.json has type: module and no require export condition). Replace the createRequire pattern with a direct ESM import to match the pattern used by all other workflow files in the repo (e.g. workflows/ci/cli-observability.ts and build-plans/00-meta-workflow-coordinator.ts). In each file, replace:

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const { workflow } = require('@agent-relay/sdk/workflows');

with:

import { workflow } from '@agent-relay/sdk/workflows';

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 Spec narrative says "4 intents" fall through to derivation but test code lists 5

The narrative text at line 215 states: "The 13 production intents split into two groups: 9 intents that have a matching persona in the default 10-profile registry, and 4 intents that fall through to derivation." However, the actual test code immediately below (lines 244-261) lists 5 derived intents: implement-frontend, debugging, flake-investigation, opencode-workflow-correctness, and npm-provenance. The count discrepancy arises because code-gen (used by code-worker-v1) is not one of the 13 production intents from the Phase 1 design plan table, yet it is included in the 9 registered-intent tests — making the true split 8+5=13, not 9+4=13. Since this spec is fed to AI agents to generate test code, the conflicting counts could cause the agent to produce incorrect tests.

Suggested change

	The 13 production intents split into two groups: 9 intents that have a matching persona in the default 10-profile registry, and 4 intents that fall through to derivation (no default persona registered).
	The 13 production intents split into two groups: 8 intents that have a matching persona in the default 10-profile registry (plus `code-gen` which has a default persona but is not in the 13-intent design table), and 5 intents that fall through to derivation (no default persona registered).

---

Was this helpful? React with 👍 or 👎 to provide feedback.