wehub-resource-sync
134 lines
11 KiB
Markdown
134 lines
11 KiB
Markdown
# Shipping Workflow
|
|
|
|
This file contains the shipping workflow (Phase 3-4). It is loaded when all Phase 2 tasks are complete and execution transitions to quality check.
|
|
|
|
## Phase 3: Quality Check
|
|
|
|
1. **Run Core Quality Checks**
|
|
|
|
Always run before submitting:
|
|
|
|
```bash
|
|
# Run full test suite (use project's test command)
|
|
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
|
|
|
# Run linting (per the project's configured lint command / active instructions)
|
|
# Use linting-agent before pushing to origin
|
|
```
|
|
|
|
2. **Simplify** (conditional — separate from code review)
|
|
|
|
Before code review, invoke **`ce-simplify-code`** when the diff is non-mechanical and large enough to benefit (default: **>=30 changed lines**). Skip when the diff is purely mechanical (formatting, dependency bumps, lint-only fixes, generated artifacts).
|
|
|
|
This step refines reuse, quality, and efficiency on the **current diff** so any later review sees cleaner code. It is not a substitute for code review.
|
|
|
|
Pass `plan:<path>` or a scope hint when the plan or user narrowed what changed. If the skill is unavailable on the harness, skip or do a brief manual pass for obvious duplicate/dead code — code review (step 3) still runs regardless.
|
|
|
|
3. **Code Review**
|
|
|
|
Review the diff with **`ce-code-review`** — the plugin's portable review skill — as the single path. It self-right-sizes (a lite roster for small, low-risk, code-only diffs; the full roster otherwise), so there is no "escalate to a heavier reviewer" decision and **no harness-specific review detection** — it behaves identically on every harness. (This replaces the former Tier 1 harness-native `/review` / Tier 2 escalation split: the size and sensitive-surface judgment that used to live here now lives inside `ce-code-review`'s own reviewer selection and small-diff gate.)
|
|
|
|
**Skip dedicated review only for a purely mechanical diff** — formatting, dependency-version bumps, lint-only fixes, generated artifacts (the same class step 2 skips for simplify). Note in the shipping summary: `Code review: skipped (mechanical diff)`. Everything else gets reviewed.
|
|
|
|
**Review is not fix — two steps:**
|
|
|
|
**3a. Review (read-only).** Invoke `ce-code-review` with `mode:agent` (add `plan:<path>` when known; `base:<ref>` when the diff base is resolved). Pass **`depth:full`** when the plan, the task, or the user explicitly asked for a full / deep / thorough review — that is the one escalation signal `ce-code-review` cannot infer from the diff alone. Do not pass `mode:autofix`. Parse the JSON.
|
|
|
|
**3b. Apply fixes (caller-owned).** Load `references/review-findings-followup.md`: filter on JSON, batch by file, dispatch fix subagents. Orchestrator merges, tests, commits. Then proceed to the Residual Work Gate.
|
|
|
|
**If `ce-code-review` cannot run at all** — subagent dispatch unavailable, unauthenticated, or hard-capped, returning `status: failed`/`degraded` with no coverage even after its own sequential Fallback: in an **interactive** session, run the harness-native review if one exists (e.g. `/review`) and fix inline; in a **non-interactive** session (autonomous pipeline, or no native review available), skip the dedicated step, note `Code review: skipped (ce-code-review unavailable)`, and add an explicit manual diff scan to Final Validation. Never silently ship a non-mechanical change with no review of any kind.
|
|
|
|
4. **Residual Work Gate** (REQUIRED when `ce-code-review` ran and left actionable residuals)
|
|
|
|
After code review and review-findings followup, inspect the **Actionable Findings** summary (or read the run artifact at `/tmp/compound-engineering/ce-code-review/<run-id>/` if the summary was truncated). If one or more actionable `downstream-resolver` findings were not applied in followup, do not proceed to Final Validation until they are resolved or durably recorded.
|
|
|
|
**Non-interactive / autonomous sessions (no human can answer — e.g. an `lfg`-style pipeline or a headless run):** do **not** call the blocking tool — that would hang the pipeline. After step 3b auto-applied every mechanically-eligible finding, take the `Accept and proceed` path automatically: record the remaining actionable residuals verbatim to the durable Known Residuals sink (the PR description's Known Residuals section, or `docs/residual-review-findings/<branch-or-head-sha>.md` on the no-PR path) and continue to Final Validation. Residuals are recorded, never dropped — this keeps autonomous shipping unblocked without losing findings.
|
|
|
|
**Interactive sessions:** Ask the user using the platform's blocking question tool (`AskUserQuestion` in Claude Code with `ToolSearch select:AskUserQuestion` pre-loaded if needed, `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension)). Fall back to numbered options in chat only when the harness genuinely lacks a blocking tool. Never silently skip the gate.
|
|
|
|
Stem: `Code review left N actionable finding(s) not yet fixed. How should the agent proceed?`
|
|
|
|
Options (four or fewer, self-contained labels):
|
|
- `Apply/fix now` — load `references/review-findings-followup.md`, dispatch batched fix subagents for remaining eligible findings, run tests, commit if needed; optionally re-run `ce-code-review` only after the diff changed materially.
|
|
- `File tickets via project tracker` — load `references/tracker-defer.md` in Interactive mode; the agent files tickets in the project's detected tracker (or `gh` fallback, or leaves them in the report if no sink exists) and proceeds to Final Validation.
|
|
- `Accept and proceed` — record the residual findings verbatim in a durable "Known Residuals" sink before shipping. If a PR will be created or updated in Phase 4, include them in the PR description's "Known Residuals" section (the agent owns this when calling `ce-commit-push-pr`). If the user later chooses the no-PR `ce-commit` path, create `docs/residual-review-findings/<branch-or-head-sha>.md`, include the accepted findings and source review-run context, stage it with the implementation commit, and mention the file path in the final summary. The user has acknowledged the risk, but the findings must not live only in the transient session.
|
|
- `Stop — do not ship` — abort the shipping workflow. The user will handle findings manually before re-invoking.
|
|
|
|
Skip this gate entirely when the review reported `Actionable findings: none.` (and followup applied everything mechanical), or when dedicated review was skipped (mechanical diff or `ce-code-review` unavailable). Do not proceed past this gate on an `Accept and proceed` decision (including the autonomous auto-accept above) until the agent has recorded whether the durable sink is `PR Known Residuals` or `docs/residual-review-findings/<branch-or-head-sha>.md`.
|
|
|
|
5. **Final Validation**
|
|
- All tasks marked completed
|
|
- Testing addressed -- tests pass and new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)
|
|
- Linting passes
|
|
- Code follows existing patterns
|
|
- Figma designs match (if applicable)
|
|
- No console errors or warnings
|
|
- If the plan has a `Requirements` section (or legacy `Requirements Trace`), verify each requirement is satisfied by the completed work
|
|
- If any `Deferred to Implementation` questions were noted, confirm they were resolved during execution
|
|
|
|
6. **Prepare Operational Validation Plan** (REQUIRED)
|
|
- Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
|
|
- Include concrete:
|
|
- Log queries/search terms
|
|
- Metrics or dashboards to watch
|
|
- Expected healthy signals
|
|
- Failure signals and rollback/mitigation trigger
|
|
- Validation window and owner
|
|
- If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
|
|
|
|
## Phase 4: Ship It
|
|
|
|
1. **Prepare Validation Context**
|
|
|
|
Do not try to launch a dedicated CE evidence-capture workflow. Modern harnesses provide their own browser, screenshot, terminal recording, and artifact capture tools; use those directly only when the user asks or when the artifact already exists.
|
|
|
|
Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output), and summarize any manual validation performed. If the user supplied evidence (URL, markdown embed, local artifact path), pass it to `ce-commit-push-pr` as PR-description context.
|
|
|
|
2. **Commit and Create Pull Request**
|
|
|
|
Load the `ce-commit-push-pr` skill to handle committing, pushing, and PR creation. The skill handles convention detection, branch safety, logical commit splitting, adaptive PR descriptions, and attribution badges.
|
|
|
|
When providing context for the PR description, include:
|
|
- The plan's summary and key decisions
|
|
- Testing notes (tests added/modified, manual testing performed)
|
|
- Evidence context from step 1, so `ce-commit-push-pr` can decide whether to ask about capturing evidence
|
|
- Figma design link (if applicable)
|
|
- The Post-Deploy Monitoring & Validation section (see Phase 3 Step 6)
|
|
- Any "Known Residuals" accepted in the Phase 3 Residual Work Gate, rendered as a dedicated section in the PR body with severity, file:line, and title per finding
|
|
|
|
If the user prefers to commit without creating a PR, load the `ce-commit` skill instead.
|
|
|
|
3. **Notify User**
|
|
- Summarize what was completed
|
|
- Link to PR (if one was created)
|
|
- Note any follow-up work needed
|
|
- Suggest next steps if applicable
|
|
|
|
## Quality Checklist
|
|
|
|
Before creating PR, verify:
|
|
|
|
- [ ] All clarifying questions asked and answered
|
|
- [ ] All tasks marked completed
|
|
- [ ] Testing addressed -- tests pass AND new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)
|
|
- [ ] Linting passes (use linting-agent)
|
|
- [ ] Code follows existing patterns
|
|
- [ ] Figma designs match implementation (if applicable)
|
|
- [ ] Validation/evidence context passed to `ce-commit-push-pr` when the change has observable behavior
|
|
- [ ] Commit messages follow conventional format
|
|
- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
|
|
- [ ] Simplify: `ce-simplify-code` when diff >=30 lines (or skipped with reason)
|
|
- [ ] Code review: `ce-code-review` ran (self-sized), or skipped (mechanical diff / unavailable — noted in summary); residuals handled via the Residual Work Gate
|
|
- [ ] PR description includes summary, testing notes, and evidence when captured
|
|
- [ ] PR description includes Compound Engineered badge with accurate model and harness
|
|
|
|
## Code Review
|
|
|
|
Single portable path: **`ce-code-review`** self-sizes (lite roster for small low-risk code-only diffs, full roster otherwise). No harness-native review detection, no escalation tiers — the size/sensitive-surface judgment lives inside `ce-code-review` now.
|
|
|
|
**Skip** only for a purely mechanical diff (formatting, dep-bumps, lint-only, generated). Everything else is reviewed.
|
|
|
|
**Two steps — review is not fix.** (3a) Review-only via `mode:agent`; add `depth:full` when the plan/task/user explicitly asked for a deep review. (3b) Batched fix subagents per `references/review-findings-followup.md`; residuals → Residual Work Gate.
|
|
|
|
**If `ce-code-review` can't run** (no subagent dispatch): interactive → harness-native review if present, fix inline; non-interactive → skip-with-note + manual diff scan in Final Validation. Never silently ship a non-mechanical change unreviewed.
|