refactor: align package folder names with npm package names

Rename packages/ subdirectories to match their @united-workforce/* scope: cli-workflow → cli workflow-agent-builtin → agent-builtin workflow-agent-claude-code → agent-claude-code workflow-agent-hermes → agent-hermes workflow-dashboard → dashboard workflow-protocol → protocol workflow-util-agent → util-agent workflow-util → util Updated all tsconfig references, scripts, and active docs. Historical docs (docs/plans/, docs/superpowers/) left as-is. Closes #21
2026-06-02 23:45:45 +08:00
parent e4e4288d00
commit 5970456a54
266 changed files with 207 additions and 207 deletions
@@ -0,0 +1,186 @@
+# @united-workforce/protocol
+
+Shared TypeScript types and JSON Schema constants for the workflow engine.
+
+## Overview
+
+This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@ocas/core`.
+
+**Dependencies:** `@ocas/core`, `@ocas/fs`
+
+## Installation
+
+```bash
+bun add @united-workforce/protocol
+```
+
+## API
+
+All exports come from `src/index.ts`.
+
+### JSON Schema constants
+
+```typescript
+START_NODE_SCHEMA: JSONSchema
+STEP_NODE_SCHEMA: JSONSchema
+WORKFLOW_SCHEMA: JSONSchema
+```
+
+### Core identifiers
+
+```typescript
+type CasRef = string      // XXH64 hash, 13-char Crockford Base32
+type ThreadId = string    // ULID, 26-char Crockford Base32
+type WorkflowName = string
+type RoleName = string
+```
+
+### Workflow definition
+
+```typescript
+type RoleDefinition = {
+  description: string;
+  goal: string;
+  capabilities: string[];
+  procedure: string;
+  output: string;
+  frontmatter: CasRef;
+};
+
+type Target = {
+  role: string;
+  prompt: string;
+};
+
+type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;
+  graph: Record<string, Record<string, Target>>;
+};
+```
+
+### Thread nodes
+
+```typescript
+type StepRecord = {
+  role: string;
+  output: CasRef;
+  detail: CasRef;
+  agent: string;
+  edgePrompt: string;
+};
+
+type StartNodePayload = {
+  workflow: CasRef;
+  prompt: string;
+};
+
+type StepNodePayload = StepRecord & {
+  start: CasRef;
+  prev: CasRef | null;
+};
+```
+
+### Moderator context
+
+```typescript
+type StepContext = Omit<StepRecord, "output"> & { output: unknown; content: string | null };
+
+type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];
+};
+```
+
+### Configuration
+
+```typescript
+type ProviderAlias = string;
+type ModelAlias = string;
+type AgentAlias = string;
+
+type ProviderConfig = { baseUrl: string; apiKey: string };
+type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;
+};
+
+type AgentConfig = {
+  command: string;
+  args: string[];
+};
+
+type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+```
+
+### CLI output types
+
+```typescript
+type StartOutput = { workflow: CasRef; thread: ThreadId };
+
+type StepOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+  head: CasRef;
+  done: boolean;
+};
+
+type StepEntry = {
+  hash: CasRef;
+  role: string;
+  output: unknown;
+  detail: CasRef;
+  agent: string;
+  timestamp: number;
+};
+
+type StartEntry = {
+  hash: CasRef;
+  workflow: CasRef;
+  prompt: string;
+  timestamp: number;
+};
+
+type ThreadStepsOutput = {
+  thread: ThreadId;
+  workflow: CasRef;
+  steps: [StartEntry, ...StepEntry[]];
+};
+
+type ThreadForkOutput = {
+  thread: ThreadId;
+  forkedFrom: { step: CasRef };
+};
+
+type ThreadListItem = {
+  thread: ThreadId;
+  workflow: CasRef;
+  head: CasRef;
+};
+
+type ThreadsIndex = Record<ThreadId, CasRef>;
+
+type Scenario = string;
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts      Public re-exports
+├── types.ts      All type definitions
+└── schemas.ts    START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA
+```
+
+## Configuration
+
+This package defines `WorkflowConfig` types only. Runtime config loading lives in `@united-workforce/util-agent` (`loadWorkflowConfig`).