@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-implementation/skills/workflow-execute-phase/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: workflow-execute-phase
+description: "Use when a planned .planning phase needs implementation, dependency-aware task execution, progress tracking, and verification evidence."
+---
+
+## Legacy Command Metadata
+
+Original slash-command metadata retained only as workflow invocation guidance.
+
+```yaml
+argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive]"
+user-invocable: true
+pattern: pipeline
+resumable: true
+state-key: phase-execution
+```
+
+<objective>
+Execute all plans in a phase using wave-based parallel execution.
+
+Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
+
+Optional wave filter:
+- `--wave N` executes only Wave `N` for pacing, quota management, or staged rollout
+- phase verification/completion still only happens when no incomplete plans remain after the selected wave finishes
+
+Flag handling rule:
+- The optional flags documented below are available behaviors, not implied active behaviors
+- A flag is active only when its literal token appears in `$ARGUMENTS`
+- If a documented flag is absent from `$ARGUMENTS`, treat it as inactive
+
+Context budget: ~15% orchestrator, 100% fresh per subagent.
+</objective>
+
+<execution_context>
+references/execute-phase.md
+references/ui-brand.md
+</execution_context>
+
+<runtime_note>
+</runtime_note>
+
+<context>
+Phase: $ARGUMENTS
+
+**Requirement backfill rule:**
+During execution, if an implementation change would alter external behavior, notifications, failure handling, retry/scheduling policy, permissions, API contracts, persistence/data-writing rules, compatibility behavior, or non-functional guarantees, stop before or immediately after the smallest safe edit and update `.planning/requirements/baseline.md` first.
+
+After updating the baseline, update every affected downstream artifact: feature breakdown, frontend/backend tech specs, change list, and pipeline/execution state. Do not let implementation become the only source of truth for new behavior.
+
+Backfill is not required for pure refactors, local method extraction, naming cleanup, formatting, comments, or log wording changes that do not alter behavior.
+
+**Project rule package:**
+Before assigning or executing implementation work, discover project rule sources in the target workspace:
+- `.planning/rules/INDEX.md`
+- `.planning/execution-contract.md`
+- `.planning/toolchain.md`
+- `.planning/lessons/README.md`
+- `.planning/milestones/`
+- `.planning/requirements/`
+- `.context/spec/index.md`
+- matching `.context/spec/stacks/{stack_key}.md`
+- matching `.context/spec/frontend|backend/{codebase}.md`
+- `.planning/code-index/` when present
+- `.context/spec/`
+- `.context/workflow/tdd.md`
+- `.context/workflow/checklist.md`
+- `.context/lessons/README.md`（如存在）
+- root `AGENTS.md`, `CLAUDE.md`, or equivalent project instruction files
+
+If rule sources exist, resolve them using this read order before delegating work: `.planning/rules/INDEX.md` → `.context/spec/index.md` → matching stack spec → matching codebase spec → `.planning/navigation/{codebase}.md` → `.planning/code-index/` when present and relation facts are needed → actual source files. Include the resolved rules and relevant code-index evidence in the files delegated to execution workers and require task-level rule activation. If no rule sources exist, record that no project rule package was found and proceed with the plan context.
+
+When `.planning/code-index/` exists, implementation workers should use it to locate callers, callees, imports, routes, data/resource reads and writes, and tests before editing. They must still read source files at `evidence_path` before making changes.
+
+**Baseline and change-list contract:**
+Before assigning implementation work, read the relevant requirement baseline and change list when present:
+- `.planning/requirements/baseline.md`
+- `.planning/features/{功能名}/功能点梳理.md`
+- `.planning/features/{功能名}/前端技术方案.md`
+- `.planning/features/{功能名}/后端技术方案.md`
+- `.planning/features/{功能名}/*变更清单.md`
+
+Legacy compatibility: if the `.planning/features/{功能名}/` documents are missing, workers may read root `features/{功能名}/` as historical/legacy input, but new generated workflow artifacts should stay under `.planning/features/{功能名}/`.
+
+Workers must implement only confirmed scope. Pending baseline decisions or challenge items that affect scope, semantics, ownership, compatibility, or implementation cost must be reported as blockers, not silently resolved in code.
+Use `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, and phase `CONTEXT.md` as primary history when a task needs history. Treat `features/` or `.context/lessons/` as optional legacy/project-rule sources only when present.
+
+**Available optional flags (documentation only — not automatically active):**
+- `--wave N` — Execute only Wave `N` in the phase. Use when you want to pace execution or stay inside usage limits.
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+- `--interactive` — Execute plans sequentially inline (no subagents) with user checkpoints between tasks. Lower token usage, pair-programming style. Best for small phases, bug fixes, and verification gaps.
+
+**Active flags must be derived from `$ARGUMENTS`:**
+- `--wave N` is active only if the literal `--wave` token is present in `$ARGUMENTS`
+- `--gaps-only` is active only if the literal `--gaps-only` token is present in `$ARGUMENTS`
+- `--interactive` is active only if the literal `--interactive` token is present in `$ARGUMENTS`
+- If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering
+- Do not infer that a flag is active just because it is documented in this prompt
+
+Context files are resolved inside the workflow per-subagent `<files_to_read>` blocks.
+</context>
+
+<rule_activation_gate>
+Before any worker edits code for a task, it must state a compact Rule Activation block:
+
+```markdown
+## Rule Activation
+- Task:
+- Affected layers/modules:
+- Spec index: .context/spec/index.md
+- Stack spec resolved: (from index "Stack Specs" table)
+- Codebase spec resolved: (from index "Codebase Specs" table)
+- Depth spec files to check: (from domain index)
+- MUST rules to verify:
+- Rules read:
+- Related lessons:
+- Toolchain/codegen/mock/DI requirements:
+- Test strategy from change list:
+- Planned test command(s):
+- Execution test command(s):
+- Test files to add/update:
+- Automation skipped? type/reason/debt:
+- Completion gate:
+```
+
+The worker must not treat existing code as more authoritative than explicit project rules. If project rules conflict with the change plan or existing implementation, stop and report the conflict instead of silently choosing.
+
+When the change list includes task-level `适用规范`, `相关经验教训`, `执行前门禁`, `测试策略`, or `审查要求`, those fields are mandatory execution inputs.
+When the change list includes `需求来源` or `CR-*` decision references, the worker must keep implementation inside those confirmed decisions and mention any deviation before editing.
+
+If a code task lacks a task-level test strategy, planned command, execution command placeholder, or skip-automation classification, the worker must stop before editing and report the task as blocked for change-list backfill. Do not invent a silent testing scope during implementation.
+</rule_activation_gate>
+
+<execution_discipline>
+Preserve these generalized workflow rules from the project rule package when applicable:
+
+1. Do not skip required workflow steps or verification because a change looks small unless the user explicitly approved simplification.
+2. Before editing, activate the relevant rules, lessons, toolchain, tests, generated artifacts, and compatibility gates for the task.
+3. Execute in dependency order derived from the change list and project architecture; do not hardcode outbound-call's Go layer order for non-Go projects.
+4. Tests can be written before code (TDD) or incrementally within the same task, but task-level tests must not be deferred to a final standalone test wave.
+5. Before marking a code task complete, add/update the required task-level tests unless the change list contains an acceptable or reviewed skip classification.
+6. Refine planning-level test commands into execution-level commands that are precise enough to rerun the changed tests, then run them and record the result.
+7. **Verification Iron Law** — Before marking ANY task complete, pass the verification gate:
+
+   ```
+   BEFORE claiming completion or expressing satisfaction:
+   1. IDENTIFY: What command proves this claim?
+   2. RUN: Execute the FULL command (fresh, complete in this session)
+   3. READ: Full output, check exit code, count failures
+   4. VERIFY: Does output confirm the claim?
+      - If NO: State actual status with evidence, fix, re-run
+      - If YES: State claim WITH evidence
+   5. ONLY THEN: Mark task complete
+   
+   Skip any step = dishonesty, not efficiency.
+   ```
+
+   **Common false completion patterns (forbidden wording):**
+   | False claim | Requires | Not sufficient |
+   |---|---|---|
+   | "Tests pass" | Test output: 0 failures | Previous run, "should pass" |
+   | "Linter clean" | Linter output: 0 errors | Partial check |
+   | "Build succeeds" | Build command: exit 0 | Linter passing |
+   | "Bug fixed" | Test original symptom: passes | Code changed, assumed fixed |
+   | "Agent reported success" | VCS diff + verify output | Agent claim alone |
+
+   **Red flags — STOP and verify before proceeding:**
+   - Using "should", "probably", "seems to" about completion
+   - Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+   - About to commit/push/complete without fresh verification
+   - Trusting subagent success reports without verifying output
+
+8. **Spec Compliance Gate** — After task implementation and before marking complete, check the applicable depth spec.
+
+   **Resolve spec paths through the index chain — do not hardcode directory names:**
+   1. Read `.context/spec/index.md` — the project's spec registry
+   2. From the "Stack Specs" table, find the stack spec path for your codebase (e.g., BACKEND → `.context/spec/stacks/python-fastapi-pydantic2-sqlalchemy-playwright.md`)
+   3. From the "Codebase Specs" table, find the codebase spec path (e.g., BACKEND → `.context/spec/backend/BACKEND.md`)
+   4. From "Detailed Spec Packages", find the domain index (e.g., `.context/spec/backend/index.md`) and read the relevant layer specs it lists
+
+   The paths vary per project. `.context/spec/index.md` is the single source of truth for where specs live.
+
+   For every MUST rule in the resolved spec files that applies to the layers you modified, either:
+   - Confirm the implementation satisfies it, with evidence; or
+   - Document why it does not apply.
+
+   Record the check in the task completion block:
+
+   ```yaml
+   ## Spec Compliance Check
+   - Spec index: .context/spec/index.md
+   - Stack spec: stacks/python-fastapi-pydantic2-sqlalchemy-playwright.md
+   - Codebase spec: backend/BACKEND.md
+   - Code index evidence: `.planning/code-index/` checked or unavailable with reason
+   - Depth spec files checked: service.md, errors.md
+   - MUST rules:
+     - "Do not expose secrets in error payloads" → ✅ satisfied (secrets stripped in response schema)
+     - "Browser resources must be explicitly cleaned up" → ✅ satisfied (lifespan shutdown handler)
+   - SHOULD rules pending: none
+   ```
+
+   Unresolved MUST violations block task completion. Report them as blocked, do not silently proceed.
+
+10. **Lessons Extraction** — Before marking task complete, ask: "Is there anything worth preserving from this task?"
+
+   Positive lesson candidates:
+   - A new code pattern or design approach that worked well
+   - A subtle dependency or configuration that was non-obvious
+   - A test strategy that caught real issues
+   - A decision rationale that future tasks should know
+
+   If yes, write to `.context/lessons/YYYY-MM-DD-{slug}.md` following existing lesson format. If no, skip.
+
+   This applies to both positive patterns and regression prevention. Good practices deserve preservation as much as bug fixes.
+
+11. **AI Output Boundary** — When a task involves LLM-generated user-facing content (recommendation reasons, summaries, descriptions, error messages in natural language), the implementation must define:
+
+   - **Fixed part**: content controlled by code, not modifiable by LLM (numbers, IDs, format structure)
+   - **Free part**: content delegated to LLM generation (descriptive language, tone, summary wording)
+   - **Constraint list**: things the LLM must NOT output
+   - **Validation**: how to verify LLM output quality (sample with real data, edge cases)
+   
+   Record these in the spec or implementation notes. Do not treat LLM output as a black box — the fixed/constraint boundary determines where bugs are: wrong fixed part = code bug, violated constraint = prompt/system bug, poor free part = quality bug. Without this boundary, all LLM output issues look like "it just doesn't sound right.""
+
+9. Do not commit unless the user explicitly asks.
+</execution_discipline>
+
+<checkpoint_resume>
+## 断点续传机制
+
+执行前必须读取 `.planning/features/{功能名}/PROGRESS.md`，确定当前执行位置。
+
+### 续传流程
+
+1. **读取进度文件**：若 PROGRESS.md 存在，读取当前 Wave 和执行指针
+2. **跳过已完成任务**：所有状态为 `done` 的任务不再执行
+3. **定位续传点**：找到第一个 `pending` 任务，从该任务所在 Wave 开始执行
+4. **Wave 内执行**：对当前 Wave 中所有 `pending` 任务，按依赖关系执行（无依赖的并行，有依赖的串行）
+5. **更新进度**：每个任务完成后立即更新 PROGRESS.md（状态改为 `done`，记录完成时间戳）
+6. **Wave 完成检查**：当前 Wave 所有任务 `done` 后，将执行指针移到下一 Wave
+7. **全部完成**：所有 Wave 的 `done` 后，更新 PROGRESS.md 标记为 `completed`
+8. **写入结构化元数据**：全部完成后写入 `.planning/features/{功能名}/PROGRESS.meta.json`，字段见 `feature-development.yaml` 中 `steps[execute].meta_output.fields`：`task_completed`, `task_total`, `build_passed`, `test_passed`。
+
+### 清除上下文后续传
+
+当会话上下文用尽或用户手动清除上下文后：
+
+1. 用户重新调用 `workflow-execute-phase <功能名>`
+2. 读取 `.planning/features/{功能名}/PROGRESS.md` 找到断点
+3. 读取 `.planning/features/{功能名}/变更清单.md` 获取当前 Wave 任务详情
+4. 从断点继续执行，无需重读已完成的上下文
+
+### 自包含任务要求
+
+每个任务在变更清单中的描述必须包含：
+- 所需文件路径和变更类型（新增/修改/删除）
+- 参考实现位置
+- 适用规范编号
+- 测试策略、规划级命令、执行级命令占位或跳过自动化测试分级
+- 完成验证命令和执行结果记录要求
+
+执行者仅凭任务描述 + 当前代码文件即可完成，无需回看整个变更清单或技术方案。
+</checkpoint_resume>
+
+<process>
+Execute the execute-phase workflow from references/execute-phase.md end-to-end.
+Preserve all workflow gates (wave execution, checkpoint handling, verification, state updates, routing).
+Additionally preserve the project rule activation gate above for every implementation task and carry rule/test/codegen requirements into worker prompts.
+Additionally apply the checkpoint/resume mechanism: read PROGRESS.md first, skip done tasks, update state after each task completes.
+After all implementation tasks for the requested scope are complete and required verification/state updates have been recorded, call `workflow-context-sync --after-implementation` before the final user-facing completion report. Let `workflow-context-sync` classify changed files and choose Light / Medium / Full. If it requires Full without explicit user authorization, explain the reason and wait for confirmation. Include the context sync result in the final report.
+</process>