jb/harness-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make development workflow risk-based and verification proportionate

Browse Source
This commit is contained in:
jb
2026-10-07 17:43:19 -04:00
parent 284fdd638d
commit 0cc0e82bbc
13 changed files with 265 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/develop/develop-workflow/SKILL.md
+42 -51
View File
@@ -1,97 +1,88 @@
---
name: develop-workflow
description: Runs feature work and other multi-step code changes through repository research, an approved implementation plan, isolated Git worktrees, explicit UI and risk gates, verification, independent review, and local integration. Use by default for features, non-trivial bug fixes, refactors, migrations, dependency changes, security-sensitive work, and UI changes. Excludes questions, research-only requests, and obvious low-risk edits requiring at most two steps.
description: Runs feature work, bug fixes, refactors, migrations, dependency changes, security-sensitive work, and UI changes through risk-based planning, isolated worktrees, proportionate verification, independent review, and local integration. Use by default for implementation work; keep questions read-only and straightforward low-risk edits lightweight.
---
# Develop workflow
Own orchestration in the parent agent. Treat Git and the retained workflow record as recovery evidence; use task tools only as the live progress view. Give subagents bounded assignments, then verify their claims against repository state.
Own orchestration in the parent agent. Use Git and one retained record for recovery, task tools for live progress, and subagents only when their benefit exceeds coordination cost. Proceed within clear requirements and established patterns; reserve human interaction for decisions and meaningful risk.
## 0. Classify the request
## 0. Classify by impact
Choose the smallest sufficient path before mutation:
- **Answer:** explain or research read-only. Make no changes.
- **Light:** make one obvious low-risk edit requiring at most two steps. Inspect, edit, run focused checks, and summarize. Record why this is safe when near the boundary.
- **Full:** use the phases below for three or more steps, multiple files or modules, ambiguity, architecture, dependencies, migrations, security implications, non-trivial UI, or meaningful regression risk.
- **Answer:** explain or research read-only.
- **Light:** a straightforward, bounded edit with understood behavior and low regression risk. Inspect, edit, run relevant checks, and summarize. Respect repository isolation and review requirements.
- **Standard:** feature work or changes needing coordinated implementation, verification, or recovery. Follow the phases below. Multiple files or steps alone do not imply high risk or require approval.
Promote light work to full before editing when discovery reveals meaningful scope or risk.
For either implementation path, assess affected consumers, data value, security, reversibility, and uncertainty. Record the reason when classification is near the boundary. Escalate the affected decision when new evidence reveals risk; do not restart the whole workflow for routine execution adjustments.
**Complete when:** observed scope and risk justify the selected path.
**Complete when:** scope and impact justify the path and any pending decisions are identified.
## Risk gates for every path
## Approval boundaries for every path
Ask just in time before adding, removing, or materially upgrading dependencies; schema/data migration; production or live-database access; public API or compatibility breaks; destructive Git/filesystem actions outside the narrowly proven final cleanup; force push or shared-history rewrite; non-fast-forward integration; conflict resolution that changes approved behavior; material scope or acceptance expansion; security-posture changes; publishing; or deployment.
Honor repository and global instructions. Ask for unresolved product or preference-sensitive design choices, material scope expansion, security-posture changes, externally breaking contracts, production/live-database access, protected data, publishing/deployment, unsafe cleanup, force operations, shared-history rewrite, non-fast-forward integration, or conflict resolution that changes agreed behavior. Dependency additions, removals, and material upgrades still need scoped authorization unless already explicitly approved.
Present concrete evidence, scope the authorization, and mark one option recommended with its reason. Checkpoint the decision before acting. Treat approval as specific to that action; ask again when later evidence broadens it. Promote light work to full before editing when meaningful risk appears.
For schema/data work, apply [data policy](references/data-policy.md): a standing authorization may cover named disposable targets, but pre-production alone grants no permission. Verify the actual target before any authorized operation.
Reuse an explicit authorization within its scope instead of asking again at execution. Ask again only when evidence changes that scope or a rule explicitly requires a fresh decision. Present concrete evidence, a recommended option with its reason, and record the answer before acting. Routine worker reassignment after proven termination, equivalent checks, or internal implementation adjustments under established patterns are not new product decisions.
## 1. Preflight and isolate
For the full path, require Git worktrees, a writable repository record, `ask_user`, Git-capable independent reviewers, and target-interface validation when UI applies. Stop before product mutation when a mandatory capability is unavailable. Let task tools degrade to the retained record and let `artifact-presenter` degrade to reporting the exact artifact path; neither optional convenience may bypass a gate. In print or JSON mode, emit the pending gate or validation instructions and stop.
Read repository instructions, relevant docs/ADRs/tests, and Git state. For standard work, require an isolated Git worktree, a writable record, and a Git-capable independent reviewer. Require target-interface validation for UI changes. Follow [Git and integration](references/git-and-integration.md) for isolation and dirty-source handling.
Read repository instructions, relevant docs/ADRs/tests, and Git state. Follow [Git and integration](references/git-and-integration.md) to capture source evidence, resolve dirty-source approval, and establish the isolated branch/worktree. Prepare a unique record from [`assets/workflow-record.md`](assets/workflow-record.md) and publish it with the helper in [evidence and recovery](references/evidence-and-recovery.md). Create the available live progress view, run applicable documentation checks, and commit the initial record before product mutation.
Create a unique record from [`assets/workflow-record.md`](assets/workflow-record.md) using [evidence and recovery](references/evidence-and-recovery.md). Create the available task view. Save the record before product mutation; a separate initial commit is unnecessary.
**Complete when:** worktree identity is proven and the initial record commit names the next safe action.
Stop only at an unavailable capability needed for the next action. Noninteractive runs may proceed within clear authorization; if a human decision is pending and `ask_user` is unavailable, report the decision and stop before dependent mutation. Task tools may degrade to the record, and artifact presentation to an exact path.
## 2. Discover and decide requirements
**Complete when:** isolation and recovery evidence exist and the next action is authorized.
Launch independent read-only research lanes directly when concerns can be investigated separately; state that no files are owned. Give each child a self-contained prompt. Keep the parent active on other work and verify that every required result was delivered. Treat missing delivery as missing evidence.
## 2. Discover and plan
Reconcile repository evidence into scope, out-of-scope items, acceptance criteria, affected surfaces, constraints, and risks. Use `ask_user` only for decisions repository evidence cannot answer. Checkpoint decisions.
Resolve scope, acceptance criteria, affected surfaces, existing seams, and risks from repository evidence. Launch read-only research lanes only for useful independent questions; state that they own no files. Verify required results were delivered.
**Complete when:** requirements and unresolved questions are explicit.
Record a concise plan with implementation slices, path ownership, focused checks, final required verification, UI/data classification, outstanding decisions, and local integration/rollback. Use [proportionate verification](references/verification.md) to choose tests. Give mutating children bounded assignments, normally 15 minutes; the parent may adjust the bound to the task without a user gate.
## 3. Design and obtain plan approval
For clear routine work, state the plan and proceed. Present a plan through `artifact-presenter` when human review is needed, then use `ask_user` for the unresolved choices. An explicit user approval already supplied in conversation counts. Revisit only decisions affected by changed evidence; changing an owner or equivalent verification command does not itself require reapproval.
Record an exact implementation plan containing:
**Complete when:** the record states the intended outcome, checks, ownership, and authority to proceed.
- acceptance criteria mapped to slices;
- one named owner and concrete path ownership per mutating assignment;
- existing seams and patterns;
- focused and full verification commands with realistic data needs;
- UI classification, dependencies, migrations, production effects, and risk gates;
- review fixed point and specification source;
- integration and rollback strategy;
- a 15-minute default deadline per mutating assignment, or an explicitly approved alternative.
## 3. Resolve non-trivial UI direction
Present the complete record through `artifact-presenter`, then obtain explicit approval with `ask_user`. Checkpoint and commit the decision before production edits. Return to this gate after any material scope, acceptance, ownership, verification, or architecture change.
For non-trivial UI, invoke `prototype` and create three structurally different throwaway candidates before production-component edits. Ask approval for a smaller count when three meaningful alternatives are impossible. Validate candidates in the browser or real PTY/application, including representative responsive sizes. Prefer fast-browser for supported local web validation; use browser-harness when explicitly requested or its additional capabilities are needed.
**Complete when:** the user explicitly approved the exact committed plan.
Retain candidates on a dedicated throwaway branch and record its commit. Present them, obtain direction approval through `ask_user`, and checkpoint the choice. Rewrite the chosen direction as production code. Record why minor or non-visual UI skips prototyping; changed UI still needs actual interface validation.
## 4. Resolve non-trivial UI direction
**Complete when:** the selected direction and target-interface evidence are recorded before production UI mutation.
For non-trivial UI, invoke `prototype` and create three structurally different throwaway candidates before production-component edits. Ask approval for a smaller explicit count when three meaningful alternatives are impossible. Validate candidates through `browser-harness` for web UI or the real PTY/application for terminal/native UI, including representative responsive sizes.
## 4. Implement and run focused checks
Retain candidates on a dedicated throwaway branch and record its commit. Present them and obtain direction approval through `ask_user`. Checkpoint the selected direction before production mutation. Rewrite the chosen direction as production code rather than promoting prototype code. Record why minor or non-visual UI skips this phase.
State one owner and exclusive paths for each mutating assignment. Serialize by default; parallelize disjoint low-integration paths. Give workers the plan, decisions, acceptance criteria, test seam, commands, and deadline. Leave commits, integration, user interaction, and mutation delegation to the parent.
**Complete when:** target-interface evidence, retained prototype commit, selected direction, and reflected plan are recorded.
Follow [assignment evidence](references/evidence-and-recovery.md#assignment-evidence). Use TDD when appropriate under its agreed-seam rules, rather than invoking it for every edit. Run focused checks after meaningful behavioral slices; reuse delivered evidence when its inputs remain valid. Inspect returned diffs and repository state before accepting work.
## 5. Implement owned slices
**Complete when:** acceptance criteria have intentional implementation and proportionate focused evidence.
State one owner and exclusive paths for every mutating assignment. Serialize by default; parallelize only disjoint low-integration paths. Give each implementer the approved plan, decisions, acceptance criteria, test seam, allowed commands, and deadline. Tell workers to stop at the deadline and leave commits, integration, user interaction, and mutation delegation to the parent.
## 5. Synchronize and independently review
Follow [assignment evidence and recovery](references/evidence-and-recovery.md#assignment-evidence) before accepting, retrying, or reassigning mutation. Use TDD at agreed seams where practical. Run focused tests after behavioral slices. Inspect each returned diff and repository state before marking it complete.
Inspect the complete diff, synchronize affected documentation, and follow [Git and integration](references/git-and-integration.md) to fetch/rebase before final verification where practical. Run checks affected by synchronization, then create focused commits after their applicable checks pass.
**Complete when:** every acceptance criterion has intentional owned code and test evidence.
Follow [review and remediation](references/review-and-remediation.md). One independent, read-only reviewer covers standards and specification. Resolve material findings through a non-reviewer, run affected checks, and obtain targeted follow-up. Routine fixes do not require two new reviewers or a full-suite rerun before each review.
## 6. Verify the integrated worktree
**Complete when:** the final product diff has independent approval covering both axes and all material fixes.
Inspect the complete diff and status. Run focused behavioral tests, then repository-required typecheck, lint, build, and full tests. Exercise realistic E2E data across process/UI boundaries. Validate changed UI in its target interface and representative sizes. Synchronize affected documentation.
## 6. Run final verification
Record exact commands, exit codes, and concise outcomes. Keep flaky or environmental failures visible until resolved or escalated. Never infer success from a child transcript.
After review fixes, run the full repository-required test suite once against the integrated worktree, plus applicable typecheck, lint, and build checks. Use [verification evidence](references/verification.md) to reuse valid results and rerun invalidated checks. A failure is not permission to skip completion; fix it, obtain review for changed behavior, and rerun the necessary checks.
**Complete when:** the approved verification matrix passes against the integrated worktree state.
Validate changed UI in its target interface and important cross-boundary behavior with realistic data. Record commands, exit codes, and concise outcomes. Keep flaky/environmental failures visible until resolved or explicitly escalated. Distinguish a policy-authorized waiver from a pass.
## 7. Commit, synchronize, and review
**Complete when:** required final checks passed or exceptions were explicitly authorized under repository policy, and review still covers the final product state.
Create focused commits after their checks pass. Follow [Git and integration](references/git-and-integration.md) to fetch/rebase, reverify changed trees, and produce the pinned review brief and exact diff fingerprint. Follow [review and remediation](references/review-and-remediation.md) for two independent review axes, mutator exclusion, findings, and fresh-review rules.
## 7. Integrate and close
**Complete when:** standards and specification reviewers approve the exact verified product diff.
Follow [Git and integration](references/git-and-integration.md) for clean fast-forward integration, evidence updates, and proven-safe cleanup. Batch record changes with meaningful commits; a separate metadata closure commit is optional, not a gate. A later evidence-only record update cannot silently change requirements or executable instructions.
## 8. Integrate and close
Mark tasks complete and report commits, verification outcomes, review result, and record path concisely. Preserve detailed identity and fingerprint evidence in the record rather than repeating it in chat. Push, publish, deployment, and other protected actions remain outside local integration unless explicitly authorized.
Follow [Git and integration](references/git-and-integration.md). Recheck the source branch and checkout, fast-forward only when evidence remains valid, then create one metadata-only closure commit touching only the record. Run a cheap final sanity check. Remove the workflow-owned worktree and branch only after reachability and clean-state proofs.
Mark tasks complete and report product/closure commits, review command and digest, reviewer identities, record path, and verification evidence. Keep push, publish, deployment, production access, unsafe cleanup, conflict-driven behavior changes, force operations, and non-fast-forward integration behind explicit just-in-time approval.
**Complete when:** reviewed work and closure are reachable from the intended local source branch and temporary state is safely removed.
**Complete when:** reviewed work and retained evidence are reachable from the intended local branch and workflow-owned temporary state is safely removed.