npm - @chenguangyao/devflow-kit - Versions diffs - 0.1.43 - Mend

@chenguangyao/devflow-kit 0.1.43

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (198) hide show

package/CHANGELOG.md +232 -0
package/LICENSE +21 -0
package/README.md +539 -0
package/bin/devflow.js +9 -0
package/docs/RFC-001-devflow-kit.md +617 -0
package/docs/RFC-002-workflow-kernel.md +134 -0
package/docs/enterprise-integration-supplement.md +274 -0
package/docs/internal-gitlab-setup.md +426 -0
package/docs/marketplace-skills.md +231 -0
package/docs/migration-from-arb.md +232 -0
package/docs/tooling-overview.md +774 -0
package/docs/workflow-orchestration.md +695 -0
package/docs/workflow-ui-prototype.html +271 -0
package/package.json +52 -0
package/schemas/config.schema.json +51 -0
package/schemas/delta.schema.json +22 -0
package/schemas/state.schema.json +130 -0
package/schemas/status-surface.schema.json +197 -0
package/schemas/workflow-confirmation-surface.schema.json +70 -0
package/schemas/workflow-picker.schema.json +94 -0
package/scripts/postinstall.js +101 -0
package/scripts/render-workflow-ui-prototype.js +271 -0
package/skills/apply/SKILL.md +313 -0
package/skills/apply/references/discipline-checklist.md +145 -0
package/skills/apply/references/subagent-implementer-prompt.md +113 -0
package/skills/apply/references/subagent-orchestration.md +150 -0
package/skills/apply/references/subagent-reviewer-prompt.md +180 -0
package/skills/apply/references/tdd-loop.md +287 -0
package/skills/apply/references/when-plan-is-wrong.md +279 -0
package/skills/apply/references/worktree-swarm.md +292 -0
package/skills/archive/SKILL.md +229 -0
package/skills/archive/references/conflict-resolution.md +336 -0
package/skills/archive/references/knowledge-deposit.md +381 -0
package/skills/archive/references/spec-merge.md +365 -0
package/skills/brainstorm/SKILL.md +123 -0
package/skills/brainstorm/references/proposal-template.md +244 -0
package/skills/brainstorm/references/question-catalog.md +168 -0
package/skills/brainstorm/references/session-template.md +184 -0
package/skills/ci-fix/SKILL.md +63 -0
package/skills/ci-fix/references/loop.md +25 -0
package/skills/code-review/SKILL.md +279 -0
package/skills/code-review/references/escalation-playbook.md +192 -0
package/skills/code-review/references/language-cheatsheets/go.md +175 -0
package/skills/code-review/references/language-cheatsheets/java-spring-mybatis.md +246 -0
package/skills/code-review/references/language-cheatsheets/python.md +170 -0
package/skills/code-review/references/language-cheatsheets/vue.md +199 -0
package/skills/code-review/references/output-template.md +275 -0
package/skills/code-review/references/review-checklist.md +251 -0
package/skills/complexity-grading/SKILL.md +259 -0
package/skills/deliver/SKILL.md +271 -0
package/skills/deliver/references/delivery-modes.md +299 -0
package/skills/deliver/references/notify.md +359 -0
package/skills/deliver/references/pr-description.md +319 -0
package/skills/dependency-upgrade/SKILL.md +57 -0
package/skills/dependency-upgrade/references/risk-matrix.md +38 -0
package/skills/df-orchestrator/SKILL.md +407 -0
package/skills/df-orchestrator/references/complexity-grading.md +177 -0
package/skills/df-orchestrator/references/escalation-matrix.md +191 -0
package/skills/df-orchestrator/references/routing-rules.md +290 -0
package/skills/df-orchestrator/references/workflow-state-machine.md +208 -0
package/skills/frontend-quality/SKILL.md +61 -0
package/skills/frontend-quality/references/checklist.md +35 -0
package/skills/handoff-resume/SKILL.md +59 -0
package/skills/handoff-resume/references/handoff-template.md +54 -0
package/skills/plan/SKILL.md +166 -0
package/skills/plan/references/task-breakdown.md +207 -0
package/skills/plan/references/task-sequencing.md +143 -0
package/skills/plan/references/task-template.md +248 -0
package/skills/requirement-analysis/SKILL.md +499 -0
package/skills/requirement-analysis/references/acceptance-criteria.md +183 -0
package/skills/requirement-analysis/references/code-recon.md +151 -0
package/skills/requirement-analysis/references/edge-case-catalog.md +164 -0
package/skills/requirement-analysis/references/requirement-template.md +339 -0
package/skills/requirement-analysis/references/scope-negotiation.md +162 -0
package/skills/security-hardening/SKILL.md +60 -0
package/skills/security-hardening/references/checklist.md +42 -0
package/skills/tech-spec/SKILL.md +388 -0
package/skills/tech-spec/references/api-contract-design.md +172 -0
package/skills/tech-spec/references/decision-records.md +110 -0
package/skills/tech-spec/references/design-template.md +301 -0
package/skills/tech-spec/references/rollout-and-rollback.md +203 -0
package/skills/tech-spec/references/spec-delta-conventions.md +250 -0
package/skills/tech-spec/references/transaction-patterns.md +212 -0
package/skills/test-spec/SKILL.md +219 -0
package/skills/test-spec/references/coverage-strategy.md +218 -0
package/skills/test-spec/references/edge-case-to-test.md +143 -0
package/skills/test-spec/references/test-case-template.md +276 -0
package/skills/verify/SKILL.md +232 -0
package/skills/verify/references/nfr-verification.md +292 -0
package/skills/verify/references/report-templates.md +510 -0
package/skills/verify/references/self-test-guide.md +240 -0
package/skills/verify/references/verify-rollback-map.md +247 -0
package/src/cli/commands/_helpers.js +108 -0
package/src/cli/commands/_submit.js +718 -0
package/src/cli/commands/apply.js +198 -0
package/src/cli/commands/archive.js +180 -0
package/src/cli/commands/checkpoint.js +113 -0
package/src/cli/commands/deliver.js +377 -0
package/src/cli/commands/deploy.js +504 -0
package/src/cli/commands/design.js +158 -0
package/src/cli/commands/disable.js +21 -0
package/src/cli/commands/doctor.js +178 -0
package/src/cli/commands/enable.js +21 -0
package/src/cli/commands/flow.js +645 -0
package/src/cli/commands/help.js +93 -0
package/src/cli/commands/ingest.js +602 -0
package/src/cli/commands/init.js +341 -0
package/src/cli/commands/knowledge.js +523 -0
package/src/cli/commands/logs.js +43 -0
package/src/cli/commands/new.js +202 -0
package/src/cli/commands/plan.js +49 -0
package/src/cli/commands/propose.js +27 -0
package/src/cli/commands/provider.js +698 -0
package/src/cli/commands/report.js +143 -0
package/src/cli/commands/requirement.js +227 -0
package/src/cli/commands/review.js +301 -0
package/src/cli/commands/skills.js +457 -0
package/src/cli/commands/status.js +925 -0
package/src/cli/commands/switch.js +27 -0
package/src/cli/commands/sync.js +47 -0
package/src/cli/commands/test.js +366 -0
package/src/cli/commands/uninstall.js +32 -0
package/src/cli/commands/update.js +74 -0
package/src/cli/commands/verify.js +354 -0
package/src/cli/commands/worktree.js +78 -0
package/src/cli/index.js +72 -0
package/src/cli/parse-args.js +102 -0
package/src/core/autodetect.js +271 -0
package/src/core/change.js +208 -0
package/src/core/checkpoint.js +217 -0
package/src/core/config.js +60 -0
package/src/core/delta.js +290 -0
package/src/core/markers.js +59 -0
package/src/core/paths.js +173 -0
package/src/core/plan-tasks.js +36 -0
package/src/core/project-routing.js +285 -0
package/src/core/projects.js +200 -0
package/src/core/state.js +200 -0
package/src/core/workflow-check.js +177 -0
package/src/core/workflow-init.js +34 -0
package/src/core/workflow-picker.js +154 -0
package/src/core/workflow-policy.js +119 -0
package/src/core/workflow-suggest.js +181 -0
package/src/core/workflow-verify.js +88 -0
package/src/core/workflow.js +433 -0
package/src/core/worktree.js +241 -0
package/src/knowledge/categories.js +107 -0
package/src/knowledge/classify.js +125 -0
package/src/knowledge/deposit.js +414 -0
package/src/knowledge/migrate.js +149 -0
package/src/knowledge/mr.js +219 -0
package/src/knowledge/query.js +131 -0
package/src/knowledge/registry.js +151 -0
package/src/knowledge/sync.js +179 -0
package/src/providers/base.js +74 -0
package/src/providers/drivers/api-yapi.js +78 -0
package/src/providers/drivers/ci-jenkins.js +109 -0
package/src/providers/drivers/intake-confluence.js +544 -0
package/src/providers/drivers/kb-git.js +549 -0
package/src/providers/drivers/kb-weknora.js +472 -0
package/src/providers/drivers/notify-smtp.js +515 -0
package/src/providers/drivers/observability-oss.js +43 -0
package/src/providers/drivers/observability-sls.js +50 -0
package/src/providers/lifecycle.js +135 -0
package/src/providers/loader.js +132 -0
package/src/providers/local.js +190 -0
package/src/providers/userconfig.js +283 -0
package/src/reports/aggregate.js +185 -0
package/src/reports/coverage.js +163 -0
package/src/reports/detect.js +143 -0
package/src/reports/parse.js +236 -0
package/src/templates/files/ci/github.yml +38 -0
package/src/templates/files/ci/gitlab.yml +27 -0
package/src/templates/files/design.md +63 -0
package/src/templates/files/ide/devflow-workflow.md +58 -0
package/src/templates/files/ide/project-overview-reference.md +1 -0
package/src/templates/files/ide/project-overview.md +27 -0
package/src/templates/files/knowledge-index.json +17 -0
package/src/templates/files/knowledge.md +28 -0
package/src/templates/files/meta.json +8 -0
package/src/templates/files/plan.md +38 -0
package/src/templates/files/proposal.md +33 -0
package/src/templates/files/reports/contract-test.md +40 -0
package/src/templates/files/reports/e2e-test.md +30 -0
package/src/templates/files/reports/integration-test.md +36 -0
package/src/templates/files/reports/joint-test.md +58 -0
package/src/templates/files/reports/perf.md +24 -0
package/src/templates/files/reports/regression.md +20 -0
package/src/templates/files/reports/remote-test.md +55 -0
package/src/templates/files/reports/self-test.md +43 -0
package/src/templates/files/reports/smoke-test.md +22 -0
package/src/templates/files/reports/unit-test.md +36 -0
package/src/templates/files/requirement.md +51 -0
package/src/templates/files/review.md +38 -0
package/src/templates/files/tests.md +36 -0
package/src/templates/files/verify.md +32 -0
package/src/templates/index.js +21 -0
package/src/utils/log.js +37 -0

package/scripts/render-workflow-ui-prototype.js ADDED Viewed

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const childProcess = require('child_process');
+function renderWorkflowUiPrototype(options = {}) {
+  const root = options.root || path.resolve(__dirname, '..');
+  const fixtures = options.pickers && options.card
+    ? { pickers: options.pickers, card: options.card }
+    : loadFixtureSurfaces({ root });
+  const sourceLabel = options.sourceLabel || fixtures.card.slug || fixtures.card.baseRecipe?.id || 'workflow';
+  return [
+    '<!doctype html>',
+    '<html lang="zh-CN">',
+    '<head>',
+    '  <meta charset="utf-8">',
+    '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+    '  <title>devflow Workflow UI Prototype</title>',
+    '  <style>',
+    renderCss(),
+    '  </style>',
+    '</head>',
+    '<body>',
+    '  <main class="page">',
+    '    <section class="toolbar" aria-label="Workflow actions">',
+    '      <div>',
+    '        <h1>Workflow 编排</h1>',
+    '        <p>线性 skill 选项卡 + 推荐勾选 + workflow 确认卡。</p>',
+    '      </div>',
+    `      <code>${escapeHtml(sourceLabel)} · ${escapeHtml(fixtures.card.actions.picker || fixtures.card.nextAction || '-')}</code>`,
+    '    </section>',
+    fixtures.pickers.map((entry) => renderPickerSurface(entry.surface, entry.title)).join('\n'),
+    renderConfirmationSurface(fixtures.card),
+    '  </main>',
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n');
+}
+function loadFixtureSurfaces({ root = path.resolve(__dirname, '..') } = {}) {
+  return {
+    pickers: [
+      { title: '默认推荐', surface: readJson(root, 'test/fixtures/workflow-surfaces/picker-default.json') },
+      { title: '风险推荐', surface: readJson(root, 'test/fixtures/workflow-surfaces/picker-risk-recommended.json') },
+    ],
+    card: readJson(root, 'test/fixtures/workflow-surfaces/confirmation-card.json'),
+  };
+}
+function loadWorkflowSurfacesFromCli({
+  root = path.resolve(__dirname, '..'),
+  slug,
+  cwd = process.cwd(),
+  execFileSync = childProcess.execFileSync,
+} = {}) {
+  if (!slug) throw new Error('loadWorkflowSurfacesFromCli requires slug');
+  const picker = runDevflowJson(root, cwd, ['flow', 'picker', `--slug=${slug}`, '--json'], execFileSync);
+  const card = runDevflowJson(root, cwd, ['flow', 'card', `--slug=${slug}`, '--json'], execFileSync);
+  return {
+    pickers: [{ title: '当前 workflow', surface: picker }],
+    card,
+  };
+}
+function runDevflowJson(root, cwd, args, execFileSync) {
+  const out = execFileSync(process.execPath, [path.join(root, 'bin', 'devflow.js'), ...args], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return JSON.parse(String(out));
+}
+function readJson(root, rel) {
+  return JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+}
+function renderPickerSurface(surface, title) {
+  return [
+    `    <section class="surface" data-surface="workflow-picker" aria-label="${escapeAttr(title)}">`,
+    `      <div class="surface-head"><h2>${escapeHtml(title)}</h2><span>${escapeHtml(surface.baseRecipe.id)} / ${escapeHtml(surface.status)}</span></div>`,
+    '      <div class="groups">',
+    surface.groups.map(renderGroup).join('\n'),
+    '      </div>',
+    '      <div class="command-row">',
+    `        <code>${escapeHtml(surface.actions.applySelection)}</code>`,
+    `        <code>${escapeHtml(surface.actions.card)}</code>`,
+    '      </div>',
+    '    </section>',
+  ].join('\n');
+}
+function renderGroup(group) {
+  return [
+    `        <section class="group" aria-label="${escapeAttr(group.label)}">`,
+    `          <h3>${escapeHtml(group.label)}</h3>`,
+    '          <ol>',
+    group.items.map(renderItem).join('\n'),
+    '          </ol>',
+    '        </section>',
+  ].join('\n');
+}
+function renderItem(item) {
+  const state = item.selected ? '已选' : item.recommended ? '推荐' : '可选';
+  const tags = [
+    item.required ? 'required' : null,
+    item.optional ? 'optional' : null,
+    item.protected ? 'protected' : null,
+    item.locked ? 'locked' : null,
+  ].filter(Boolean);
+  const checkbox = item.locked
+    ? `<input type="checkbox" checked disabled aria-label="${escapeAttr(item.step)} locked">`
+    : `<input type="checkbox"${item.selected ? ' checked' : ''} aria-label="${escapeAttr(item.step)}">`;
+  const command = item.command ? `<code>${escapeHtml(item.command)}</code>` : '';
+  const reason = item.reason ? `<p>${escapeHtml(item.reason)}</p>` : '';
+  return [
+    '            <li>',
+    `              <label>${checkbox}<span>${escapeHtml(item.step)}</span></label>`,
+    `              <small>${escapeHtml(item.skill)} · ${escapeHtml(state)}${tags.length ? ` · ${escapeHtml(tags.join(' / '))}` : ''}</small>`,
+    reason ? `              ${reason}` : '',
+    command ? `              ${command}` : '',
+    '            </li>',
+  ].filter(Boolean).join('\n');
+}
+function renderConfirmationSurface(surface) {
+  const card = surface.confirmationCard;
+  return [
+    '    <section class="surface confirm" data-surface="workflow-card" aria-label="Workflow confirmation card">',
+    `      <div class="surface-head"><h2>确认卡</h2><span>${surface.ok ? 'ok' : 'blocked'} / ${escapeHtml(surface.status || '-')}</span></div>`,
+    '      <ol class="timeline">',
+    card.steps.map((step, idx) => renderTimelineStep(step, idx + 1)).join('\n'),
+    '      </ol>',
+    '      <div class="actions">',
+    `        <button type="button">${escapeHtml(card.primaryAction.id)}</button>`,
+    `        <code>${escapeHtml(card.primaryAction.command)}</code>`,
+    `        <code>${escapeHtml(card.secondaryActions[0].command)}</code>`,
+    '      </div>',
+    '    </section>',
+  ].join('\n');
+}
+function renderTimelineStep(step, num) {
+  const tags = [
+    step.required ? 'required' : null,
+    step.optional ? 'optional' : null,
+    step.protected ? 'protected' : null,
+  ].filter(Boolean).join(' / ');
+  return [
+    '        <li>',
+    `          <span>${num}</span>`,
+    `          <strong>${escapeHtml(step.id)}</strong>`,
+    `          <small>${escapeHtml(step.skill)}${tags ? ` · ${escapeHtml(tags)}` : ''}</small>`,
+    '        </li>',
+  ].join('\n');
+}
+function renderCss() {
+  return [
+    '    :root { color-scheme: light; --ink: #172026; --muted: #60707a; --line: #d8e0e5; --panel: #f8fafb; --accent: #146b5f; --warn: #b85c00; }',
+    '    * { box-sizing: border-box; }',
+    '    body { margin: 0; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: var(--ink); background: #eef3f5; }',
+    '    .page { width: min(1180px, calc(100vw - 32px)); margin: 0 auto; padding: 28px 0 40px; }',
+    '    .toolbar { display: flex; align-items: end; justify-content: space-between; gap: 20px; padding: 10px 0 18px; }',
+    '    h1, h2, h3, p { margin: 0; }',
+    '    h1 { font-size: 28px; line-height: 1.15; }',
+    '    h2 { font-size: 18px; }',
+    '    h3 { font-size: 14px; color: var(--muted); }',
+    '    p { color: var(--muted); margin-top: 6px; }',
+    '    code { display: inline-block; max-width: 100%; overflow-wrap: anywhere; border: 1px solid var(--line); border-radius: 6px; padding: 5px 7px; background: white; font-size: 12px; color: #263840; }',
+    '    .surface { margin-top: 18px; border: 1px solid var(--line); border-radius: 8px; background: white; padding: 18px; }',
+    '    .surface-head { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-bottom: 14px; }',
+    '    .surface-head span { color: var(--muted); font-size: 13px; }',
+    '    .groups { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }',
+    '    .group { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 12px; }',
+    '    ol { list-style: none; margin: 0; padding: 0; }',
+    '    .group li { min-height: 112px; display: grid; gap: 6px; align-content: start; border-top: 1px solid var(--line); padding: 10px 0; }',
+    '    .group li:first-child { border-top: 0; }',
+    '    label { display: flex; align-items: center; gap: 8px; font-weight: 700; }',
+    '    input { width: 16px; height: 16px; accent-color: var(--accent); }',
+    '    small { color: var(--muted); font-size: 12px; line-height: 1.35; }',
+    '    li p { color: var(--warn); font-size: 12px; margin: 0; }',
+    '    .command-row, .actions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 14px; align-items: center; }',
+    '    .timeline { display: grid; grid-template-columns: repeat(8, minmax(96px, 1fr)); gap: 8px; overflow-x: auto; padding-bottom: 4px; }',
+    '    .timeline li { min-width: 96px; border: 1px solid var(--line); border-radius: 8px; padding: 10px; background: var(--panel); display: grid; gap: 5px; }',
+    '    .timeline span { display: grid; place-items: center; width: 22px; height: 22px; border-radius: 999px; background: var(--accent); color: white; font-size: 12px; font-weight: 700; }',
+    '    button { border: 0; border-radius: 6px; padding: 8px 12px; background: var(--accent); color: white; font-weight: 700; }',
+    '    @media (max-width: 860px) { .toolbar { align-items: start; flex-direction: column; } .groups { grid-template-columns: 1fr; } .timeline { grid-template-columns: repeat(4, minmax(96px, 1fr)); } }',
+  ].join('\n');
+}
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+function escapeAttr(value) {
+  return escapeHtml(value);
+}
+function writePrototype(options = {}) {
+  const root = options.root || path.resolve(__dirname, '..');
+  const html = renderWorkflowUiPrototype(options);
+  const out = options.out || outputPathFor({ root, slug: options.sourceLabel });
+  fs.writeFileSync(out, html, 'utf8');
+  return out;
+}
+function outputPathFor({ root = path.resolve(__dirname, '..'), slug = null } = {}) {
+  if (!slug) return path.join(root, 'docs', 'workflow-ui-prototype.html');
+  return path.join(os.tmpdir(), `devflow-workflow-ui-${slugify(slug)}.html`);
+}
+function slugify(value) {
+  return String(value)
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    || 'workflow';
+}
+if (require.main === module) {
+  const args = parseArgs(process.argv.slice(2));
+  const root = args.root || path.resolve(__dirname, '..');
+  const surfaces = args.slug
+    ? loadWorkflowSurfacesFromCli({ root, slug: args.slug, cwd: args.cwd || process.cwd() })
+    : loadFixtureSurfaces({ root });
+  const options = {
+    root,
+    ...surfaces,
+    sourceLabel: args.slug,
+    out: args.out,
+  };
+  if (args.write) {
+    console.log(writePrototype(options));
+  } else {
+    process.stdout.write(renderWorkflowUiPrototype(options));
+  }
+}
+function parseArgs(argv) {
+  const out = { write: false };
+  for (const arg of argv) {
+    if (arg === '--write') out.write = true;
+    else if (arg.startsWith('--slug=')) out.slug = arg.slice('--slug='.length);
+    else if (arg.startsWith('--cwd=')) out.cwd = arg.slice('--cwd='.length);
+    else if (arg.startsWith('--root=')) out.root = arg.slice('--root='.length);
+    else if (arg.startsWith('--out=')) out.out = arg.slice('--out='.length);
+  }
+  return out;
+}
+module.exports = {
+  renderWorkflowUiPrototype,
+  loadFixtureSurfaces,
+  loadWorkflowSurfacesFromCli,
+  outputPathFor,
+  writePrototype,
+  parseArgs,
+};

package/skills/apply/SKILL.md ADDED Viewed

@@ -0,0 +1,313 @@
+---
+name: devflow-apply
+description: |
+  devflow-kit apply 阶段严格按 `plan.md` 执行编码。一个 task 一个 TDD 循环(写失败测试 → 最小实现 → 运行 → 提交),
+  默认每个 task 在独立 worktree 运行。≥2 个互不依赖 task 必须由上层 agent 一次性并行分派多个
+  子 agent,不能在父 agent 中顺序实现。触发时机:`devflow apply [--task N]` 或 `/df:apply`。
+  不允许在 apply 阶段拍脑袋偷改 scope;发现 plan / design 有问题要回退到对应 phase。
+  所有完成的 task 通过 `devflow apply --task N --done` 写进 state.json。
+when_to_use: |
+  plan.md 通过硬闸后。每个 task 开一次 `devflow apply --task N --start` → 编码 → `--done`;直到所
+  有 task done。之后由 `devflow-df-orchestrator` 触发 `devflow review --round`。
+---
+# apply
+**执行者身份**,不是决策者。plan.md 是你的剧本,tests.md(若存在)和 plan 的 Test 字段是验收,design.md 是参考;任何偏离都意味着前置 phase 有问题,必须**回退修正**,而不是在 apply 里偷偷改。
+## 前置检查
+| 输入 | 必需 | 缺失时 |
+| --- | --- | --- |
+| `plan.md`(硬闸通过) | 是 | 回退 plan |
+| `state.planReviewConfirmedAt` | 是 | 回到 plan 补审查确认；必须先展示计划审查卡并等用户确认 |
+| `tests.md` | 可选；存在时必须遵守 | 缺失时以 plan.md 每个 task 的 Test 字段为验收 |
+| `design.md` | 是 | 回退 tech-spec |
+| `state.json`,phase=apply | 是 | orchestrator 修正 |
+| 项目可编译 / 测试框架就绪 | 是 | `devflow doctor` 诊断 |
+**旧状态兜底**：如果已经有 `plan.md`，但 `state.planReviewConfirmedAt` 缺失，说明计划还没有经过用户审查。必须停止 apply，回到 plan 补展示计划审查卡；用户确认后写入 `planReviewConfirmedAt` 才能继续。不要因为用户说"继续"就直接开 task、创建 worktree 或编码。
+**并行授权规则**：plan 审查一旦确认，用户不需要再单独说"并行"、"用子 agent"或"分派 agent"。`devflow apply` / `/df:apply` 本身就是按 plan 执行的授权；如果 plan 的 ready wave 中有 ≥2 个互不依赖 task，必须自动使用 subagent + worktree 并行分派。只有用户明确选择 `applyMode: direct`、工具环境不支持 subagent，或 task 间有共享文件 / 强依赖时，才允许不并行；这种例外必须写进下一步卡片和 state note。
+## 一个 task 的 TDD 循环(硬)
+每个 task 都是 4-step 循环。少任何一步都是**错误**:
+```
+1. 读 task 的 5 要素(Files / Behavior / Test / Implementation / Commit)
+2. 写失败测试(先跑一次,确认失败,且失败原因正确)
+3. 最小实现(刚好让测试通过,不做"顺手重构")
+4. 跑所有相关测试(不仅新加的,防回归)→ 必须展示实际输出(见下 verification gate)
+5. commit(用 plan.md 里规定的 commit message)
+6. devflow apply --task N --done --note="commit <sha>"
+```
+### Verification Gate（--done 前强制）
+> 借鉴 **verification-before-completion** 原则：没有实际输出就不能声称"通过"。
+```
+NO COMPLETION CLAIMS WITHOUT FRESH TEST EVIDENCE
+在执行 --done 前必须展示：
+  ✅ 实际命令：go test ./... | npm test | pytest | mvn test
+  ✅ 实际输出：通过数 / 失败数 / 耗时
+  ✅ exit code 0
+禁止：
+  ❌ "我跑了测试，都过了" (未附输出)
+  ❌ "应该能过" / "看起来没问题"
+  ❌ 跳过运行直接 --done
+```
+### Baseline Attribution（防止编译空转）
+apply 阶段的验证目标是证明"本轮 diff 没有引入新问题"，不是反复证明"整个老项目已经完美 green"。遇到大仓 / DDD 多模块 / 历史编译红点时，必须走验证阶梯和基线归因。
+**硬规则**：
+1. 改代码前先跑一次最小基线探测，记录 `baselineKnownFailures`。
+2. 本轮实现后优先跑 diff-scoped 验证：`git diff --check`、变更文件相关测试、最小 reactor slice。
+3. 验证失败必须先归因：命中新改文件 / 新增测试 / 本轮依赖链路 → 修；与改代码前基线一致且不涉及本轮 diff → 记录为基线问题。
+4. 基线失败不能无限重试：同一条已知基线错误最多复核一次；继续失败时停止消耗时间，输出 `DONE_WITH_CONCERNS` 或 `BLOCKED`，并在下一步卡片里让用户选择先修环境还是继续 review。
+5. 每轮验证有时间预算：单条 compile/test 建议 3-5 分钟；超时按阻塞/风险记录，不要换命令盲跑。
+`baselineKnownFailures` 必须写清：
+```yaml
+baselineKnownFailures:
+  - command: mvn -pl <entry-module> -am -DskipTests compile
+    symptom: "Lombok/config 类历史编译错误"
+    beforeChange: true
+    touchesCurrentDiff: false
+    decision: "treat as baseline; current diff verified with git diff --check + targeted tests"
+```
+如果只剩基线问题而本轮 diff-scoped 验证通过，result 用 `DONE_WITH_CONCERNS`，不要假装全绿；如果基线问题阻止判断本轮改动是否正确，result 用 `BLOCKED`。
+### 处理 Review Findings（实现反馈时）
+> 借鉴 **receiving-code-review** 原则：技术核验 > 条件反射式修改。
+```
+收到 review.findings.json 后：
+1. READ 完整读一遍，不要边读边改
+2. VERIFY 先在代码里确认问题真实存在
+   - MUST 级：确认根因，不要只改表面症状
+   - SHOULD 级：评估是否真实影响，可合理 pushback
+   - NIT 级：直接改，无需讨论
+3. CLARIFY 若 finding 描述不清，先问清楚再动手
+4. IMPLEMENT 逐条修复，每条独立 commit
+5. 禁止：看到 finding 就盲改（可能改错方向）
+```
+详细的 TDD 每步该做 / 不该做见 [`references/tdd-loop.md`](references/tdd-loop.md)。
+## 硬约束
+1. **≥ 2 个 task 必须用子 agent**:不允许在父 agent 里顺序执行多个 task，必须分派子 agent
+2. **不连着做 2 个 task 再 commit**:每个 task 独立 commit,方便 review 和回滚
+3. **不改 Files 外的文件**:发现要改,先更新 plan.md,审计后再动
+4. **不跳过失败测试**:失败测试必须修;暂时修不了 → quarantine(@Disabled + 记 issue),不 skip
+5. **不在 apply 里改 design / tests / plan**(不是 proofreading 级的改动):任何业务改动必须回退到对应 phase
+6. **不提交编译不过 / 测试红的代码到主干**:工作区 OK,但每个 commit 都要 green
+更多 apply 阶段的坚守原则 + 常见偷懒的识别见 [`references/discipline-checklist.md`](references/discipline-checklist.md)。
+## 子 agent 编排模式（多 task 强制）
+> **⛔ HARD GATE**：plan.md 中 task 数量 ≥ 2 时，**必须**使用子 agent 编排 + worktree。
+> 直接在当前 agent 里顺序执行多个 task 是**反模式**，视同跳过质量门。
+> **⛔ PARALLEL GATE**：同一批 ready task 中只要有 ≥ 2 个互不依赖、无共享文件，就必须在同一轮里并行启动多个实现子 agent。
+> 把 T-02 做完再启动 T-03（两者本可并行）是**错误执行**，必须停下重排为并行 wave。
+**授权规则（硬约束）**：
+- 用户触发 `devflow apply` / `/df:apply`，且 `plan.md` 已通过用户审查后，devflow apply 本身就是子 agent 授权。
+- 只要命中本节的多 task / 并行 gate，就不得再要求用户额外说"用子 agent"、"并行"或"分派 agent"。
+- 如果当前系统提供 subagent / spawn_agent 工具，controller 必须直接按 ready wave 分派；不能退化为父 agent 顺序实现。
+- 只有两种情况允许降级：所有未完成 task 都有强依赖 / 共享文件，或工具环境确实不支持子 agent。降级时必须在 STATUS 里写明原因。
+**每个 ready wave 并行分派实现子 agent → wave 完成后逐 task 规格合规 reviewer → 代码质量 reviewer → `--done`**。
+```
+controller（本 agent）读 plan.md 提取所有 task 全文，建 TodoWrite
+Step 0: 根据 plan.md DAG 计算 ready wave
+  - 已完成依赖全部满足
+  - Files 无交集
+  - 不存在 contract→consumer / DDL→business 等强依赖
+Per wave：
+  1. 对 wave 内每个 task 先执行 devflow apply --task N --start，创建独立 worktree
+  2. 在同一条工具消息里一次性分派多个实现子 agent（每个 agent 一个 task + 一个 worktree）
+  3. 等 wave 内实现子 agent 返回后，逐 task 分派规格合规 reviewer 子 agent（传 diff + AC）
+  4. 逐 task 分派代码质量 reviewer 子 agent（传 diff + cheatsheet）
+  5. controller 对通过 pre-review 的 task 执行 devflow apply --task N --done --note="<sha>"
+  6. 重新计算下一批 ready wave
+所有 task done → devflow review --round（正式 review，不省略）
+```
+**模式选择（强制）**：
+| task 数量 | 复杂度 | 执行模式 |
+| --- | --- | --- |
+| 1 个 task | 任意 | 当前 agent 直接做（无需子 agent） |
+| ≥ 2 个 task 且存在强依赖 / 共享文件 | 任意 | 子 agent + worktree，按依赖 wave 串行推进 |
+| ≥ 2 个 task 且同一 wave 内有 ≥ 2 个独立 task | 任意 | 子 agent + worktree，同一 wave 必须并行启动 |
+**controller 职责**：只做协调（读文件、传上下文、回答问题、执行 `--done`），不写代码。
+**并行启动要求**：如果 IDE 支持 subagent 工具，controller 必须在一条消息中发起多个子 agent 调用；不要先等 T-02 返回再发 T-03。若工具环境不支持并行子 agent，必须在状态输出中标记 `BLOCKED` 或 `DONE_WITH_CONCERNS`，说明原因，不能假装已按并行协议执行。
+详细编排流程、回审循环上限、反模式见 [`references/subagent-orchestration.md`](references/subagent-orchestration.md)。
+实现子 agent prompt 模板见 [`references/subagent-implementer-prompt.md`](references/subagent-implementer-prompt.md)。
+reviewer 子 agent prompt 模板（规格合规 + 代码质量）见 [`references/subagent-reviewer-prompt.md`](references/subagent-reviewer-prompt.md)。
+## Worktree swarm(并行的单元)
+默认行为:`devflow apply --task N` 在 `.devflow-worktrees/<slug>/task-N/` 创建独立 worktree + 分支 `devflow/<slug>/task-N`。
+并行执行时:
+```
+devflow apply --task 1 --start        # 终端 A
+devflow apply --task 2 --start        # 终端 B(独立 worktree,不互相污染)
+devflow apply --task 3 --start        # 终端 C
+```
+- 每个 worktree 独立 git 状态 / build 缓存 / 测试 watcher
+- 同时跑的 task 之间**不能有依赖**(plan.md 的依赖图标了)
+- 合并顺序按依赖,不按完成顺序
+清理:
+```
+devflow worktree cleanup <slug> --task=N                 # 删 worktree + 删分支(合并后)
+devflow worktree cleanup <slug> --task=N --keep-branch    # 保留分支(pre-PR)
+devflow worktree list <slug>                              # 看当前 worktree 状态
+```
+worktree 用法、何时 `--no-worktree`、冲突处置、合并顺序见 [`references/worktree-swarm.md`](references/worktree-swarm.md)。
+## 什么时候**不**用 worktree
+- L1 一行改 bug(`--no-worktree` 直接在 main 做)
+- 纯 spike / POC(`--no-worktree`,做完 stash / reset)
+- 只 1 个 task 的 plan(worktree 开销 > 好处)
+## 发现 plan / design 不对时
+**第一反应**:停止编码。
+```
+devflow apply --task N --pause --reason="<具体描述>"
+```
+然后按问题定位:
+| 问题 | 回退到哪 |
+| --- | --- |
+| task 描述歧义 / 5 要素不全 | plan(`devflow plan --edit`) |
+| 实现方式不对 / 架构缺陷 | tech-spec(`devflow tech-spec --revise`) |
+| 需求里没定义这种情况 | requirement-analysis(Round 2 追加 Q) |
+回退后**一定**在对应 phase 的产物里留一段"第 N 次返工"的记录;然后 `devflow apply --task N --resume`。
+发现问题时的决策树、审计格式见 [`references/when-plan-is-wrong.md`](references/when-plan-is-wrong.md)。
+## 按语言加载 cheatsheet(全语言)
+apply 阶段写实现时,agent 应按项目语言加载对应 cheatsheet(与 code-review / tech-spec 共享):
+| detect.language | cheatsheet |
+| --- | --- |
+| `java` (Spring Boot + MyBatis / JPA) | `../code-review/references/language-cheatsheets/java-spring-mybatis.md` |
+| `go` | `../code-review/references/language-cheatsheets/go.md` |
+| `python` | `../code-review/references/language-cheatsheets/python.md` |
+| `node`(Vue) | `../code-review/references/language-cheatsheets/vue.md` |
+apply 时关注的重点与 review 不同:
+- **review**:看"代码里**做了**什么错事"
+- **apply**:看"写的时候**该**怎么避免那些错事"
+比如 cheatsheet 里 "MyBatis 全链路字段一致性" 一节,apply 时要主动**逐步核对**(Entity → Mapper XML → ResultMap),review 时则是**扫**有没有不一致。
+## 完成状态协议(phase 级)
+单个 task 完成由 `devflow apply --task N --done` 记入 state;当**所有 task done** 时,本 skill 整体 DONE:
+```
+---STATUS---
+result: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+outputs:
+  - devflow/changes/<slug>/state.json (updated)
+  - git commits: T-01..T-NN
+  - devflow/changes/<slug>/reports/test-report.md#unit (首次跑过后产出)
+baselineKnownFailures:
+  - <command + symptom + whether it touches current diff>
+tasksCompleted: K/K
+iterations: N             # 如果经历了 review 回退再 apply,这里是第几轮
+nextAction: devflow review --slug=<slug> --round
+---END_STATUS---
+```
+**下一步卡片（硬约束）**：
+任何 result 都必须在用户可见正文最后展示下一步卡片。每次用户可见回复收尾都要给出下一步，包含但不限于：启动/完成一个 task、完成一个 ready wave、修复一轮 review findings、pre-review 后返回、进入 `DONE_WITH_CONCERNS` / `BLOCKED` / `NEEDS_INPUT`。不能只列变更和校验，不能只写 `---STATUS---`，也不能让用户猜下一步。
+```markdown
+## 下一步
+状态：DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+下一步：[一句话说明]
+命令：`<nextAction command>`
+需要你确认：[无 / 是否接受遗留风险并推进 / 需要补充的信息]
+```
+按 result 填写：
+- `DONE`：下一步通常是正式 review；命令：`devflow review --slug=<slug> --round`。
+- `DONE_WITH_CONCERNS`：必须列出遗留风险，并明确问用户是否推进到下一 phase；如果推进，给出命令：`devflow review --slug=<slug> --round`。
+- `BLOCKED`：不要给推进命令；必须说明解除阻塞的最小动作，例如切换 JDK/toolchain、修复编译环境、回退 plan/design。
+- `NEEDS_INPUT`：必须列出需要用户回答的问题或选择项，用户回复后才能继续。
+示例：
+```markdown
+## 下一步
+状态：DONE_WITH_CONCERNS
+下一步：建议先修复 Maven 实际 JDK / Lombok 环境后再进入正式 review，或者你确认接受该风险后继续 review。
+命令：`mvn -pl health-mall-app -am -DskipTests compile`
+需要你确认：是否先处理编译环境问题；若继续推进，回复“继续 review”。
+```
+## 反模式
+- **⛔ 多 task 但不用子 agent，在父 agent 里顺序执行**：违反硬约束 1，跳过 pre-review 质量门
+- **⛔ ≥ 2 task 但不开 worktree**：task 间文件互相污染，合并冲突风险高
+- **先整块写再加测试**:违反 TDD,review 和 verify 都会返工
+- **用 print / 手 test 代替自动化 test**:没留下可重跑的契约
+- **一个 commit 包 5 个 task**:review 一口气咽 500 行,灾难
+- **测试挂了 skip 继续**:挂了就修,quarantine 要走审计(reason + deadline)
+- **偷偷改 plan / design**:行为不一致,下游 review 对不上,archive 时 delta 冲突
+- **跨 task 编辑公用文件**:合并时冲突
+- **在 worktree 里 `git rebase main`**:保持干净线性的诱惑,但会让依赖链混乱;让合并者 rebase
+- **忘记 `--done` 标记**:state.json 认为 task 还在 in_progress,下次 apply 或 review 会 gate 挂
+- **apply 阶段"顺手"优化 design 未涉及的代码**:所谓 scope creep,review 要反问"为什么这个不是单独 task"
+## 参考
+- [`references/tdd-loop.md`](references/tdd-loop.md) — TDD 每步详解:写失败测试 / 最小实现 / 运行 / 提交 + 常见偏离识别
+- [`references/discipline-checklist.md`](references/discipline-checklist.md) — apply 阶段的纪律 checklist(per-task before/during/after)
+- [`references/worktree-swarm.md`](references/worktree-swarm.md) — worktree 并行执行、合并顺序、冲突处置
+- [`references/when-plan-is-wrong.md`](references/when-plan-is-wrong.md) — 发现 plan / design 不对时的回退决策树与审计格式
+- [`references/subagent-orchestration.md`](references/subagent-orchestration.md) — 子 agent 编排流程、回审循环上限、与正式 review 的边界
+- [`references/subagent-implementer-prompt.md`](references/subagent-implementer-prompt.md) — 实现子 agent prompt 模板
+- [`references/subagent-reviewer-prompt.md`](references/subagent-reviewer-prompt.md) — reviewer 子 agent prompt 模板（规格合规 + 代码质量）
+- [`../code-review/references/language-cheatsheets/`](../code-review/references/language-cheatsheets/) — 按语言挑 1-2 份(apply 视角:写时避免;与 review 共享同一份内容)