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

docs: update architecture docs and package READMEs for post-split structure #153

New Issue
Closed
opened 2026-05-09 04:35:57 +00:00 by xiaoju · 0 comments
xiaoju commented 2026-05-09 04:35:57 +00:00
Owner
Copy Link
Copy Source

Background

The monolith @uncaged/workflow has been split into 15 packages, but documentation still reflects the old 2-package / 8-package structure. Need a comprehensive update.

Scope

1. docs/architecture.md — Full Rewrite

Must cover:

  • Package Map — all 15 packages, one-liner description each, organized by layer
  • Dependency Graph — bottom-up layering diagram (protocol → util/runtime/reactor → cas/register → execute → cli)
  • Package Roles:
    • protocol — pure types, zero deps, the contract layer
    • runtime — workflow author API surface (createWorkflow, types re-export)
    • util — shared utilities (Base32, ULID, logger, refs)
    • cas — content-addressable storage + Merkle
    • register — bundle validation, registry YAML, config/model resolution
    • execute — engine: thread execution, fork, GC, extract
    • reactor — LLM function calling / thread reactor
    • cli-workflow — CLI entry point
    • workflow-agent-* — agent adapters (hermes, cursor, llm)
    • workflow-util-agent — shared agent prompt builder + spawnCli
    • workflow-template-* — workflow templates (solve-issue, develop)
    • workflow-dashboard — React web dashboard
  • Three-Phase Engine Loop — keep existing content, update file paths
  • Bundle Contract — keep, update references
  • Storage Layout — keep, update if changed
  • Design Decisions — update package split rationale

2. CLAUDE.md — Update Monorepo Structure Section

  • Replace the old 2-package structure with current 15-package layout
  • Update the packages/ tree view
  • Keep all coding conventions as-is (they are still correct)

3. Missing Package READMEs (7 packages)

Create README.md for: workflow-protocol, workflow-reactor, workflow-register, workflow-runtime, workflow-util, workflow-cas, workflow-execute.

Each README should follow this template:

# @uncaged/<name>

One-line description.

## What This Package Does

2-3 sentences explaining the role in the system.

## Key Exports

Bullet list of main exports (read from src/index.ts).

## Dependencies

Which workspace packages this depends on and why.

## Usage

Short code example if applicable.

4. Fix Existing READMEs (3 packages)

workflow-agent-llm, workflow-agent-cursor, workflow-agent-hermes — update dependency references from @uncaged/workflow to actual current deps.

5. docs/plans/2025-05-07-workflow-as-agent.md

Add a note at the top: > ⚠️ This plan references the pre-split package structure. File paths have changed.

Approach

  • Read every packages/*/package.json and packages/*/src/index.ts to get accurate info
  • Do NOT invent — only document what actually exists in code
  • Keep language concise and technical

Ref

小橘 🍊（NEKO Team）

## Background The monolith `@uncaged/workflow` has been split into 15 packages, but documentation still reflects the old 2-package / 8-package structure. Need a comprehensive update. ## Scope ### 1. `docs/architecture.md` — Full Rewrite Must cover: - **Package Map** — all 15 packages, one-liner description each, organized by layer - **Dependency Graph** — bottom-up layering diagram (protocol → util/runtime/reactor → cas/register → execute → cli) - **Package Roles**: - `protocol` — pure types, zero deps, the contract layer - `runtime` — workflow author API surface (`createWorkflow`, types re-export) - `util` — shared utilities (Base32, ULID, logger, refs) - `cas` — content-addressable storage + Merkle - `register` — bundle validation, registry YAML, config/model resolution - `execute` — engine: thread execution, fork, GC, extract - `reactor` — LLM function calling / thread reactor - `cli-workflow` — CLI entry point - `workflow-agent-*` — agent adapters (hermes, cursor, llm) - `workflow-util-agent` — shared agent prompt builder + spawnCli - `workflow-template-*` — workflow templates (solve-issue, develop) - `workflow-dashboard` — React web dashboard - **Three-Phase Engine Loop** — keep existing content, update file paths - **Bundle Contract** — keep, update references - **Storage Layout** — keep, update if changed - **Design Decisions** — update package split rationale ### 2. `CLAUDE.md` — Update Monorepo Structure Section - Replace the old 2-package structure with current 15-package layout - Update the `packages/` tree view - Keep all coding conventions as-is (they are still correct) ### 3. Missing Package READMEs (7 packages) Create `README.md` for: `workflow-protocol`, `workflow-reactor`, `workflow-register`, `workflow-runtime`, `workflow-util`, `workflow-cas`, `workflow-execute`. Each README should follow this template: ``` # @uncaged/<name> One-line description. ## What This Package Does 2-3 sentences explaining the role in the system. ## Key Exports Bullet list of main exports (read from src/index.ts). ## Dependencies Which workspace packages this depends on and why. ## Usage Short code example if applicable. ``` ### 4. Fix Existing READMEs (3 packages) `workflow-agent-llm`, `workflow-agent-cursor`, `workflow-agent-hermes` — update dependency references from `@uncaged/workflow` to actual current deps. ### 5. `docs/plans/2025-05-07-workflow-as-agent.md` Add a note at the top: `> ⚠️ This plan references the pre-split package structure. File paths have changed.` ## Approach - Read every `packages/*/package.json` and `packages/*/src/index.ts` to get accurate info - Do NOT invent — only document what actually exists in code - Keep language concise and technical ## Ref 小橘 🍊（NEKO Team）
Sign in to join this conversation.
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
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#153
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?