shazhou/united-workforce
8
0
Fork 0
Code Issues 8 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Merge pull request 'chore: open-source readiness' (#511) from chore/510-open-source-readiness into main

Browse Source
This commit is contained in:
xiaomo
2026-05-25 10:20:39 +00:00
parent 6e8dedeb2f a11d76264a
commit 813cbfd5c2
15 changed files with 318 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+31
View File
@@ -0,0 +1,31 @@
---
name: Bug Report
about: Report a bug or unexpected behavior
labels: bug
---
## Describe the bug
A clear description of what the bug is.
## To reproduce
Steps or commands to reproduce:
```bash
uwf ...
```
## Expected behavior
What you expected to happen.
## Actual behavior
What actually happened. Include error messages or logs.
## Environment
- OS:
- Bun version:
- uwf version (`uwf --version`):
.github/ISSUE_TEMPLATE/feature_request.md
+17
View File
@@ -0,0 +1,17 @@
---
name: Feature Request
about: Suggest a new feature or improvement
labels: enhancement
---
## What
Describe the feature or improvement.
## Why
Why is this needed? What problem does it solve?
## Proposed solution
How should it work? Include API sketches, CLI examples, or workflow YAML snippets if applicable.
.github/pull_request_template.md
+15
View File
@@ -0,0 +1,15 @@
## What
What this PR does.
## Why
Why the change is needed.
## Changes
- `path/to/file` — what changed and why
## Ref
Fixes #
CONTRIBUTING.md
+110
View File
@@ -0,0 +1,110 @@
# Contributing to @uncaged/workflow
Thank you for your interest in contributing! This guide covers setup, conventions, and the PR workflow.
## Prerequisites
- [Bun](https://bun.sh/) (latest)
- [Node.js](https://nodejs.org/) 20+
- Git
## Setup
```bash
git clone https://github.com/shazhou-ww/uncaged-workflow.git
cd uncaged-workflow
bun install
bun run build
bun test
```
## Development Workflow
```bash
bun run build # TypeScript compilation (all packages)
bun run check # tsc + biome lint + log tag validation
bun run format # Auto-format with Biome
bun test # Run all tests
```
All three (`build`, `check`, `test`) must pass before submitting a PR. A pre-push hook runs `check` + `test` automatically.
## Coding Conventions
See [CLAUDE.md](CLAUDE.md) for the full coding standard. Key points:
- **Functional-first** — `function` + `type`, not `class` + `interface`
- **No optional properties** — use `T | null` instead of `?:`
- **Named exports only** — no default exports
- **No `console.log`** — use the structured logger from `@uncaged/workflow-util`
- **Static imports only** — no `await import()` in production code
- **Biome** for lint + format — run `bun run check` before committing
## Commit Messages
```
<type>(<scope>): <description>
type: feat | fix | refactor | docs | chore | test
scope: cli | moderator | agent-kit | hermes | builtin | claude-code | util | protocol | dashboard
```
Examples:
- `feat(moderator): add cycle detection to graph evaluator`
- `fix(cli): handle missing config file gracefully`
- `docs(protocol): update StepNode field descriptions`
## Pull Request Process
1. **Branch** from `main`: `git checkout -b feat/123-short-description`
2. **Implement** your change with tests
3. **Run checks**: `bun run check && bun test`
4. **Commit** with a descriptive message referencing the issue: `Fixes #123`
5. **Push** and open a PR
### PR Description Template
```
## What
What this PR does.
## Why
Why the change is needed.
## Changes
- `path/to/file.ts` — what changed and why
## Ref
Fixes #N
```
## Adding a Changeset
For any user-facing change (feat, fix, breaking change), add a changeset:
```bash
bun changeset
```
This creates a markdown file in `.changeset/` describing the change. It will be consumed on the next release to bump versions and generate CHANGELOG entries.
## Project Structure
```
packages/
workflow-protocol/ # Shared types and JSON Schema
workflow-util/ # Encoding, IDs, logging, frontmatter
workflow-moderator/ # Status-based graph evaluator
workflow-agent-kit/ # createAgent factory, extract pipeline
workflow-agent-hermes/ # Hermes ACP agent
workflow-agent-builtin/ # Built-in LLM agent
workflow-agent-claude-code/ # Claude Code agent
cli-workflow/ # uwf CLI binary
workflow-dashboard/ # Web UI (private, alpha)
```
Dependency flows downward — lower layers have no dependency on higher layers. See [CLAUDE.md](CLAUDE.md) for the full architecture.
## License
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Uncaged
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+26 -18
View File
@@ -15,6 +15,32 @@ Workflow state lives entirely on disk under `~/.uncaged/workflow/`: CAS nodes fo
Agents are pluggable CLI binaries (`uwf-hermes`, `uwf-builtin`, `uwf-claude-code`, or custom commands). The engine spawns the configured agent with `<thread-id>` and `<role>`, sets `UWF_EDGE_PROMPT` from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay.
## Install
```bash
npm install -g @uncaged/cli-workflow
```
Requires [Bun](https://bun.sh/) runtime (used internally for TypeScript execution).
## Quick Start
```bash
# 1. Configure provider, model, and default agent
uwf setup
# 2. Register a workflow from YAML
uwf workflow add examples/solve-issue.yaml
# 3. Start a thread (creates head pointer; does not execute)
uwf thread start solve-issue -p "Fix the login redirect bug"
# 4. Execute steps (one at a time, until done)
uwf thread exec <thread-id>
```
Use `-c, --count <number>` on `thread exec` to run multiple steps in one invocation. Override the agent with `--agent <cmd>`.
## Architecture
Dependency layers (lower layers have no dependency on higher layers):
@@ -60,24 +86,6 @@ See [docs/architecture.md](docs/architecture.md) for the full design — three-p
| `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) |
| `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) |
## Quick Start
```bash
# 1. Configure provider, model, and default agent
uwf setup
# 2. Register a workflow from YAML
uwf workflow add examples/solve-issue.yaml
# 3. Start a thread (creates head pointer; does not execute)
uwf thread start solve-issue -p "Fix the login redirect bug"
# 4. Execute steps (one at a time, until done)
uwf thread exec <thread-id>
```
Use `-c, --count <number>` on `thread exec` to run multiple steps in one invocation. Override the agent with `--agent <cmd>`.
## CLI Reference
Global options: `-V, --version`, `--format <json|yaml>`, `-h, --help`.
package.json
+10 -1
View File
@@ -23,5 +23,14 @@
"@types/xxhashjs": "^0.2.4",
"@uncaged/workflow-agent-hermes": "workspace:*",
"bun-types": "^1.3.13"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/cli-workflow/package.json
+11 -1
View File
@@ -29,5 +29,15 @@
},
"devDependencies": {
"vitest": "^4.1.6"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/cli-workflow"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-agent-builtin/package.json
+11 -1
View File
@@ -30,5 +30,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-agent-builtin"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-agent-claude-code/package.json
+11 -1
View File
@@ -30,5 +30,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-agent-claude-code"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-agent-hermes/package.json
+11 -1
View File
@@ -31,5 +31,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-agent-hermes"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-agent-kit/package.json
+11 -1
View File
@@ -30,5 +30,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-agent-kit"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-moderator/package.json
+11 -1
View File
@@ -27,5 +27,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-moderator"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-protocol/package.json
+11 -1
View File
@@ -23,5 +23,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-protocol"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}
packages/workflow-util/package.json
+11 -1
View File
@@ -20,5 +20,15 @@
},
"publishConfig": {
"access": "public"
}
},
"repository": {
"type": "git",
"url": "https://github.com/shazhou-ww/uncaged-workflow.git",
"directory": "packages/workflow-util"
},
"homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
"bugs": {
"url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
},
"license": "MIT"
}