From 1e976176ba6e9e9321bfbec418d30c63ce87f03c Mon Sep 17 00:00:00 2001 From: drepkovsky Date: Fri, 12 Jun 2026 16:12:58 +0200 Subject: [PATCH] Add safe workflow skill --- README.md | 17 +++++--- docs/cli-reference.md | 3 +- docs/concepts.md | 16 ++++++++ docs/flows.md | 16 ++++---- src/flow.ts | 21 ++++++++++ src/index.ts | 2 +- src/nudge.ts | 2 +- src/skills-audit.ts | 4 ++ src/skills.ts | 95 ++++++++++++++++++++++++++++++++++++++----- src/workspace.ts | 8 ++++ test/cli.test.ts | 3 ++ 11 files changed, 161 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 752389e..ba8079b 100644 --- a/README.md +++ b/README.md @@ -44,9 +44,9 @@ agent-board skills install `agent-board skills install` links the bundled skills into supported local runtimes: ```txt -~/.claude/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review} -~/.agents/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review} -~/.cursor/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review} +~/.claude/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review} +~/.agents/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review} +~/.cursor/skills/{agent-board,agent-board-bootstrap,agent-board-research,agent-board-spec,agent-board-safe-workflow,agent-board-flow,agent-board-implement,agent-board-worker,agent-board-grill,agent-board-maintenance,agent-board-design-wireframe,agent-board-design-review} ``` Check links, and that the bundled skill docs still match the CLI: @@ -104,14 +104,21 @@ Frontend/product work adds a design gate before production code: spec -> design flow -> wireframe/design board -> design review -> implementation tasks ``` +User-facing behavior adds a safe workflow gate before production code: + +```txt +use cases -> scenario matrix -> failing test/replay -> implementation -> full regression +``` + ## Skills -Eleven skills are bundled: +Twelve skills are bundled: - `agent-board`: thin router/orchestrator. Chooses the right workflow, creates goals/specs/tasks, delegates, reviews evidence, and controls flow waves. - `agent-board-bootstrap`: guided project or feature bootstrap interview with current-docs research and explicit tradeoffs. - `agent-board-research`: read-only discovery. Turns repo/current-docs uncertainty into specs, knowledge, blockers, and concrete tasks. - `agent-board-spec`: writes or updates specs, task graphs, dependencies, acceptance criteria, and verify blocks. +- `agent-board-safe-workflow`: TDD and no-regression workflow. Defines use-case ids, scenario matrices, stable test ids/selectors, e2e/replay gates, and verify commands before implementation. - `agent-board-flow`: designs and runs closed-loop flow waves, including runtime/model discovery, deterministic fan-out, review, synthesis, design gates, task graphs, per-file refactor lanes, and hygiene loops. - `agent-board-implement`: executes one explicit task id. Claims, edits, verifies, and closes the task. - `agent-board-worker`: legacy name for the same one-task implementation workflow; kept for compatibility. @@ -155,7 +162,7 @@ agent-board flow show agent-board flow watch # read-only follower for the same live progress stream ``` -Templates: `default`, `feature`, `review`, `fix`, `design`, `task-graph`, `refactor`, `hygiene`, `grill`. +Templates: `default`, `feature`, `review`, `fix`, `design`, `task-graph`, `refactor`, `hygiene`, `grill`, `safe-workflow`. `flow run` prints the run id immediately and renders live per-agent progress by default. Use `--no-watch` when another terminal will follow the run with `flow watch`. The per-agent inactivity watchdog defaults to 120m. Long reviews are allowed to diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 99694aa..0a3c9d4 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -135,7 +135,7 @@ project-specific `package.json` preview script is required. ## Flows ```sh -agent-board flow new [--template default|feature|review|fix|design|task-graph|refactor|hygiene|grill] [--force] +agent-board flow new [--template default|feature|review|fix|design|task-graph|refactor|hygiene|grill|safe-workflow] [--force] agent-board flow list agent-board flow runtimes agent-board flow models --runtime @@ -184,6 +184,7 @@ agent. Templates are simple editable JavaScript scripts: - `refactor`: deterministic per-file planning; up to 30 file paths become independent read lanes - `hygiene`: maintenance reader + archive planner + consolidator - `grill`: adversarial challenge of assumptions, stale facts, risks, and test gaps +- `safe-workflow`: use-case cartographer + scenario matrix auditor + TDD planner + replay gate reviewer `flow run` prints: diff --git a/docs/concepts.md b/docs/concepts.md index bb6e918..c9fc73c 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -15,6 +15,7 @@ agent-board-bootstrap/ agent-board-research/ agent-board-spec/ + agent-board-safe-workflow/ agent-board-flow/ agent-board-implement/ agent-board-worker/ @@ -115,6 +116,21 @@ until first-class task-wireframe links exist. A design review can create blockin follow-up tasks, design gotchas in knowledge, or approval evidence for the next implementation wave. +## Safe Workflow Gate + +User-facing behavior should be represented as a no-regression contract before +production code starts: + +```txt +use cases -> scenario matrix -> failing test/replay -> implementation -> full regression +``` + +Use stable use-case and flow ids such as `UC-001` and `F01`, then describe each +scenario with a lower-kebab slug, layer, actors, states, locales, fixtures, +real-API requirement, and verify command. UI-facing tests should use stable, +locale-independent selectors/test ids based on product terms. The final task is +not done until the new scenario and the existing regression suite pass. + ## Task Contract A task is a Markdown file with frontmatter: diff --git a/docs/flows.md b/docs/flows.md index 0d2fb4e..e0223cf 100644 --- a/docs/flows.md +++ b/docs/flows.md @@ -75,6 +75,7 @@ Templates: - `refactor`: deterministic per-file planning; explicit file paths in the input become up to 30 independent read lanes - `hygiene`: board cleanup planning for stale runs, stale claims, duplicates, archive candidates, and canonical replacements - `grill`: adversarial challenge of assumptions, stale external facts, risks, and test gaps +- `safe-workflow`: TDD/no-regression planning for use-case ids, scenario matrices, stable test ids, e2e/replay gates, and verify commands For quick read-only fan-out: @@ -233,13 +234,14 @@ For non-trivial work: 1. Confirm project and goal with `agent-board status`. 2. Write or update a spec. 3. For frontend/product work, create the design gate first: design flow, wireframe/design-board artifact, optional presentation artifact, and design-review task. -4. Split the feature into linked tasks. -5. Create a flow script with `agent-board flow new --template `. -6. Inspect or edit the script with `agent-board flow cat/write` to encode phases: fan-out, worker prompts, reviews, synthesis, and task/evidence updates. -7. Summarize the phases to the user. -8. Run the script after approval or explicit go-ahead. -9. While the flow runs, read the live progress lines; if the flow is attached to a task and you learn something durable before completion, record it with `agent-board progress --from -`. -10. Read `summary.md`, update board state, and decide the next wave. +4. For user-facing behavior, create the safe workflow gate first: use-case ids, scenario matrix, stable test ids/selectors, failing test or replay, and full-regression verify commands. +5. Split the feature into linked tasks. +6. Create a flow script with `agent-board flow new --template `. +7. Inspect or edit the script with `agent-board flow cat/write` to encode phases: fan-out, worker prompts, reviews, synthesis, and task/evidence updates. +8. Summarize the phases to the user. +9. Run the script after approval or explicit go-ahead. +10. While the flow runs, read the live progress lines; if the flow is attached to a task and you learn something durable before completion, record it with `agent-board progress --from -`. +11. Read `summary.md`, update board state, and decide the next wave. For deterministic large fan-out, feed `task-graph` newline-separated lanes or `refactor` newline-separated file paths. Both templates cap generated lanes at diff --git a/src/flow.ts b/src/flow.ts index 6c84912..3c26c67 100644 --- a/src/flow.ts +++ b/src/flow.ts @@ -24,6 +24,7 @@ export const FLOW_TEMPLATES = [ "refactor", "hygiene", "grill", + "safe-workflow", ] as const; export type FlowTemplate = (typeof FLOW_TEMPLATES)[number]; @@ -1937,6 +1938,26 @@ function flowTemplate(name: string, template: FlowTemplate): string { }, ], "Synthesize this into a grill report with blockers, must-verify-current-facts, follow-up tasks, accepted risks, and questions. Be adversarial but concrete."); } + if (template === "safe-workflow") { + return roleFlowTemplate(name, template, fallback, [ + { + name: "use-case-cartographer", + brief: "Map the requested work into durable use cases and app flows before implementation. Do not edit files. Return proposed UC ids, flow ids, actors, states, locales, acceptance criteria, and gaps in the current spec.", + }, + { + name: "scenario-matrix-auditor", + brief: "Design a regression scenario matrix. Do not edit files. Return route/API/PWA/visual/native layers, stable scenario names, filename conventions, required real API coverage, and which existing scenarios must keep passing.", + }, + { + name: "tdd-planner", + brief: "Plan the red-green-refactor sequence. Do not edit files. Return the first failing test, implementation slice, refactor guard, and exact verification commands.", + }, + { + name: "replay-gate-reviewer", + brief: "Define the no-regression gate. Do not edit files. Return replay/e2e commands, qprobe record/replay opportunities, log/API/browser assertions, and conditions that block done.", + }, + ], "Synthesize this into a safe workflow plan: use-case ids, scenario matrix, stable selectors/test ids, TDD red-green-refactor order, e2e or qprobe replay gates, verify commands, board tasks, and blockers. Work is not shippable until existing regressions and new scenarios pass."); + } return roleFlowTemplate(name, template, fallback, [ { name: "reproducer", diff --git a/src/index.ts b/src/index.ts index b779662..77bbcae 100755 --- a/src/index.ts +++ b/src/index.ts @@ -864,7 +864,7 @@ flow .description("Create a project flow script") .option( "--template