@tianhai/pi-workflow-kit 1.3.0 → 1.4.0

package/README.md

@@ -58,7 +58,7 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. A
 
 | Phase | Trigger | What Happens |
 |-------|---------|--------------|
-| **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list |
+| **Brainstorm** | `/skill:pwk-brainstorming` | Explore approaches, produce a design doc with a `## Requirements` list. On non-trivial topics, dispatches the `pwk-recon-scout` agent (read-only) to map the codebase before design. |
 | **Plan** | `/skill:pwk-writing-plans` | Turn each requirement into **acceptance criteria + integration tests** — a behavioral spec (no implementation code) |
 | **Execute** | `/skill:pwk-executing-tasks` | Write the feature E2E (red) → **checkpoint: feature-spec** → implement requirements → **checkpoint: feature-complete** → feature review |
 | **Code review** | `/skill:pwk-code-review` | Feature-level (default) or per-requirement: code tracing, spec alignment, code smells (applies fixes), production hazard check |
@@ -177,7 +177,7 @@ pi-workflow-kit/
 │   ├── pwk-finalizing/SKILL.md
 │   ├── pwk-status/SKILL.md
 │   └── pwk-diagnose/SKILL.md
-├── agents/                   # package agents for parallel code-review (discovered by pi-subagents)
+├── agents/                   # package agents for parallel code-review + recon scout (discovered by pi-subagents)
 ├── docs/
 │   ├── developer-usage-guide.md
 │   ├── workflow-phases.md

package/agents/pwk-recon-scout.md

@@ -0,0 +1,68 @@
+---
+name: pwk-recon-scout
+description: Codebase recon scout — maps how a repo handles a topic before design. Produces a 5-section observation report (no recommendations, no design opinion). Read-only reporter.
+tools: read, grep, find, ls, bash
+systemPromptMode: replace
+---
+
+# PWK Recon Scout
+
+You are a codebase recon scout dispatched by `pwk-brainstorming` before design work. Your job is to map how a repository handles a topic today so the main agent can design against prior art instead of loading the relevant files into its own context.
+
+**You are observations only.** No design recommendations, no preferred-approach opinion, no code beyond one-line excerpts. Every claim must cite a `file:line` so the main agent can drill in if it needs to.
+
+## Tools
+
+You inherit the read-only set the workflow-guard already enforces on the brainstorm session: `read, grep, find, ls, bash`. Do not attempt writes or edits — they will be blocked.
+
+## Inputs
+
+The main agent dispatches you with three things in the task string:
+
+- a `<topic>` (one short phrase, the new feature or change)
+- a one-line `<intent>` (what the new thing does, in plain words)
+- the repo root
+
+If any of these is missing, ask for it before proceeding.
+
+## Output — the 5-section codebase map
+
+Return a single markdown report with these five sections, in this order. Each section is a short bulleted list (5-10 bullets is the sweet spot; fewer is fine, more is a smell that you did not stay narrow).
+
+### Relevant files
+
+Paths that matter for the topic, each with a one-line role. Group by subdirectory if the repo has clear layering; otherwise a flat list is fine.
+
+### Existing patterns
+
+How the codebase does similar work today. Cite the file:line for the pattern. Include 2-4 patterns — the new design will compose with these, so the main agent needs to know what conventions are non-negotiable.
+
+### Call sites
+
+Where the new behavior would plug in, or which existing wiring it would change. Distinguish **read-side call sites** (consumers of the current behavior) from **write-side call sites** (the functions or entry points that would need updating).
+
+### Test layout
+
+Where similar tests live, what harness they use (vitest, jest, go test, etc.), and one or two example test names to mimic. If the codebase has a custom fixture that is painful to build, call it out here so the main agent does not discover it during the planning phase.
+
+### Gotchas
+
+Anything that bit a previous change, in this layer of the code or in the topic area specifically. A migrations folder that must run in order, a feature flag that gates the new path, a known deadlock with another subsystem, an environment variable that has to be set, a CI hook that runs before tests. The point is to surface landmines before the main agent commits to a design.
+
+## Hard rules
+
+- **Cite a file:line per claim.** No assertions without a citation. The main agent treats your report as a map, not a summary.
+- **Observations only.** No `I recommend`, no `the right approach is`, no `consider doing X`. If you have an opinion, surface it as a neutral fact: e.g. `the codebase has three different error formats` is fine; `the codebase should standardize on one` is not.
+- **Stay narrow.** If the topic is `add OAuth2 login`, do not also report on the entire auth subsystem. Cover the call sites and patterns the new feature will actually touch.
+- **Do not paste code blocks longer than five lines.** One-line excerpts are fine for context. Anything longer means the main agent should read the file itself.
+- **Time-box.** If after 10 tool calls the topic has no prior art in the repo, report that and stop. An empty codebase map is a useful signal: the topic is greenfield.
+
+## When you finish
+
+Return the report as your final message. The main agent reads it into its context and uses it as the grounding for the next two brainstorm steps (Explore approaches, Present the design).
+
+## Failure modes
+
+- Subagent tool unavailable: the main agent will fall back to inline recon and you will not be invoked. You do not need to handle this case.
+- You return empty: the main agent will treat it as greenfield and proceed with no-prior-art assumptions. Returning a short, honest report is better than padding it.
+- You return a wrong-shaped report: the main agent will downweight the findings but still proceed. Better to ship the 5-section shape than to improvise.

package/docs/developer-usage-guide.md

@@ -44,7 +44,7 @@ You control each phase by invoking the skill. A design doc is one PR; a requirem
 /skill:pwk-brainstorming
 ```
 
-Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review.
+Explore the idea through collaborative dialogue. The agent reads code, asks questions, proposes approaches, and presents the design for your review. On non-trivial topics with prior art, the agent dispatches the `pwk-recon-scout` package agent (read-only, fresh context) to map the codebase before design, so the main agent can design against prior art instead of loading files into its own context.
 
 Outcome: `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list. For a too-big requirement, may start an **umbrella** (writes a status-free overview + the first part's design doc). ADRs go to `docs/adr/` (permanent).
 
@@ -121,5 +121,5 @@ Plans specify *what* (acceptance criteria + integration tests); the executor wri
 - Start with brainstorming for anything non-trivial.
 - The plan is a behavioral spec, not an implementation recipe — let the executor choose how.
 - The feature-gate flow has two checkpoints by default (feature-spec + feature-complete): use them to steer the E2E spec and the finished implementation.
-- **Right-size each requirement at plan time** with the `### Checkpoints` (`none`/`full`/`spec`, default `none`) and `### Review` (`skip`/`parallel`/`inline`, default `skip`) tags — per-requirement ceremony is opt-in. The always-on feature-level `### Feature review` covers the whole diff. `spec` keeps the cheap spec-correctness gate and drops the complete checkpoint (covered by review), so it requires at least `inline` review. A trivial fix can also use the brainstorming trivial fast-path (one-turn brainstorm, minimal design doc).
+- **Right-size each requirement at plan time** with the `### Checkpoints` (`none`/`full`/`spec`, default `none`) and `### Review` (`skip`/`parallel`/`inline`, default `skip`) tags — per-requirement ceremony is opt-in. The always-on feature-level `### Feature review` covers the whole diff. `spec` keeps the cheap spec-correctness gate and drops the complete checkpoint (covered by review), so it requires at least `inline` review. A trivial fix can also use the brainstorming trivial fast-path (one-turn brainstorm, minimal design doc). Production-risk requirements are auto-tagged `### Review: parallel` by `pwk-writing-plans`; the human can override or downgrade before plan approval.
 - Put all plan artifacts under `docs/plans/`; ADRs under `docs/adr/`.

package/docs/workflow-phases.md

@@ -32,7 +32,7 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 - Reads the design doc's `## Requirements`; for each, derives **acceptance criteria + integration-test cases** (a behavioral spec, no implementation code), lists requirements in build order (dependencies positioned earlier), and challenges the design when `## Production-risk areas` is present.
 - For an umbrella part, reads the `*-overview.md` to plan one slice (composing with earlier parts' code) and reuses the existing feature branch instead of creating a new one.
 - Derives a **`## Feature acceptance` section** in the plan from the design's Feature acceptance — the **primary enforced spec**, an end-to-end test the executor gates on first. If the design has none, stops and asks the human to brainstorm one.
-- Tags the plan: per-requirement `### Checkpoints`/`### Review` default to `none`/`skip` (opt-in), plus an always-on feature-level `### Feature review`. Flags only requirements with complex logic, the main part of the feature, or production-risk.
+- Tags the plan: per-requirement `### Checkpoints`/`### Review` default to `none`/`skip` (opt-in), plus an always-on feature-level `### Feature review`. Flags only requirements with complex logic, the main part of the feature, or production-risk. Requirements with `### Production-risk notes` are auto-tagged `### Review: parallel` (see `pwk-writing-plans` for the rule).
 - Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
 
 Write boundary: only `docs/plans/` is writable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

package/skills/pwk-brainstorming/SKILL.md

@@ -11,7 +11,7 @@ Read-only exploration of source code; every file you create or edit goes under `
 
 Classify the change at the start.
 
-- **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–5; write a **minimal** design doc in one turn (one-line context, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
+- **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–7; write a **minimal** design doc in one turn (one-line context, a `## Requirements` list with the single requirement, optional `## Production-risk areas` line), and hand off to `/skill:pwk-writing-plans`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
 - **Non-trivial** — open design questions, multiple approaches, cross-module impact, or new behavior. Run the full process below.
 
 When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Default to full.
@@ -54,11 +54,12 @@ The whole umbrella is one branch and one PR: `pwk-writing-plans` creates the bra
 1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
 2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — glob `docs/plans/*-design.md` and `*-overview.md`; 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)).
 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 one at a time, prefer multiple choice. Once you can articulate what/why/constraints, present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
-4. **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.
-5. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
+4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, dispatch the `pwk-recon-scout` package agent (a fresh-context, read-only worker) with the topic, a one-line intent, and the 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 — and stays within the read-only tool set the guard already enforces. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If the `subagent` tool is unavailable (e.g. `pi-subagents` is not installed), skip the dispatch, do the recon inline as today, and append the literal line `Scout: unavailable (pi-subagents not installed) — inline recon used.` to the design doc at step 7.
+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.
+6. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
 
    Identified a significant architectural decision? Offer an ADR in `docs/adr/`. Only when all three hold: **hard to reverse**, **surprising without context**, **a real trade-off**. Format: title + 1–3 sentences of context/decision/why. ADRs are permanent institutional memory — they stay out of archive/rotation forever. (Guard note: `docs/adr/` is outside the writable `docs/plans/`; write it only after the user approves and unlocks.)
-6. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **Open with `## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
+7. **Write the design doc** — `docs/plans/YYYY-MM-DD-<topic>-design.md`, descriptive (not a task list). **Open with `## Requirements`** — one testable behavior each; `pwk-writing-plans` derives acceptance criteria and tests from these. Then: problem, approaches considered, architecture, components, data flow, error handling, testing.
 
    Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` — `pwk-writing-plans` carries it into the plan and `pwk-code-review` audits it per requirement.
 

package/skills/pwk-executing-tasks/SKILL.md

@@ -120,7 +120,7 @@ On success, set `Feature phase: done`.
 The plan tags each requirement and the feature level:
 
 - **`### Checkpoints: none | full | spec`** — per-requirement human stops. `none` (default) = no per-requirement stop; `full` = tests + complete; `spec` = tests only.
-- **`### Review: skip | parallel | inline`** — per-requirement review. `skip` (default) = none; `parallel` = four reviewers; `inline` = one `pwk-code-review` pass.
+- **`### Review: skip | parallel | inline`** — per-requirement review. `skip` (default) = none; `parallel` = four reviewers; `inline` = one `pwk-code-review` pass. The auto-tag default for requirements with non-empty `### Production-risk notes` is `parallel` (see `pwk-writing-plans` for the rule).
 - **`### Feature review: parallel | inline`** — the one whole-feature review (always present). Default `parallel`; `inline` for small features.
 
 ## User override commands

package/skills/pwk-writing-plans/SKILL.md

@@ -23,10 +23,11 @@ Your writes go into `docs/plans/` and nowhere else. Source code and configuratio
    - **Integration tests** — test name + what each asserts. This is the spec the executor writes tests from.
    - **Meaningful tests** — write acceptance criteria and tests as observable behavior: (1) **Test observable behavior** — assert on what the feature produces or changes (a return value, persisted/updated data, an emitted event, an HTTP response) through its public interface; these assertions keep passing as the implementation changes. (2) **Write a per-slice test when the slice has its own observable behavior** — when a slice is pure config or a trivial extraction, the feature E2E covers it and a per-slice test is unnecessary.
    - **`### Checkpoints: none | full | spec`** — how many human stops. `none` = no per-requirement stop (default — the feature gate covers it); `full` = tests + complete stops; `spec` = tests stop only. Flag a requirement `full` or `spec` when it contains complex logic or is the main part of the feature — where a human look at the slice is worth the stop.
-   - **`### Review: skip | parallel | inline`** — `skip` = no per-requirement review (default — the feature-level review covers it); `parallel` = four reviewers via subagent; `inline` = one `pwk-code-review` pass. Flag a requirement for `parallel` or `inline` when it touches production-risk areas.
+   - **`### Review: skip | parallel | inline`** — `skip` = no per-requirement review (default — the feature-level review covers it); `parallel` = four reviewers via subagent; `inline` = one `pwk-code-review` pass. The auto-tag bullet below is the single source of truth for risky-requirement tagging.
    - **`### Feature review: parallel | inline`** — one review over the **whole feature diff**, always present (the single thorough pass). `parallel` (default — thoroughness lives here, since it is the only review in the common case); `inline` for small features.
    - Tag every requirement — missing tags default to `none` / `skip`. **`spec` requires at least `inline` review** — dropping the complete checkpoint is only safe when review covers implementation quality; never combine `spec` with `Review: skip` (use `Checkpoints: none` instead).
    - **Production-risk notes** — carry forward the design's `## Production-risk areas`, if any.
+   - **Auto-tag risky requirements with `### Review: parallel`** — when a requirement has a non-empty `### Production-risk notes` section, emit `### Review: parallel` as the default. Requirements without risk notes keep the existing default (`### Review: skip`). The tag is silently applied; the human can override or downgrade it to `inline` or `skip` during plan review before approval, and `pwk-executing-tasks` honors the edited value. This is the one source of truth for the auto-tag rule — `pwk-executing-tasks` and the docs link to it here, they do not restate the rule.
    - **Challenge the design first** *(if production-risk areas exist)* — stress-test the design against the flagged risks before writing criteria. If a risk invalidates a design choice, stop and return to `/skill:pwk-brainstorming` rather than planning around a flawed design.
    - **Ordering** — dependencies come **earlier** in the list; the executor runs in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.