89 lines
9.2 KiB
Markdown
89 lines
9.2 KiB
Markdown
---
|
|
name: develop-workflow
|
|
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. 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 by impact
|
|
|
|
Choose the smallest sufficient path before mutation:
|
|
|
|
- **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.
|
|
|
|
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:** scope and impact justify the path and any pending decisions are identified.
|
|
|
|
## Approval boundaries for every path
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** isolation and recovery evidence exist and the next action is authorized.
|
|
|
|
## 2. Discover and plan
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** the record states the intended outcome, checks, ownership, and authority to proceed.
|
|
|
|
## 3. Resolve non-trivial UI direction
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** the selected direction and target-interface evidence are recorded before production UI mutation.
|
|
|
|
## 4. Implement and run focused checks
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** acceptance criteria have intentional implementation and proportionate focused evidence.
|
|
|
|
## 5. Synchronize and independently review
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** the final product diff has independent approval covering both axes and all material fixes.
|
|
|
|
## 6. Run final verification
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** required final checks passed or exceptions were explicitly authorized under repository policy, and review still covers the final product state.
|
|
|
|
## 7. Integrate and close
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
**Complete when:** reviewed work and retained evidence are reachable from the intended local branch and workflow-owned temporary state is safely removed.
|