From 3b3aaf13e7cf62110ee3f833fdb7781cacd82a54 Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Wed, 22 Apr 2026 11:42:01 +0300 Subject: [PATCH 1/4] feat(skills): phase protocol enforcement for orchestration skills Add four complementary enforcement mechanisms to make ORCHESTRATED pipeline phase compliance the path of least resistance: - Phase Protocol section in router with 5 rules (announce, produce, no silent skips, verify, scoped nesting) - Produces:/Requires: checkpoint variables on all 7 orch skills - Continuation Detection for plan:orch and implement:orch - Phase Completion Checklist on all 7 orch skills Structural tests validate checklist/phase count correspondence, annotation presence, and continuation detection placement. --- shared/skills/debug:orch/SKILL.md | 29 +++++++++ shared/skills/explore:orch/SKILL.md | 21 +++++++ shared/skills/implement:orch/SKILL.md | 44 ++++++++++++++ shared/skills/pipeline:orch/SKILL.md | 31 ++++++++++ shared/skills/plan:orch/SKILL.md | 63 +++++++++++++++++++ shared/skills/resolve:orch/SKILL.md | 33 ++++++++++ shared/skills/review:orch/SKILL.md | 34 +++++++++++ shared/skills/router/SKILL.md | 10 +++ tests/ambient.test.ts | 87 +++++++++++++++++++++++++++ 9 files changed, 352 insertions(+) diff --git a/shared/skills/debug:orch/SKILL.md b/shared/skills/debug:orch/SKILL.md index e5d0c70..97a398a 100644 --- a/shared/skills/debug:orch/SKILL.md +++ b/shared/skills/debug:orch/SKILL.md @@ -26,6 +26,8 @@ If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktre ## Phase 0: Load Knowledge Index (Orchestrator-Local) +**Produces:** KNOWLEDGE_CONTEXT + Before hypothesizing, load the knowledge index: ```bash @@ -36,6 +38,9 @@ The orchestrator uses `KNOWLEDGE_CONTEXT` locally when generating hypotheses (Ph ## Phase 1: Hypothesize +**Produces:** HYPOTHESES +**Requires:** KNOWLEDGE_CONTEXT + Analyze the bug description, error messages, and conversation context. Generate 3-5 hypotheses that are: - **Specific**: Points to a concrete mechanism (not "something is wrong with auth") @@ -46,6 +51,9 @@ If fewer than 3 hypotheses are possible, proceed with 2. ## Phase 2: Investigate (Parallel) +**Produces:** INVESTIGATION_RESULTS +**Requires:** HYPOTHESES + Spawn one `Agent(subagent_type="Explore")` per hypothesis **in a single message** (parallel execution): - Each investigator searches for evidence FOR and AGAINST its hypothesis @@ -54,6 +62,9 @@ Spawn one `Agent(subagent_type="Explore")` per hypothesis **in a single message* ## Phase 3: Converge +**Produces:** CONVERGENCE_DECISION +**Requires:** INVESTIGATION_RESULTS + Evaluate investigation results: - **One CONFIRMED**: Spawn 1-2 additional `Agent(subagent_type="Explore")` agents to validate from different angles (prevent confirmation bias) @@ -62,6 +73,9 @@ Evaluate investigation results: ## Phase 4: Report +**Produces:** ROOT_CAUSE_REPORT +**Requires:** CONVERGENCE_DECISION, INVESTIGATION_RESULTS + Present root cause analysis: - **Confidence level**: HIGH (confirmed + validated) | MEDIUM (partial convergence) | LOW (best guess from incomplete evidence) @@ -71,6 +85,8 @@ Present root cause analysis: ## Phase 5: Offer Fix +**Requires:** ROOT_CAUSE_REPORT + Ask user via AskUserQuestion: "Want me to implement this fix?" - **YES** → Implement the fix directly in main session using GUIDED approach: load devflow:patterns, devflow:research, and devflow:test-driven-development skills, then code the fix. Spawn `Agent(subagent_type="Simplifier")` on changed files after. @@ -80,3 +96,16 @@ Ask user via AskUserQuestion: "Want me to implement this fix?" - **All hypotheses disproved, no second-round ideas**: Report "No root cause identified" with summary of what was investigated and ruled out - **Explore agents return insufficient evidence**: Report LOW confidence with available evidence, suggest manual investigation areas + +## Phase Completion Checklist + +Before reporting results, verify every phase was announced: + +- [ ] Phase 0: Load Knowledge Index → KNOWLEDGE_CONTEXT captured +- [ ] Phase 1: Hypothesize → HYPOTHESES captured (3-5 distinct) +- [ ] Phase 2: Investigate → INVESTIGATION_RESULTS captured per hypothesis +- [ ] Phase 3: Converge → CONVERGENCE_DECISION captured +- [ ] Phase 4: Report → ROOT_CAUSE_REPORT presented +- [ ] Phase 5: Offer Fix → User asked, response handled + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/explore:orch/SKILL.md b/shared/skills/explore:orch/SKILL.md index cf4003f..3610ad7 100644 --- a/shared/skills/explore:orch/SKILL.md +++ b/shared/skills/explore:orch/SKILL.md @@ -30,6 +30,8 @@ For GUIDED depth, the main session performs exploration directly: ### Phase 1: Orient +**Produces:** ORIENT_OUTPUT + Spawn `Agent(subagent_type="Skimmer")` to get codebase overview relevant to the exploration question: - File structure and module boundaries in the target area @@ -38,6 +40,9 @@ Spawn `Agent(subagent_type="Skimmer")` to get codebase overview relevant to the ### Phase 2: Explore +**Produces:** EXPLORE_OUTPUT +**Requires:** ORIENT_OUTPUT + Based on Skimmer findings, spawn 2-3 `Agent(subagent_type="Explore")` agents **in a single message** (parallel execution): - **Flow explorer**: Trace the primary call chain end-to-end — entry point through to side effects @@ -48,6 +53,9 @@ Adjust explorer focus based on the specific exploration question. ### Phase 3: Synthesize +**Produces:** MERGED_FINDINGS +**Requires:** EXPLORE_OUTPUT + Spawn `Agent(subagent_type="Synthesizer")` in `exploration` mode with combined findings: - Merge overlapping discoveries from parallel explorers @@ -56,6 +64,8 @@ Spawn `Agent(subagent_type="Synthesizer")` in `exploration` mode with combined f ### Phase 4: Present +**Requires:** MERGED_FINDINGS + Main session reviews synthesis for: - **Gaps**: Areas the explorers missed or couldn't reach @@ -78,3 +88,14 @@ Structured exploration findings with concrete code references: - Integration Points (module boundaries, shared types, external dependencies) - Patterns (recurring conventions, design decisions observed) - Key Insights (non-obvious findings, surprises, potential concerns) + +## Phase Completion Checklist + +Before presenting findings, verify every phase was announced: + +- [ ] Phase 1: Orient → ORIENT_OUTPUT captured +- [ ] Phase 2: Explore → EXPLORE_OUTPUT captured +- [ ] Phase 3: Synthesize → MERGED_FINDINGS captured +- [ ] Phase 4: Present → Findings delivered with file:line references + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/implement:orch/SKILL.md b/shared/skills/implement:orch/SKILL.md index 22e9ef3..3204b0c 100644 --- a/shared/skills/implement:orch/SKILL.md +++ b/shared/skills/implement:orch/SKILL.md @@ -20,8 +20,25 @@ This is a lightweight variant of `/implement` for ambient ORCHESTRATED mode. Exc --- +## Continuation Detection + +Before starting the full pipeline, check for re-validation context: + +- **Re-validation after manual fix**: User explicitly asks to re-validate, re-check, or re-run gates after making their own changes + +If this condition is true → execute **Re-validation Path**: +1. **Branch safety check**: If current branch is protected (main, master, etc.), execute Phase 1 first to create/switch to a work branch. If already on a work branch, skip Phase 1. +2. Skip Phases 2-3 (no Coder needed) +3. Run Phase 4 (FILES_CHANGED Detection) using the existing branch +4. Run Phase 5 (Quality Gates) on detected changes +5. Proceed to Phase 6 (Completion) + +If not → proceed with the full pipeline below. + ## Phase 1: Pre-flight — Branch Safety +**Produces:** BASE_BRANCH, FEATURE_BRANCH + Detect branch type before spawning Coder: - **Work branches** (`feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefix): proceed on current branch. @@ -41,6 +58,9 @@ Capture `branch name` and `BASE_BRANCH` from Git agent output for use throughout ## Phase 2: Plan Synthesis +**Produces:** EXECUTION_PLAN +**Requires:** FEATURE_BRANCH + Synthesize conversation context into a structured EXECUTION_PLAN for Coder: - **If a plan exists** in conversation context (from plan mode — accepted in-session or injected after "accept and clear") → use the plan as-is. @@ -54,6 +74,9 @@ If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktre ## Phase 3: Coder Execution +**Produces:** CODER_COMMITS, PRE_CODER_SHA +**Requires:** EXECUTION_PLAN, FEATURE_BRANCH + Record git SHA before first Coder: `git rev-parse HEAD` Spawn `Agent(subagent_type="Coder")` with input variables: @@ -75,6 +98,9 @@ If Coder returns **BLOCKED**, halt the pipeline and report to user. ## Phase 4: FILES_CHANGED Detection +**Produces:** FILES_CHANGED +**Requires:** PRE_CODER_SHA + After Coder completes, detect changed files: ```bash @@ -85,6 +111,9 @@ Pass FILES_CHANGED to all quality gate agents. ## Phase 5: Quality Gates +**Produces:** GATE_RESULTS +**Requires:** FILES_CHANGED, CODER_COMMITS + Run sequentially — each gate must pass before the next: 1. `Agent(subagent_type="Validator")` (build + typecheck + lint + tests) — retry up to 2× on failure (Coder fixes between retries) @@ -98,6 +127,8 @@ If any gate exhausts retries, halt pipeline and report what passed and what fail ## Phase 6: Completion +**Requires:** GATE_RESULTS, FILES_CHANGED, CODER_COMMITS + Cleanup: delete `.docs/handoff.md` if it exists (no longer needed after pipeline completes). Report results: @@ -112,3 +143,16 @@ Report results: - **Validator fails after retries**: Report specific failures, halt pipeline - **Evaluator misalignment after retries**: Report misalignment details, let user decide next steps - **Tester QA failures after retries**: Report QA failure details, let user decide next steps + +## Phase Completion Checklist + +Before reporting results, verify every phase was announced: + +- [ ] Phase 1: Pre-flight → BASE_BRANCH, FEATURE_BRANCH captured +- [ ] Phase 2: Plan Synthesis → EXECUTION_PLAN captured +- [ ] Phase 3: Coder Execution → CODER_COMMITS, PRE_CODER_SHA captured +- [ ] Phase 4: FILES_CHANGED Detection → FILES_CHANGED captured +- [ ] Phase 5: Quality Gates → GATE_RESULTS captured (per gate: pass/fail) +- [ ] Phase 6: Completion → Results reported + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/pipeline:orch/SKILL.md b/shared/skills/pipeline:orch/SKILL.md index 5fdac85..c668bc6 100644 --- a/shared/skills/pipeline:orch/SKILL.md +++ b/shared/skills/pipeline:orch/SKILL.md @@ -22,8 +22,12 @@ Meta-orchestrator chaining implement → review → resolve with status reportin Classification statement must warn about scope: `Devflow: PIPELINE/ORCHESTRATED. This runs implement → review → resolve (15+ agents across stages).` +**Scoped nesting**: When delegating to inner orch skills (implement:orch, review:orch, resolve:orch), those skills announce their phases with a scoped prefix: `Implement > Phase 1: Pre-flight`, `Review > Phase 3: File Analysis`, etc. Pipeline:orch announces its own phases without prefix. + ## Phase 1: Implement +**Produces:** IMPLEMENT_RESULT + Load `devflow:implement:orch` via the Skill tool, then execute its full pipeline (Phases 1-6: pre-flight → plan synthesis → Coder → FILES_CHANGED detection → quality gates → completion). The quality gates are non-negotiable: Validator → Simplifier → Scrutinizer → re-Validate → Evaluator → Tester. If implementation returns **BLOCKED**: halt entire pipeline, report blocker. @@ -32,6 +36,9 @@ Cleanup: delete `.docs/handoff.md` if it exists (no longer needed before review) ## Phase 2: Status — Review Decision +**Produces:** STATUS_DECISION +**Requires:** IMPLEMENT_RESULT + Log implementation results: > "Implementation complete ({n} files changed, all quality gates passed). Proceeding to multi-agent review." @@ -39,12 +46,18 @@ Auto-proceed to Phase 3. ## Phase 3: Review +**Produces:** REVIEW_RESULT +**Requires:** IMPLEMENT_RESULT + Load `devflow:review:orch` via the Skill tool, then execute its full pipeline (Phases 1-6: pre-flight → incremental detection → file analysis → parallel reviewers (7 core + conditional) → synthesis → finalize). All 7 core reviewers (security, architecture, performance, complexity, consistency, testing, regression) are mandatory. Report review results (merge recommendation, issue counts). ## Phase 4: Status — Resolve Decision +**Produces:** RESOLVE_DECISION +**Requires:** REVIEW_RESULT + If **blocking issues found**: > Log: "Found {n} blocking issues. Auto-resolving." @@ -55,10 +68,15 @@ If **no blocking issues**: ## Phase 5: Resolve +**Produces:** RESOLVE_RESULT +**Requires:** RESOLVE_DECISION, REVIEW_RESULT + Load `devflow:resolve:orch` via the Skill tool, then execute its full pipeline (Phases 1-6: target review directory → parse issues → analyze & batch → parallel resolvers → collect & simplify → report). ## Phase 6: Summary +**Requires:** IMPLEMENT_RESULT, REVIEW_RESULT, RESOLVE_RESULT + End-to-end report: - **Implementation**: files changed, commits, quality gate results - **Review**: issue counts by severity, merge recommendation @@ -71,3 +89,16 @@ End-to-end report: - **Review finds no changes**: Skip review, report implementation only - **All issues resolved**: Report full success - **Partial resolution**: Report what was fixed and what remains + +## Phase Completion Checklist + +Before reporting summary, verify every phase was announced: + +- [ ] Phase 1: Implement → IMPLEMENT_RESULT captured +- [ ] Phase 2: Status — Review Decision → STATUS_DECISION logged +- [ ] Phase 3: Review → REVIEW_RESULT captured +- [ ] Phase 4: Status — Resolve Decision → RESOLVE_DECISION logged +- [ ] Phase 5: Resolve → RESOLVE_RESULT captured (or skipped: no blocking issues — announce skip) +- [ ] Phase 6: Summary → SUMMARY_REPORT presented + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/plan:orch/SKILL.md b/shared/skills/plan:orch/SKILL.md index 1f38e36..4b8b8ce 100644 --- a/shared/skills/plan:orch/SKILL.md +++ b/shared/skills/plan:orch/SKILL.md @@ -35,8 +35,30 @@ If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktre --- +## Continuation Detection + +Before starting the full pipeline, check for prior planning context: + +- **Existing artifact**: `.docs/design/` contains a file matching the current topic +- **Accepted plan in session**: A structured plan was already presented and accepted in this conversation + +**Override**: If the user explicitly requests a fresh plan ("start from scratch", "ignore the old plan", "new approach"), execute the full pipeline regardless of prior artifacts. + +If EITHER condition is true (and no override) → execute **Refinement Path** instead of Phases 0-8: + +1. Read the existing plan (disk artifact or conversation context) +2. Run Phase 2 (Explore) targeting only areas affected by the new request +3. Update the plan with changes, preserving unchanged sections +4. Run Phase 6 (Design Review Lite) on updated sections only +5. Present the delta (what changed and why) +6. Proceed to Phase 8 (Persist) if updated plan is substantial + +If NEITHER condition is met → proceed with the full pipeline below. + ## Phase 0: Load Knowledge Index +**Produces:** KNOWLEDGE_CONTEXT + Before spawning any agents, load the knowledge index for the current worktree: ```bash @@ -47,6 +69,8 @@ This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT` ## Phase 0.5: Requirements Discovery +**Produces:** CONSTRAINED_PROBLEM + Before committing to an approach, surface ambiguity through focused Socratic questioning. **Skip when** (semantic assessment, not word count): @@ -82,6 +106,9 @@ If the user says "skip", "just proceed", or signals impatience — skip remainin ## Phase 1: Orient +**Produces:** ORIENT_OUTPUT +**Requires:** CONSTRAINED_PROBLEM (or original prompt if Phase 0.5 skipped) + Spawn `Agent(subagent_type="Skimmer")` to get codebase overview relevant to the planning question: - Existing patterns and conventions in the affected area @@ -91,6 +118,9 @@ Spawn `Agent(subagent_type="Skimmer")` to get codebase overview relevant to the ## Phase 2: Explore +**Produces:** EXPLORE_OUTPUT +**Requires:** ORIENT_OUTPUT, KNOWLEDGE_CONTEXT + Based on Skimmer findings, spawn 2-3 `Agent(subagent_type="Explore")` agents **in a single message** (parallel execution): - **Integration explorer**: Examine integration points — APIs, shared types, module boundaries the plan must respect @@ -103,6 +133,9 @@ Adjust explorer focus based on the specific planning question. ## Phase 3: Gap Analysis Lite +**Produces:** GAP_OUTPUT +**Requires:** EXPLORE_OUTPUT, ORIENT_OUTPUT, KNOWLEDGE_CONTEXT + Spawn 2 `Agent(subagent_type="Designer")` agents **in a single message** (parallel execution): ``` @@ -131,6 +164,9 @@ Follow devflow:apply-knowledge for KNOWLEDGE_CONTEXT." ## Phase 4: Synthesize +**Produces:** SYNTHESIS_OUTPUT +**Requires:** GAP_OUTPUT, EXPLORE_OUTPUT + Spawn `Agent(subagent_type="Synthesizer")` combining gap analysis and explore outputs: ``` @@ -142,6 +178,9 @@ Combine gap findings with exploration context into blocking vs. should-address c ## Phase 5: Plan +**Produces:** PLAN_OUTPUT +**Requires:** ORIENT_OUTPUT, EXPLORE_OUTPUT, SYNTHESIS_OUTPUT, KNOWLEDGE_CONTEXT + Spawn `Agent(subagent_type="Plan")` with all findings: - Design implementation approach with file-level specificity @@ -152,6 +191,9 @@ Spawn `Agent(subagent_type="Plan")` with all findings: ## Phase 6: Design Review Lite +**Produces:** REVIEW_NOTES +**Requires:** PLAN_OUTPUT + Main session reviews the plan inline using the loaded `devflow:design-review` skill: - Check for N+1 query implications @@ -165,6 +207,8 @@ Note findings directly in the plan presentation. This is inline review — no ag ## Phase 7: Present +**Requires:** PLAN_OUTPUT, SYNTHESIS_OUTPUT, REVIEW_NOTES + Present plan to user with: - Implementation approach (file-level) - Gap analysis findings (from Phase 4 synthesis) @@ -175,6 +219,8 @@ Use AskUserQuestion for any ambiguous design choices that need user input before ## Phase 8: Persist +**Requires:** PLAN_OUTPUT + If the plan is substantial (>10 implementation steps or HIGH/CRITICAL context risk): - Write to `.docs/design/{topic-slug}.{YYYY-MM-DD_HHMM}.md` with YAML frontmatter - Note the artifact path in the output @@ -196,3 +242,20 @@ Structured plan ready to feed into IMPLEMENT/ORCHESTRATED if user proceeds: - Risks and mitigations - Open questions (if any) - Design artifact path (if written to disk) + +## Phase Completion Checklist + +Before presenting output, verify every phase was announced: + +- [ ] Phase 0: Load Knowledge Index → KNOWLEDGE_CONTEXT captured +- [ ] Phase 0.5: Requirements Discovery → CONSTRAINED_PROBLEM captured (or skipped with stated reason) +- [ ] Phase 1: Orient → ORIENT_OUTPUT captured +- [ ] Phase 2: Explore → EXPLORE_OUTPUT captured +- [ ] Phase 3: Gap Analysis Lite → GAP_OUTPUT captured +- [ ] Phase 4: Synthesize → SYNTHESIS_OUTPUT captured +- [ ] Phase 5: Plan → PLAN_OUTPUT captured +- [ ] Phase 6: Design Review Lite → REVIEW_NOTES captured +- [ ] Phase 7: Present → Output delivered to user +- [ ] Phase 8: Persist → Artifact written (or skipped with stated reason) + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/resolve:orch/SKILL.md b/shared/skills/resolve:orch/SKILL.md index 5989b6e..7515649 100644 --- a/shared/skills/resolve:orch/SKILL.md +++ b/shared/skills/resolve:orch/SKILL.md @@ -22,6 +22,8 @@ This is a lightweight variant of `/resolve` for ambient mode. Excluded: pitfall ## Phase 1: Target Review Directory +**Produces:** REVIEW_DIR, BRANCH_SLUG + Find the latest timestamped directory under `.docs/reviews/` that: 1. Contains a `review-summary.md` (has been reviewed) 2. Does NOT contain a `resolution-summary.md` (hasn't been resolved yet) @@ -35,10 +37,16 @@ Extract branch slug from the directory path. handled by Phase 1 here). Same content as resolve.md Step 0d. --> ## Phase 1.5: Load Project Knowledge +**Produces:** KNOWLEDGE_CONTEXT +**Requires:** REVIEW_DIR + Run `node scripts/hooks/lib/knowledge-context.cjs index "{worktree}"` to produce a compact index of active ADR/PF entries from `decisions.md` and `pitfalls.md`, with Deprecated/Superseded entries already stripped. Falls back to `(none)` when both files are absent or all entries are filtered. Pass `KNOWLEDGE_CONTEXT` to every Resolver agent in Phase 4. Resolver agents use `devflow:apply-knowledge` to Read full entry bodies on demand — no fan-out of the full corpus. ## Phase 2: Parse Issues +**Produces:** ISSUES +**Requires:** REVIEW_DIR + Read all `{focus}.md` files in the timestamped directory (exclude `review-summary.md` and `resolution-summary.md`). Extract **ALL** issues from all categories and severities, including Suggestions. @@ -49,6 +57,9 @@ If no actionable issues found: "Review is clean — no issues to resolve." → s ## Phase 3: Analyze & Batch +**Produces:** BATCHES +**Requires:** ISSUES + Group issues by file/function for efficient resolution: - Issues in the same file → same batch - Issues with cross-file dependencies → same batch @@ -58,6 +69,9 @@ Determine execution: batches with no shared files can run in parallel. ## Phase 4: Resolve (Parallel) +**Produces:** RESOLUTION_RESULTS +**Requires:** BATCHES, KNOWLEDGE_CONTEXT, BRANCH_SLUG + Spawn `Agent(subagent_type="Resolver")` agents — one per batch, parallel where possible. Each receives: @@ -73,6 +87,9 @@ Resolvers follow a 3-tier risk approach: ## Phase 5: Collect & Simplify +**Produces:** SIMPLIFICATION_RESULTS +**Requires:** RESOLUTION_RESULTS + Aggregate results from all Resolver agents: - Count: fixed, false positives, deferred @@ -80,6 +97,8 @@ Spawn `Agent(subagent_type="Simplifier")` on all files modified by Resolvers. ## Phase 6: Report +**Requires:** RESOLUTION_RESULTS, SIMPLIFICATION_RESULTS, REVIEW_DIR + Write `resolution-summary.md` to the same timestamped review directory. The report includes a `## Knowledge Citations` section at the top (before Statistics) listing all unique `applies ADR-NNN` and `avoids PF-NNN` references extracted from Resolver Reasoning columns. Omit the section entirely if no citations were made. @@ -97,3 +116,17 @@ Report to user: - **All issues false positive**: Report findings, write resolution-summary noting no changes needed - **Resolver BLOCKED**: Report which batch blocked, continue with remaining - **Simplifier fails**: Resolution still valid — report that simplification was skipped + +## Phase Completion Checklist + +Before reporting results, verify every phase was announced: + +- [ ] Phase 1: Target Review Directory → REVIEW_DIR captured +- [ ] Phase 1.5: Load Project Knowledge → KNOWLEDGE_CONTEXT captured +- [ ] Phase 2: Parse Issues → ISSUES captured (or stopped: no actionable issues) +- [ ] Phase 3: Analyze & Batch → BATCHES captured +- [ ] Phase 4: Resolve → RESOLUTION_RESULTS captured per batch +- [ ] Phase 5: Collect & Simplify → SIMPLIFICATION_RESULTS captured +- [ ] Phase 6: Report → resolution-summary.md written + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/review:orch/SKILL.md b/shared/skills/review:orch/SKILL.md index 6e33ae5..3577e02 100644 --- a/shared/skills/review:orch/SKILL.md +++ b/shared/skills/review:orch/SKILL.md @@ -19,8 +19,12 @@ This is a lightweight variant of `/code-review` for ambient ORCHESTRATED mode. E --- +**Continuation**: Phase 2 handles incremental detection via `.last-review-head` — no separate continuation path needed. + ## Phase 1: Pre-flight +**Produces:** BRANCH_INFO, PR_INFO + Spawn `Agent(subagent_type="Git")` with action `ensure-pr-ready`: - Extract: branch, base_branch, branch_slug, pr_number - If BLOCKED (detached HEAD, no commits ahead of base): halt with message @@ -29,6 +33,9 @@ Determine base branch: use PR target if PR exists, otherwise `main`/`master`. ## Phase 2: Incremental Detection +**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP +**Requires:** BRANCH_INFO + Check `.docs/reviews/{branch_slug}/.last-review-head`: - If file exists and SHA matches HEAD: "No new commits since last review. Nothing to do." → stop - If file exists and SHA differs: set `DIFF_RANGE={sha}...HEAD` (incremental) @@ -39,6 +46,9 @@ Create directory: `mkdir -p .docs/reviews/{branch_slug}/{timestamp}` ## Phase 2b: Load Knowledge Index +**Produces:** KNOWLEDGE_CONTEXT +**Requires:** REVIEW_DIR + After incremental detection, load the knowledge index: ```bash @@ -49,6 +59,9 @@ This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT` ## Phase 3: File Analysis +**Produces:** REVIEWER_LIST +**Requires:** DIFF_RANGE + Run `git diff --name-only {DIFF_RANGE}` to get changed files. Detect conditional reviewers from file types: @@ -69,6 +82,9 @@ Detect conditional reviewers from file types: ## Phase 4: Reviews (Parallel) +**Produces:** REVIEWER_OUTPUTS +**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, KNOWLEDGE_CONTEXT, REVIEWER_LIST + Spawn all reviewers in a single message (parallel execution): **7 core reviewers** (always): @@ -86,6 +102,8 @@ Each reviewer receives: ## Phase 5: Synthesis (Parallel) +**Requires:** REVIEWER_OUTPUTS, REVIEW_DIR, PR_INFO + After all reviewers complete, spawn in parallel: 1. `Agent(subagent_type="Git")` with action `comment-pr` — post review summary as PR comment (deduplicate: check existing comments first) @@ -93,6 +111,8 @@ After all reviewers complete, spawn in parallel: ## Phase 6: Finalize +**Requires:** BRANCH_INFO, REVIEW_DIR + Write HEAD SHA to `.docs/reviews/{branch_slug}/.last-review-head` for next incremental review. Report to user: @@ -107,3 +127,17 @@ Report to user: - **No changed files**: "No changes to review." → stop - **Reviewer fails**: Report which reviewer failed, continue with remaining - **Synthesizer fails**: Reports are still on disk — user can read them directly + +## Phase Completion Checklist + +Before reporting results, verify every phase was announced: + +- [ ] Phase 1: Pre-flight → BRANCH_INFO, PR_INFO captured +- [ ] Phase 2: Incremental Detection → DIFF_RANGE, REVIEW_DIR, TIMESTAMP captured +- [ ] Phase 2b: Load Knowledge Index → KNOWLEDGE_CONTEXT captured +- [ ] Phase 3: File Analysis → REVIEWER_LIST captured +- [ ] Phase 4: Reviews → REVIEWER_OUTPUTS written to disk +- [ ] Phase 5: Synthesis → review-summary.md written +- [ ] Phase 6: Finalize → .last-review-head updated, results reported + +If any phase is unchecked, execute it before proceeding. diff --git a/shared/skills/router/SKILL.md b/shared/skills/router/SKILL.md index b8a1011..845b804 100644 --- a/shared/skills/router/SKILL.md +++ b/shared/skills/router/SKILL.md @@ -13,6 +13,16 @@ GUIDED: work directly in main session. Spawn Simplifier after code changes. - GUIDED PLAN: spawn Skimmer for orientation, then plan directly. ORCHESTRATED: follow the loaded orchestration skill's pipeline. +## Phase Protocol + +All ORCHESTRATED pipelines follow this protocol: + +1. **Announce** — Before executing each phase, output: `Phase N: {name}`. No phase may execute without this announcement. Skipping the announcement and doing the work anyway is a protocol violation. +2. **Produce** — Each phase declares what it `Produces:`. Capture that output by name. Subsequent phases reference it via `Requires:`. +3. **No silent skips** — If a phase's preconditions are not met (e.g., no issues found), announce the phase, state why it is being skipped, and move to the next phase. The announcement must still appear. +4. **Verify** — Before presenting final output, check the skill's Phase Completion Checklist. Every phase must show as announced. If any phase was missed, execute it before proceeding. +5. **Scoped nesting** — When a pipeline delegates to another orchestration skill (e.g., pipeline:orch → implement:orch), the inner skill's phases use a scoped prefix: `{Outer} > Phase N: {name}` (e.g., `Implement > Phase 1: Pre-flight`). + ## GUIDED | Intent | Skills | diff --git a/tests/ambient.test.ts b/tests/ambient.test.ts index 07eacf4..8ad70c1 100644 --- a/tests/ambient.test.ts +++ b/tests/ambient.test.ts @@ -693,6 +693,11 @@ describe('preamble drift detection', () => { expect(routerContent).toContain('DEBUG'); expect(routerContent).toContain('PLAN'); expect(routerContent).toContain('REVIEW'); + + // Must contain Phase Protocol section + expect(routerContent).toContain('## Phase Protocol'); + expect(routerContent).toContain('Announce'); + expect(routerContent).toContain('No silent skips'); }); it('session-start-classification hook reads classification-rules.md', async () => { @@ -702,3 +707,85 @@ describe('preamble drift detection', () => { expect(hookContent).toContain('classification-rules.md'); }); }); + +describe('phase protocol structural validation', () => { + const orchSkills = [ + 'plan:orch', + 'implement:orch', + 'review:orch', + 'resolve:orch', + 'debug:orch', + 'explore:orch', + 'pipeline:orch', + ]; + + const sharedSkillsDir = path.resolve(__dirname, '../shared/skills'); + + it('every orch skill has a Phase Completion Checklist', async () => { + for (const skill of orchSkills) { + const content = await fs.readFile( + path.join(sharedSkillsDir, skill, 'SKILL.md'), + 'utf-8', + ); + expect(content, `${skill} missing Phase Completion Checklist`).toContain( + '## Phase Completion Checklist', + ); + } + }); + + it('every orch skill has Produces: annotations', async () => { + for (const skill of orchSkills) { + const content = await fs.readFile( + path.join(sharedSkillsDir, skill, 'SKILL.md'), + 'utf-8', + ); + expect(content, `${skill} missing Produces: annotations`).toContain( + '**Produces:**', + ); + } + }); + + it('every orch skill has Requires: annotations', async () => { + for (const skill of orchSkills) { + const content = await fs.readFile( + path.join(sharedSkillsDir, skill, 'SKILL.md'), + 'utf-8', + ); + expect(content, `${skill} missing Requires: annotations`).toContain( + '**Requires:**', + ); + } + }); + + it('plan:orch and implement:orch have Continuation Detection', async () => { + for (const skill of ['plan:orch', 'implement:orch']) { + const content = await fs.readFile( + path.join(sharedSkillsDir, skill, 'SKILL.md'), + 'utf-8', + ); + expect(content, `${skill} missing Continuation Detection`).toContain( + '## Continuation Detection', + ); + } + }); + + it('checklist item count matches phase count in each orch skill', async () => { + for (const skill of orchSkills) { + const content = await fs.readFile( + path.join(sharedSkillsDir, skill, 'SKILL.md'), + 'utf-8', + ); + + // Count phase headings (## Phase N or ### Phase N — digit distinguishes from ## Phase Completion Checklist) + const phaseHeadings = content.match(/^#{2,3}\s+Phase\s+\d/gm) ?? []; + + // Count checklist items (- [ ] Phase) + const checklistItems = content.match(/^- \[ \] Phase/gm) ?? []; + + expect( + checklistItems.length, + `${skill}: ${checklistItems.length} checklist items but ${phaseHeadings.length} phases`, + ).toBe(phaseHeadings.length); + } + }); +}); From a1b8f94f892aff97006a212f2793b4575586382e Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Wed, 22 Apr 2026 17:19:41 +0300 Subject: [PATCH 2/4] refactor(tests): dynamic orch skill discovery + CLAUDE.md convention note Replace hardcoded orchSkills array with fs.readdir discovery of *:orch directories so new orch skills are automatically validated by phase protocol structural tests. Add Phase Protocol convention bullet to CLAUDE.md Key Conventions > Skills section. --- CLAUDE.md | 1 + tests/ambient.test.ts | 23 +++++++++-------------- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f60124f..9cfa12b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -167,6 +167,7 @@ Working memory files live in a dedicated `.memory/` directory: - Target: ~120-150 lines per SKILL.md with progressive disclosure to `references/` - Skills default to read-only (`allowed-tools: Read, Grep, Glob`); exceptions: git/review skills add `Bash`, interactive skills add `AskUserQuestion`, `quality-gates` adds `Write` for state persistence, and `router` omits `allowed-tools` entirely (unrestricted, as the main-session orchestrator) - All skills live in `shared/skills/` — add to plugin `plugin.json` `skills` array, then `npm run build` +- Orchestration skills (`*:orch`) follow the Phase Protocol (defined in `router/SKILL.md`) — each phase needs `**Produces:**`/`**Requires:**` annotations and a `## Phase Completion Checklist` ### Agents diff --git a/tests/ambient.test.ts b/tests/ambient.test.ts index 8ad70c1..967b90b 100644 --- a/tests/ambient.test.ts +++ b/tests/ambient.test.ts @@ -709,20 +709,15 @@ describe('preamble drift detection', () => { }); describe('phase protocol structural validation', () => { - const orchSkills = [ - 'plan:orch', - 'implement:orch', - 'review:orch', - 'resolve:orch', - 'debug:orch', - 'explore:orch', - 'pipeline:orch', - ]; - const sharedSkillsDir = path.resolve(__dirname, '../shared/skills'); + async function discoverOrchSkills(): Promise { + const entries = await fs.readdir(sharedSkillsDir); + return entries.filter(e => e.endsWith(':orch')).sort(); + } + it('every orch skill has a Phase Completion Checklist', async () => { - for (const skill of orchSkills) { + for (const skill of await discoverOrchSkills()) { const content = await fs.readFile( path.join(sharedSkillsDir, skill, 'SKILL.md'), 'utf-8', @@ -734,7 +729,7 @@ describe('phase protocol structural validation', () => { }); it('every orch skill has Produces: annotations', async () => { - for (const skill of orchSkills) { + for (const skill of await discoverOrchSkills()) { const content = await fs.readFile( path.join(sharedSkillsDir, skill, 'SKILL.md'), 'utf-8', @@ -746,7 +741,7 @@ describe('phase protocol structural validation', () => { }); it('every orch skill has Requires: annotations', async () => { - for (const skill of orchSkills) { + for (const skill of await discoverOrchSkills()) { const content = await fs.readFile( path.join(sharedSkillsDir, skill, 'SKILL.md'), 'utf-8', @@ -770,7 +765,7 @@ describe('phase protocol structural validation', () => { }); it('checklist item count matches phase count in each orch skill', async () => { - for (const skill of orchSkills) { + for (const skill of await discoverOrchSkills()) { const content = await fs.readFile( path.join(sharedSkillsDir, skill, 'SKILL.md'), 'utf-8', From f15f72abfae26a292371dc8f8dd4c88858f38e4e Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Thu, 23 Apr 2026 00:11:14 +0300 Subject: [PATCH 3/4] feat(commands): add Produces/Requires annotations to all slash commands MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add explicit data-flow annotations to 12 command files (7 base + 5 teams variants) aligning them with the Phase Protocol convention shipped for orchestration skills. Each phase/step heading now documents its checkpoint variables — what it produces and what it requires — making data contracts visible and consistent across both execution paths. Add per-phase correspondence tests to ambient.test.ts that dynamically discover all command files, detect container headings, and verify every leaf phase has at least one annotation. --- .../commands/audit-claude.md | 7 ++ .../commands/code-review-teams.md | 25 +++++++ .../commands/code-review.md | 21 ++++++ plugins/devflow-debug/commands/debug-teams.md | 19 +++++ plugins/devflow-debug/commands/debug.md | 13 ++++ .../commands/implement-teams.md | 28 ++++++++ .../devflow-implement/commands/implement.md | 28 ++++++++ plugins/devflow-plan/commands/plan-teams.md | 40 +++++++++++ plugins/devflow-plan/commands/plan.md | 40 +++++++++++ .../devflow-resolve/commands/resolve-teams.md | 33 +++++++++ plugins/devflow-resolve/commands/resolve.md | 33 +++++++++ .../commands/self-review.md | 13 ++++ tests/ambient.test.ts | 69 +++++++++++++++++++ 13 files changed, 369 insertions(+) diff --git a/plugins/devflow-audit-claude/commands/audit-claude.md b/plugins/devflow-audit-claude/commands/audit-claude.md index a991b6b..fa8407c 100644 --- a/plugins/devflow-audit-claude/commands/audit-claude.md +++ b/plugins/devflow-audit-claude/commands/audit-claude.md @@ -19,6 +19,8 @@ Audit CLAUDE.md files against Anthropic's best practices. Finds oversized files, ### Phase 1: Discovery +**Produces:** CLAUDE_FILES + Find all CLAUDE.md files to audit: ```bash @@ -36,6 +38,9 @@ If a specific path argument was provided, use only that file. ### Phase 2: Analysis +**Produces:** AUDIT_RESULTS +**Requires:** CLAUDE_FILES + For each discovered file, spawn a `claude-md-auditor` agent: ``` @@ -53,6 +58,8 @@ Run agents in parallel when multiple files are found. ### Phase 3: Report +**Requires:** AUDIT_RESULTS + Combine all agent outputs into a single report: ```markdown diff --git a/plugins/devflow-code-review/commands/code-review-teams.md b/plugins/devflow-code-review/commands/code-review-teams.md index afb19c7..0a0eea3 100644 --- a/plugins/devflow-code-review/commands/code-review-teams.md +++ b/plugins/devflow-code-review/commands/code-review-teams.md @@ -21,6 +21,8 @@ Run a comprehensive code review of the current branch by spawning a review team #### Step 0a: Discover Worktrees +**Produces:** WORKTREES + 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm: - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list @@ -31,6 +33,9 @@ Run a comprehensive code review of the current branch by spawning a review team #### Step 0b: Per-Worktree Pre-Flight (Git Agent) +**Produces:** BRANCH_INFO, PR_INFO +**Requires:** WORKTREES + For each reviewable worktree, spawn Git agent: ``` @@ -49,6 +54,9 @@ In multi-worktree mode, spawn all pre-flight agents **in a single message** (par #### Step 0c: Incremental Detection & Timestamp Setup +**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP +**Requires:** BRANCH_INFO + For each worktree: 1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`). @@ -64,6 +72,9 @@ For each worktree: ### Phase 1: Analyze Changed Files +**Produces:** REVIEWER_LIST +**Requires:** DIFF_RANGE + Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews: | Condition | Adds Perspective | @@ -84,6 +95,8 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio ### Phase 1b: Load Knowledge Index +**Produces:** KNOWLEDGE_CONTEXT + Load the knowledge index for the current worktree before spawning the review team: ```bash @@ -94,6 +107,9 @@ This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT` ### Phase 2: Spawn Review Team +**Produces:** REVIEWER_OUTPUTS +**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, KNOWLEDGE_CONTEXT, REVIEWER_LIST + **Per worktree**, create an agent team for adversarial review. Always include 4 core perspectives; conditionally add more based on Phase 1 analysis. **Note**: In multi-worktree mode, process worktrees sequentially for Agent Teams (one team per session constraint). Each worktree gets its own team lifecycle: create → debate → synthesize → cleanup. @@ -166,6 +182,8 @@ Spawn review teammates. For each teammate, compose a self-contained prompt using ### Phase 2b: Debate Round +**Requires:** REVIEWER_OUTPUTS + After all reviewers complete initial analysis, lead initiates adversarial debate: Lead initiates debate via broadcast: @@ -196,6 +214,9 @@ Reviewers message each other directly using SendMessage: ### Phase 3: Synthesis and PR Comments +**Produces:** REVIEW_SUMMARY +**Requires:** REVIEWER_OUTPUTS, REVIEW_DIR, PR_INFO + **WAIT** for debate to complete, then lead produces outputs. Spawn 2 agents **in a single message**: @@ -240,6 +261,8 @@ Check for existing inline comments at same file:line before creating new ones." ### Phase 4: Write Review Head Marker +**Requires:** BRANCH_INFO, REVIEW_DIR + Per worktree, after successful completion: 1. Write current HEAD SHA to `{worktree_path}/.docs/reviews/{branch-slug}/.last-review-head` @@ -248,6 +271,8 @@ Per worktree, after successful completion: ### Phase 5: Cleanup and Report +**Requires:** REVIEW_SUMMARY + Shut down all review teammates explicitly: ``` diff --git a/plugins/devflow-code-review/commands/code-review.md b/plugins/devflow-code-review/commands/code-review.md index 84bb6d5..9b6efff 100644 --- a/plugins/devflow-code-review/commands/code-review.md +++ b/plugins/devflow-code-review/commands/code-review.md @@ -28,6 +28,8 @@ Run a comprehensive code review of the current branch by spawning parallel revie #### Step 0a: Discover Worktrees +**Produces:** WORKTREES + 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm: - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list @@ -38,6 +40,9 @@ Run a comprehensive code review of the current branch by spawning parallel revie #### Step 0b: Per-Worktree Pre-Flight (Git Agent) +**Produces:** BRANCH_INFO, PR_INFO +**Requires:** WORKTREES + For each reviewable worktree, spawn Git agent: ``` @@ -56,6 +61,9 @@ In multi-worktree mode, spawn all pre-flight agents **in a single message** (par #### Step 0c: Incremental Detection & Timestamp Setup +**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP +**Requires:** BRANCH_INFO + For each worktree: 1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`). @@ -71,6 +79,9 @@ For each worktree: ### Phase 1: Analyze Changed Files +**Produces:** REVIEWER_LIST +**Requires:** DIFF_RANGE + Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews: | Condition | Adds Review | @@ -91,6 +102,8 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio ### Phase 1b: Load Knowledge Index +**Produces:** KNOWLEDGE_CONTEXT + While file analysis runs (or just before spawning reviewers), load the knowledge index for the current worktree: ```bash @@ -101,6 +114,9 @@ This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT` ### Phase 2: Run Reviews (Parallel) +**Produces:** REVIEWER_OUTPUTS +**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, KNOWLEDGE_CONTEXT, REVIEWER_LIST + Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add more based on changed file types: | Focus | Always | Pattern Skill | @@ -141,6 +157,9 @@ In multi-worktree mode, process worktrees **sequentially** (one worktree at a ti ### Phase 3: Synthesis (Parallel) +**Produces:** REVIEW_SUMMARY +**Requires:** REVIEWER_OUTPUTS, REVIEW_DIR, PR_INFO + **WAIT** for Phase 2, then spawn agents per worktree **in a single message**: **Git Agent (PR Comments)** per worktree: @@ -169,6 +188,8 @@ Output: {worktree_path}/.docs/reviews/{branch-slug}/{timestamp}/review-summary.m ### Phase 4: Write Review Head Marker & Report +**Requires:** BRANCH_INFO, REVIEW_DIR + Per worktree, after successful completion: 1. Write current HEAD SHA to `{worktree_path}/.docs/reviews/{branch-slug}/.last-review-head` 2. Display results from all agents: diff --git a/plugins/devflow-debug/commands/debug-teams.md b/plugins/devflow-debug/commands/debug-teams.md index 38e32ed..961271d 100644 --- a/plugins/devflow-debug/commands/debug-teams.md +++ b/plugins/devflow-debug/commands/debug-teams.md @@ -25,6 +25,8 @@ Investigate bugs by spawning a team of agents, each pursuing a different hypothe ### Phase 1: Load Knowledge Index (Orchestrator-Local) +**Produces:** KNOWLEDGE_CONTEXT + Before hypothesizing, load the knowledge index: ```bash @@ -35,6 +37,9 @@ The orchestrator uses `KNOWLEDGE_CONTEXT` locally when generating hypotheses (Ph ### Phase 2: Context Gathering +**Produces:** HYPOTHESES, BUG_CONTEXT +**Requires:** KNOWLEDGE_CONTEXT + If `$ARGUMENTS` starts with `#`, fetch the GitHub issue: ``` @@ -51,6 +56,8 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible ### Phase 3: Spawn Investigation Team +**Requires:** HYPOTHESES, BUG_CONTEXT + Create an agent team with one investigator per hypothesis: ``` @@ -111,6 +118,9 @@ Spawn investigator teammates with self-contained prompts: ### Phase 4: Investigation +**Produces:** INVESTIGATION_RESULTS +**Requires:** HYPOTHESES + Teammates investigate in parallel: - Read relevant source files - Trace execution paths @@ -120,6 +130,8 @@ Teammates investigate in parallel: ### Phase 5: Adversarial Debate +**Requires:** INVESTIGATION_RESULTS + Lead initiates debate via broadcast: ``` @@ -147,6 +159,9 @@ Teammates challenge each other directly using SendMessage: ### Phase 6: Convergence +**Produces:** CONVERGENCE_RESULTS +**Requires:** INVESTIGATION_RESULTS + After debate (max 2 rounds), lead collects results: ``` @@ -159,6 +174,8 @@ Lead broadcast: ### Phase 7: Cleanup +**Requires:** CONVERGENCE_RESULTS + Shut down all investigator teammates explicitly: ``` @@ -172,6 +189,8 @@ Verify TeamDelete succeeded. If failed, retry once after 5s. If retry fails, HAL ### Phase 8: Report +**Requires:** CONVERGENCE_RESULTS + Lead produces final report: ```markdown diff --git a/plugins/devflow-debug/commands/debug.md b/plugins/devflow-debug/commands/debug.md index 18b6236..12ec57e 100644 --- a/plugins/devflow-debug/commands/debug.md +++ b/plugins/devflow-debug/commands/debug.md @@ -33,6 +33,8 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes ### Phase 1: Load Knowledge Index (Orchestrator-Local) +**Produces:** KNOWLEDGE_CONTEXT + Before hypothesizing, load the knowledge index: ```bash @@ -43,6 +45,9 @@ The orchestrator uses `KNOWLEDGE_CONTEXT` locally when generating hypotheses (Ph ### Phase 2: Context Gathering +**Produces:** HYPOTHESES, BUG_CONTEXT +**Requires:** KNOWLEDGE_CONTEXT + If `$ARGUMENTS` starts with `#`, fetch the GitHub issue: ``` @@ -59,6 +64,9 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible ### Phase 3: Investigate (Parallel) +**Produces:** INVESTIGATION_RESULTS +**Requires:** HYPOTHESES + Spawn one Explore agent per hypothesis in a **single message** (parallel execution): ``` @@ -102,6 +110,9 @@ Focus area: {specific code area, mechanism, or condition} ### Phase 4: Synthesize +**Produces:** ROOT_CAUSE_SYNTHESIS +**Requires:** INVESTIGATION_RESULTS + Once all investigators return, spawn a Synthesizer agent to aggregate findings: ``` @@ -120,6 +131,8 @@ Instructions: ### Phase 5: Report +**Requires:** ROOT_CAUSE_SYNTHESIS + Produce the final report: ```markdown diff --git a/plugins/devflow-implement/commands/implement-teams.md b/plugins/devflow-implement/commands/implement-teams.md index 390aef2..915e3f2 100644 --- a/plugins/devflow-implement/commands/implement-teams.md +++ b/plugins/devflow-implement/commands/implement-teams.md @@ -29,6 +29,8 @@ Orchestrate a single task through implementation by spawning specialized agent t ### Phase 1: Setup +**Produces:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN + Record the current branch name as `BASE_BRANCH` - this will be the PR target. Spawn Git agent to set up task environment. The Git agent derives the branch name automatically from the issue or task description: @@ -60,6 +62,9 @@ Return the branch setup summary." ### Phase 2: Implement +**Produces:** CODER_OUTPUT, FILES_CHANGED +**Requires:** TASK_ID, BASE_BRANCH, EXECUTION_PLAN + Based on Setup context (plan document, issue body, or conversation context), use the three-strategy framework: **Strategy Selection**: @@ -157,6 +162,9 @@ DOMAIN: {subtask 2 domain}" ### Phase 3: Validate +**Produces:** VALIDATION_RESULT +**Requires:** FILES_CHANGED + After Coder completes, spawn Validator to verify correctness: ``` @@ -187,6 +195,9 @@ Run build, typecheck, lint, test. Report pass/fail with failure details." ### Phase 4: Simplify +**Produces:** SIMPLIFIER_OUTPUT +**Requires:** FILES_CHANGED + After validation passes, spawn Simplifier to polish the code: ``` @@ -199,6 +210,9 @@ Focus on code modified by Coder, apply project standards, enhance clarity" ### Phase 5: Self-Review +**Produces:** SCRUTINIZER_OUTPUT +**Requires:** FILES_CHANGED + After Simplifier completes, spawn Scrutinizer as final quality gate: ``` @@ -212,6 +226,9 @@ If Scrutinizer returns BLOCKED, report to user and halt. ### Phase 6: Re-Validate (if Scrutinizer made changes) +**Produces:** REVALIDATION_RESULT +**Requires:** SCRUTINIZER_OUTPUT + If Scrutinizer made code changes (status: FIXED), spawn Validator to verify: ``` @@ -227,6 +244,9 @@ Verify Scrutinizer's fixes didn't break anything." ### Phase 7: Evaluator↔Coder Dialogue +**Produces:** ALIGNMENT_RESULT +**Requires:** FILES_CHANGED, EXECUTION_PLAN + After Scrutinizer passes (and re-validation if needed), check alignment using direct dialogue: Create a mini-team for alignment validation: @@ -318,6 +338,9 @@ Step 3: GATE — Verify TeamDelete succeeded ### Phase 8: QA Testing +**Produces:** QA_RESULT +**Requires:** FILES_CHANGED, EXECUTION_PLAN + After Evaluator passes, spawn Tester for scenario-based acceptance testing (standalone agent, not a teammate — testing is sequential, not debate): ``` @@ -357,12 +380,17 @@ Design and execute scenario-based acceptance tests. Report PASS or FAIL with evi ### Phase 9: Create PR +**Produces:** PR_URL +**Requires:** BASE_BRANCH, TASK_ID + **For SEQUENTIAL_CODERS or PARALLEL_CODERS**: The last sequential Coder (with CREATE_PR: true) handles PR creation. For parallel coders, create unified PR using `devflow:git` skill patterns. Push branch and run `gh pr create` with comprehensive description, targeting `BASE_BRANCH`. **For SINGLE_CODER**: PR is created by the Coder agent (CREATE_PR: true). ### Phase 10: Report +**Requires:** VALIDATION_RESULT, ALIGNMENT_RESULT, QA_RESULT, PR_URL + Display completion summary with phase status, PR info, and next steps.