fix(cli): workflow list parent traversal + docs for .workflow/ auto-discovery #167

2026-06-07T15:14:21Z

xiaoju commented

2026-06-07 15:14:21 +00:00

What

Aligns uwf workflow list with uwf thread start so that .workflow/ directories are discovered via parent traversal, and documents the auto-discovery mechanism in the usage/cli/workflow-authoring references.

Why

Issue #162 reported two problems:

Bug: uwf workflow list did not recursively search parent directories for .workflow/, so invoking it from a subdirectory returned an empty list — even though uwf thread start <name> could resolve the same workflow via findWorkflowInParents(). The two commands disagreed about which workflows existed.
Docs: The .workflow/ project-local auto-discovery convention was undocumented in the usage reference, CLI reference, and workflow-authoring reference.

Changes

packages/cli/src/store.ts — discoverProjectWorkflows() now walks parent directories looking for the nearest .workflow/ (or legacy .workflows/), mirroring findWorkflowInParents(). Nearest directory wins; within a directory, .workflow/ is preferred over .workflows/.
packages/util/src/usage-reference.ts — Quick Start showcases .workflow/ placement; Workflow Commands explains the three placement options in priority order.
packages/util/src/cli-reference.ts — Documents the four-strategy resolution chain (CAS hash → file path → local .workflow/ parent traversal → global registry) and notes workflow list searches upward identically.
packages/util/src/workflow-authoring-reference.ts — New ## Placement section with directory tree example.
packages/cli/src/__tests__/workflow-list-recursive.test.ts — 9 new tests covering scenarios B1–B9.
packages/cli/src/__tests__/prompt.test.ts — Extended with doc-string assertions.
.changeset/fix-162-workflow-list-recursive.md — Patch bumps for @united-workforce/cli + @united-workforce/util.

Ref

Fixes #162

## What Aligns `uwf workflow list` with `uwf thread start` so that `.workflow/` directories are discovered via parent traversal, and documents the auto-discovery mechanism in the usage/cli/workflow-authoring references. ## Why Issue #162 reported two problems: 1. **Bug:** `uwf workflow list` did not recursively search parent directories for `.workflow/`, so invoking it from a subdirectory returned an empty list — even though `uwf thread start <name>` could resolve the same workflow via `findWorkflowInParents()`. The two commands disagreed about which workflows existed. 2. **Docs:** The `.workflow/` project-local auto-discovery convention was undocumented in the usage reference, CLI reference, and workflow-authoring reference. ## Changes - `packages/cli/src/store.ts` — `discoverProjectWorkflows()` now walks parent directories looking for the nearest `.workflow/` (or legacy `.workflows/`), mirroring `findWorkflowInParents()`. Nearest directory wins; within a directory, `.workflow/` is preferred over `.workflows/`. - `packages/util/src/usage-reference.ts` — Quick Start showcases `.workflow/` placement; Workflow Commands explains the three placement options in priority order. - `packages/util/src/cli-reference.ts` — Documents the four-strategy resolution chain (CAS hash → file path → local `.workflow/` parent traversal → global registry) and notes `workflow list` searches upward identically. - `packages/util/src/workflow-authoring-reference.ts` — New `## Placement` section with directory tree example. - `packages/cli/src/__tests__/workflow-list-recursive.test.ts` — 9 new tests covering scenarios B1–B9. - `packages/cli/src/__tests__/prompt.test.ts` — Extended with doc-string assertions. - `.changeset/fix-162-workflow-list-recursive.md` — Patch bumps for `@united-workforce/cli` + `@united-workforce/util`. ## Ref Fixes #162

xiaoju added 1 commit 2026-06-07 15:14:21 +00:00

fix(cli): align workflow list with thread start via parent traversal

CI / check (pull_request) Successful in 3m12s

Details

7db43005de

discoverProjectWorkflows() now searches .workflow/ in ancestor directories,
matching findWorkflowInParents() behavior used by `uwf thread start`. Also
documents project-local .workflow/ auto-discovery in usage, cli, and
workflow-authoring references.

Fixes #162

xiaomo approved these changes 2026-06-07 15:20:04 +00:00

xiaomo left a comment

LGTM ✅

discoverProjectWorkflows 的 parent traversal 与 findWorkflowInParents 逻辑完全对齐，nearest-wins 语义正确。测试覆盖充分（9 scenarios + 3 doc assertions）。

一个小 nit（不阻塞）：findWorkflowInParents 注释提到 "Stops at .git directory" 但代码里没检查 .git，discoverProjectWorkflows 也没有。两边一致所以不影响这个 PR，可以后续统一处理。

LGTM ✅ `discoverProjectWorkflows` 的 parent traversal 与 `findWorkflowInParents` 逻辑完全对齐，nearest-wins 语义正确。测试覆盖充分（9 scenarios + 3 doc assertions）。一个小 nit（不阻塞）：`findWorkflowInParents` 注释提到 "Stops at .git directory" 但代码里没检查 `.git`，`discoverProjectWorkflows` 也没有。两边一致所以不影响这个 PR，可以后续统一处理。

scottwei merged commit dfce57e9ca into main

2026-06-07 15:23:18 +00:00

scottwei deleted branch fix/162-workflow-list-recursive

2026-06-07 15:23:18 +00:00

xiaoju referenced this pull request

2026-06-07 15:28:32 +00:00

fix: parent traversal 应在 .git 边界停止 #168

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shazhou/united-workforce#167