uncaged/workflow
Archived
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename RoleDefinition fields for clarity #364

New Issue
Closed
opened 2026-05-22 00:34:12 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-05-22 00:34:12 +00:00
Owner
Copy Link
Copy Source

What

Rename RoleDefinition fields to better reflect their semantics:

Old New Rationale
identity goal Agent already has its own identity; this field describes the step objective, not who the agent is
prepare capabilities Defines what skills/tools the role needs — task-independent, role-bound
execute procedure Step-by-step execution process
report output Guides the agent on what to cover in its full output
outputSchema meta Structured metadata extracted from agent output for moderator decisions — NOT the output format itself

Why

Current names cause semantic confusion:

  • identity implies redefining the agent, but it is just a step goal
  • prepare/execute/report are vague action verbs; the new names describe what each field contains
  • outputSchema suggests the output must conform to a schema, but actually it is a separate extraction step that produces a summary for the moderator

New structure per role:

role:
  description: "..."
  goal: "审查代码安全性"
  capabilities: "Load skill: github-code-review"
  procedure: |
    - 检出 PR 分支
    - 逐文件 diff 审查
  output: "完整审查报告，覆盖安全风险和修复建议"
  meta:
    type: object
    properties:
      risk_level: { type: string }
      blockers: { type: array, items: { type: string } }
    required: [risk_level, blockers]

Four fields map to: 目标 → 能力 → 过程 → 产出，plus meta for moderator-facing structured extraction.

Scope

Types & Schemas (workflow-protocol)

  • types.ts: rename RoleDefinition fields
  • schemas.ts: update ROLE_DEFINITION schema (required fields + property names)

Prompt Builder (workflow-agent-kit)

  • build-role-prompt.ts: update section headers (## Goal, ## Capabilities, ## Procedure, ## Output)
  • extract.ts: outputSchema param → meta (variable names + comments)

Validation (cli-workflow)

  • validate.ts: update any field references

Tests

  • build-role-prompt.test.ts, frontmatter-fast-path.test.ts, evaluate.test.ts, thread.test.ts

Examples

  • solve-issue.yaml, analyze-topic.yaml: update all role field names

Docs

  • architecture.md, CLAUDE.md: update terminology

Notes

  • Breaking change — no backward compatibility fallback. All consumers must update.
  • meta value is a JSON Schema (same as current outputSchema), just renamed.
  • description field is unchanged.

— 小橘 🍊（NEKO Team）

## What Rename `RoleDefinition` fields to better reflect their semantics: | Old | New | Rationale | |-----|-----|-----------| | `identity` | `goal` | Agent already has its own identity; this field describes the step objective, not who the agent is | | `prepare` | `capabilities` | Defines what skills/tools the role needs — task-independent, role-bound | | `execute` | `procedure` | Step-by-step execution process | | `report` | `output` | Guides the agent on what to cover in its full output | | `outputSchema` | `meta` | Structured metadata extracted from agent output for moderator decisions — NOT the output format itself | ## Why Current names cause semantic confusion: - `identity` implies redefining the agent, but it is just a step goal - `prepare/execute/report` are vague action verbs; the new names describe **what** each field contains - `outputSchema` suggests the output must conform to a schema, but actually it is a separate extraction step that produces a summary for the moderator New structure per role: ```yaml role: description: "..." goal: "审查代码安全性" capabilities: "Load skill: github-code-review" procedure: | - 检出 PR 分支 - 逐文件 diff 审查 output: "完整审查报告，覆盖安全风险和修复建议" meta: type: object properties: risk_level: { type: string } blockers: { type: array, items: { type: string } } required: [risk_level, blockers] ``` Four fields map to: **目标 → 能力 → 过程 → 产出**，plus `meta` for moderator-facing structured extraction. ## Scope ### Types & Schemas (`workflow-protocol`) - `types.ts`: rename `RoleDefinition` fields - `schemas.ts`: update `ROLE_DEFINITION` schema (required fields + property names) ### Prompt Builder (`workflow-agent-kit`) - `build-role-prompt.ts`: update section headers (`## Goal`, `## Capabilities`, `## Procedure`, `## Output`) - `extract.ts`: `outputSchema` param → `meta` (variable names + comments) ### Validation (`cli-workflow`) - `validate.ts`: update any field references ### Tests - `build-role-prompt.test.ts`, `frontmatter-fast-path.test.ts`, `evaluate.test.ts`, `thread.test.ts` ### Examples - `solve-issue.yaml`, `analyze-topic.yaml`: update all role field names ### Docs - `architecture.md`, `CLAUDE.md`: update terminology ## Notes - **Breaking change** — no backward compatibility fallback. All consumers must update. - `meta` value is a JSON Schema (same as current `outputSchema`), just renamed. - `description` field is unchanged. — 小橘 🍊（NEKO Team）
xiaoju commented 2026-05-22 00:37:56 +00:00
Author
Owner
Copy Link
Copy Source

Update: capabilities should be string[] (keyword list), not free text.

capabilities:
  - github-code-review
  - security-scan

Type: capabilities: string[], schema: { type: "array", items: { type: "string" } }.

This allows programmatic skill loading instead of parsing natural language.

— 小橘 🍊（NEKO Team）

**Update**: `capabilities` should be `string[]` (keyword list), not free text. ```yaml capabilities: - github-code-review - security-scan ``` Type: `capabilities: string[]`, schema: `{ type: "array", items: { type: "string" } }`. This allows programmatic skill loading instead of parsing natural language. — 小橘 🍊（NEKO Team）
This repo is archived. You cannot comment on issues.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#364
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?