@tianhai/pi-workflow-kit 2.0.0 → 2.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -52,7 +52,7 @@ The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the b
|
|
|
52
52
|
## Process
|
|
53
53
|
|
|
54
54
|
1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
|
|
55
|
-
2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* —
|
|
55
|
+
2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md` and `overview.md` (each umbrella lives in its own `docs/plans/<date>-<umbrella>/` folder — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `overview.md` means the split is already decided — read it for the roster and design this part's `-design.md` against it (see [Umbrella](#umbrella)).
|
|
56
56
|
3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions in **frontier rounds**: build a question tree seeded by the dimension checklist, then ask in rounds. The **frontier** is every question whose prerequisites are already settled — ask the whole frontier in one round; a question whose answer depends on another still-open question waits for a later round. Number each question (`Q1`, `Q2`, …) and attach your recommended answer (`➡️ <recommendation>`) — the recommendation is your assumption surfaced up front; the human confirms, strikes, or corrects each in one reply. Recompute the frontier after each round of answers. Seed the tree by walking every checklist dimension — *Goal & scope · Data & state · Behavior & edge cases · Errors & failure · Integration · Non-functional* — printing `— nothing to ask` for groups with no questions (never skip silently). **Facts vs. decisions**: anything answerable from the codebase, docs, or tools is looked up — recon scout or inline — never asked of the human; a pending lookup is an unsettled prerequisite that holds only its downstream questions, while the rest of the frontier is asked now. Only decisions are asked. Major approvals stay single-decision — one question each, never batched: approach selection (step 5), umbrella split, design approval, ADR unlock. The interview ends when the frontier is empty — every branch visited, nothing left silently assumed — not when you feel you understand. Then present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
|
|
57
57
|
4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, request the host’s `codebase-recon` capability using the logical `pwk-recon-scout` role. Require a fresh-context, read-only, bounded worker and pass the topic, one-line intent, and repo root. Use the returned 5-section codebase map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as the grounding context for the next two steps instead of reading those files inline. The scout is observations only — no design recommendations. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If no compatible capability is available or the provider cannot enforce the requested constraints, report `Scout: unavailable` and do the same recon inline, preserving the five-section map and `file:line` citations; do not silently omit recon.
|
|
58
58
|
5. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
|
|
@@ -14,7 +14,7 @@ The feature-acceptance E2E test is the primary enforced gate and the primary enf
|
|
|
14
14
|
## Before you start
|
|
15
15
|
|
|
16
16
|
1. **Git state** — `git status` + `git log --oneline -5`; note uncommitted changes.
|
|
17
|
-
2. **Find the doc** —
|
|
17
|
+
2. **Find the doc** — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md` and `*-implementation.md` (umbrella docs live in `docs/plans/<date>-<umbrella>/` folders — archived work is not pending). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`. A stem-matched legacy `*-implementation.md` wins for that topic (an in-flight 1.x feature — old flow). If no doc at all, ask the user to run `/skill:pwk-brainstorming` first; if several, ask which. Report one line, e.g. `Found: design "auth" — feature-gate execute (feature-spec done, implementing 2/5)`. A matching `*-progress.md` means this is a **resume** (see [Resume](#resume)).
|
|
18
18
|
3. **Workspace — create the feature branch** — if you're already on a feature branch (not `main`), **reuse** it: a later umbrella part continues on the same umbrella branch. If on `main`, `git checkout -b <topic>` — the umbrella's `<topic>` if this design doc is one of an overview's parts, else the design doc's `<topic>`. For larger work, offer a worktree (`git worktree add ../<repo>-<topic> <topic>`) and hand off to a new session there so `pwd` is the worktree. Wait for the user's choice.
|
|
19
19
|
|
|
20
20
|
## First run
|
|
@@ -62,7 +62,7 @@ The feature-acceptance E2E test is the primary enforced gate and the primary enf
|
|
|
62
62
|
|
|
63
63
|
## Resume
|
|
64
64
|
|
|
65
|
-
Read the progress file's `Feature phase
|
|
65
|
+
Read the progress file's `Feature phase` (match the line — e.g. `grep -m1 '^Feature phase:' <file>`), the Requirements table (the first row whose Done cell is not `✅` routes the next requirement — `⬜`, `🔄`, and blank all mean not-done), and the Execution summary rows (how prior parts were built); read from the top through the end of `## Execution summary` and stop — the sections after it (deviation-records, review reports, code digest) carry nothing the resume needs:
|
|
66
66
|
- `e2e-written` → write the E2E if not yet present, then present the **feature-spec** checkpoint.
|
|
67
67
|
- `feature-spec-paused` → re-present the feature-spec checkpoint and wait.
|
|
68
68
|
- `implementing (k/N)` → continue the next not-yet-✅ requirement.
|
|
@@ -10,7 +10,8 @@ Ship the completed work.
|
|
|
10
10
|
## Pre-finalization checks
|
|
11
11
|
|
|
12
12
|
1. **Run the FULL test suite** — every test must pass, and only a green suite ships. Resume spans sessions; re-run the suite yourself rather than trust the previous session's ending state. Anything failing → send the user back to `/skill:pwk-executing-tasks`.
|
|
13
|
-
2.
|
|
13
|
+
2. **Verify the repo root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then:
|
|
14
|
+
3. Read **every** relevant progress file — for an umbrella that's each part's progress file — discovered by listing `docs/plans` recursively for `*-progress.md`, excluding docs/plans/completed/ (umbrella docs live in `docs/plans/<date>-<umbrella>/` folders — archived parts are already shipped). Use whatever recurses in your harness; one example: `find docs/plans -name '*-progress.md' -not -path '*/completed/*'`. Match the `Feature phase:` line (e.g. `grep -m1 '^Feature phase:' <file>`) and read only the matching ❌/⏭ verdict rows in the Requirements table (e.g. `grep '❌' <file>` / `grep '⏭' <file>` — rows with reasons); the sections after the tables carry nothing the gate needs. For a standalone design doc, the one:
|
|
14
15
|
- **Any `❌ failed`** (in any part) → **block**. Present counts and reasons; continue only when the user sends the task back to executing-tasks, or explicitly types `--force-failed` to acknowledge shipping with incomplete requirements.
|
|
15
16
|
- **Only `⏭ skipped`** → warn and confirm ("Requirement N was skipped. Continue, or go back?").
|
|
16
17
|
- **`Feature phase` must be `done`** in every progress file — any other value (`e2e-written`, `feature-spec-paused`, `implementing (k/N)`, `reviewing`, `ship-paused`, or a legacy `feature-complete-paused` from before the ship gate) means the feature is still in flight: the ship checkpoint has not been approved. Send the user back to `/skill:pwk-executing-tasks` instead of finalizing.
|
|
@@ -9,17 +9,29 @@ Report on in-flight pipelines in this working tree (a worktree has its own `docs
|
|
|
9
9
|
|
|
10
10
|
## Process
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
0. **Verify the root** — run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; if they differ, report both paths and stop — tell the user to restart the session at the repo root; never `cd` (a worktree root counts).
|
|
13
|
+
1. **Discover** — List `docs/plans` recursively, excluding docs/plans/completed/, one list per suffix: `*-design.md`, `*-implementation.md` (legacy — a 2.0 feature has no implementation doc; discovery covers both suffixes), `*-progress.md`, `overview.md` (umbrella docs live in `docs/plans/<date>-<umbrella>/` folders — archived topics are not in flight) — this working tree only. Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`.
|
|
14
|
+
2. **State per topic/part — extract, never ingest.** For each progress file take the `Feature phase:` line by matching it (e.g. `grep -m1 '^Feature phase:' <file>` — wherever the template puts it); the body (execution summary, review reports, code digest) carries nothing status needs, and neither do design docs. Map the line to the displayed state:
|
|
15
|
+
- `done` → **`done`** — terminal, never shown as in-flight; append the tally as `N/N` when wanted — the Requirements-table row count (e.g. `grep -c '^| [0-9]' <file>`); at `done` every row is complete
|
|
16
|
+
- `implementing (k/N)` → `execute k/N` (the tally rides on the line itself — no extra read)
|
|
17
|
+
- `e2e-written`, `feature-spec-paused` → `feature-spec`
|
|
18
|
+
- `reviewing`, legacy `feature-complete-paused` → `review`
|
|
19
|
+
- `ship-paused` → `ship-paused`
|
|
20
|
+
- no progress file, only `*-design.md` → `design` — next: `/skill:pwk-executing-tasks`
|
|
21
|
+
- roster-only (named in the overview, no artifacts) → `not started`
|
|
22
|
+
- no parseable `Feature phase` line → `execute` (with tally if parseable).
|
|
23
|
+
|
|
24
|
+
A legacy 1.x topic (`*-implementation.md` stem-matched) uses the same phase-line inference on its progress file.
|
|
25
|
+
3. **Group by umbrella** — for each umbrella `overview.md` (read it — it is status-free and tiny), take its **parts** roster and roll the parts up by state (the overview carries no status): done parts, in-flight parts (design, execute, feature-spec, review, ship-paused), not-started parts. Print one roll-up line — `<umbrella> (umbrella): n done · n in-flight · n not-started` — and when every part is `done` append `— all parts done, ready for /skill:pwk-finalizing`. A `done` standalone topic gets the same hint. Once the umbrella finalizes, its folder — overview included — is disposed, so it no longer appears here. Topics not part of an overview print flat.
|
|
15
26
|
4. Print a compact table, grouped under any umbrellas, e.g.:
|
|
16
27
|
|
|
17
|
-
```
|
|
18
|
-
payments-revamp (umbrella): 2 in-flight · 1 not-started
|
|
19
|
-
payments-core
|
|
20
|
-
payments-ui
|
|
28
|
+
```text
|
|
29
|
+
payments-revamp (umbrella): 1 done · 2 in-flight · 1 not-started
|
|
30
|
+
payments-core done 3/3
|
|
31
|
+
payments-ui execute 1/2
|
|
32
|
+
payments-review review —
|
|
21
33
|
payments-webhooks not started
|
|
22
|
-
auth
|
|
34
|
+
auth ship-paused — ready for /skill:pwk-finalizing
|
|
23
35
|
```
|
|
24
36
|
|
|
25
37
|
If nothing, suggest `/skill:pwk-brainstorming`.
|