@devflow-core/dsh-devflow 0.1.0

package/assets/skills/devflow-brainstorm/references/interview-discipline.md

@@ -0,0 +1,184 @@
+# DevFlow Brainstorm Interview Discipline
+
+Use this reference only while `devflow-brainstorm` clarifies and explores a request. It is not a route, design, planning, recovery, or documentation workflow.
+
+## Clarification Loop
+
+```text
+User request
+-> read minimum relevant facts
+-> Semantic Echo-Back (all fields, even when none)
+-> wait for confirm or correction
+-> one question at a time, each with a recommended answer
+-> mandatory multi-angle exploration and problem-space recommendation
+-> corrected echo-back when understanding changes
+-> fixed Confirmed request summary
+-> user-selected A/B/C gate
+-> A starts Spec; B/C start Cut; missing depth returns facts to Core
+```
+
+`devflow-core` consumes only missing-depth, exception, and non-unique facts. This reference presents A/B/C but never selects the depth; the selected branch starts directly.
+
+## Clarification Depth
+
+Depth governs **analysis breadth only**. It never skips the echo-back, the confirm gates, the question discipline, or the recommendation duty.
+
+| Tier | Entry condition | Moves |
+|---|---|---|
+| `deep` (default) | Every request, unless the user explicitly asks for a lighter pass. | Full multi-angle checklist with a per-angle report; directions with trade-offs; recommendation. |
+| `standard` | Only on explicit user request for a lighter pass. | Fitting angles instead of the full checklist; every other duty unchanged. |
+
+There is no fast lane. When the user asks for speed, compress wording, never gates.
+
+## Semantic Echo-Back
+
+Start every Brainstorm pass with this understanding check:
+
+```text
+My understanding:
+- Problem to solve: <one sentence in the user's domain language>
+- Known facts/constraints: <facts read, or none>
+- NOT what you want: <likely misreading ruled out, or none>
+- My assumptions (that could be wrong): <inferences not stated by the user, or none>
+- Understanding gaps: <specific unclear points, or none>
+Is this right? (correct me / confirm)
+```
+
+Rules:
+
+- It is its own message and ends with the confirm-or-correct question.
+- Include all fields, even when a field is `none`.
+- If multiple interpretations are plausible, present the alternatives in the echo-back; do not choose one.
+- Facts from code, configuration, tests, or documentation are stated rather than asked.
+- Business intent and user-visible boundaries are confirmed rather than inferred.
+- If the user corrects the understanding, apply the Understanding Revision Rule below.
+
+## Multi-Angle Checklist
+
+Mandatory on every request (default `deep`). Walk every angle and report what each found, including "nothing found here" — an explicit negative finding is what makes the summary a reliable anti-hallucination basis:
+
+| Angle | Ask yourself |
+|---|---|
+| User value | Who benefits, from what pain? Is the outcome observable? |
+| Edges and exceptions | What inputs, actors, or states break the happy path? |
+| Impact surface | Who or what else is affected — other features, data, users not named in the request? |
+| Reverse thinking | What happens if we do nothing, or do the opposite? |
+| Proportionality | Is the ask sized to the value? Over- or under-scoped? |
+| Hidden assumptions | What must be true for this request to make sense? Is any of it doubtful? |
+
+Findings feed the summary: gaps and risks go to `Identified gaps/risks`; direction thinking goes to `Directions considered` and `Recommended direction`. When every angle finds nothing, write `none` in those fields — do not invent findings. If an angle exposes a new decision-impact gap, return to One-Question Discipline and resolve it before producing `Confirmed request`.
+
+## Problem-Space Recommendation
+
+Expected on every request, not only when asked:
+
+- naming gaps, contradictions, risks, and missing stakeholders in the user's request;
+- offering directions the user has not considered, each with trade-offs;
+- recommending one direction with its rationale;
+- recording rejected directions and why they were dropped.
+
+Out of bounds — record the need in the summary and leave it to `devflow-spec`:
+
+- technical selection, architecture, structure, interface contracts, implementation steps.
+
+Boundary test: "what to do / why / what not to do / what could go wrong" stays; "how to implement" goes. In-bounds example: "方向 A 覆盖边界场景但流程更长，方向 B 简单但留下重发风险——推荐 A，因为漏洞主要出在重发。" Out-of-bounds example: "用 Redis 做缓存层，表加两个字段。"
+
+Recommendations are disposable conversation material that helps the user decide what they want; they never commit the project to a design.
+
+## Understanding Revision Rule
+
+When a user correction changes the goal, scope, exclusions, constraints, acceptance, terminology, actor, or a load-bearing assumption, it interrupts the current clarification chain:
+
+1. stop the pending question;
+2. update facts, assumptions, and understanding gaps;
+3. send a complete corrected Semantic Echo-Back; and
+4. wait for confirmation before asking another question or producing `Confirmed request`.
+
+A correction that changes none of those may receive a direct one-line acknowledgement, but it must not be treated as a confirmed request. Do not silently absorb a correction into a later question or the summary.
+
+## One-Question Discipline
+
+Ask exactly one question at a time only when a decision-impact gap remains. A question qualifies only when its answer could change scope, a constraint, acceptance, or a subsequent problem-space decision. Resolve qualifying gaps in this order:
+
+1. goal ambiguity;
+2. scope boundary;
+3. out-of-scope boundary;
+4. constraint;
+5. acceptance;
+6. remaining open question.
+
+Do not ask merely because a category is unfilled: record a fact-backed `none` or non-blocking unknown instead. Stop asking when no decision-impact gap remains and every non-blocking unknown is recorded in `Confirmed request`.
+
+Use this shape for every question:
+
+```text
+Question: <one question>
+Recommended answer: <answer and rationale>
+Why now: <risk or dependency this resolves>
+```
+
+After every answer, compare it with confirmed facts and the current request. An answer that introduces a load-bearing assumption, exposes a contradiction, or changes goal, scope, exclusions, constraints, acceptance, terminology, or actor triggers the Understanding Revision Rule before another question or summary. Otherwise, record the answer and continue only if another decision-impact gap remains.
+
+Do not ask for an answer that project facts establish. Do not ask a later-category question while an earlier qualifying category remains unclear. Use the user's language; avoid unexplained technical terms.
+
+## Ambiguity Signals
+
+Treat these as a need to clarify rather than infer:
+
+| Signal | Clarify |
+|---|---|
+| Vague quantifier: "better", "faster", "more" | Observable target or threshold |
+| Implicit scope: "add search" | What and where it applies |
+| Pronoun or missing context: "it", "like before" | Exact referent or precedent |
+| Missing actor: "notify" | Sender and recipient |
+| Unstated constraint: "make it fast" | Required metric or limit |
+| Solution-as-goal: "use Redis" | Desired outcome versus mandated tool |
+| Ambiguous boundary: "related changes" | Included and excluded surfaces |
+| Idea request: "有什么办法", "give me options" | Explore directions in the problem space and recommend one |
+
+## Fixed Summary
+
+When no clarification blocker remains, output exactly this request record and stop:
+
+```text
+Confirmed request:
+- Goal: <user outcome>
+- Scope: <included behavior and surfaces>
+- Out of scope: <explicit exclusions>
+- Constraints: <must-not-change conditions, or none>
+- Acceptance: <observable proof of success>
+- Identified gaps/risks: <holes, risks, and blind spots surfaced during exploration, or none>
+- Directions considered: <directions discussed with trade-offs, including rejected ones, or none>
+- Recommended direction: <recommendation and rationale within the problem space, or none>
+- Open questions: <none or unresolved blocker>
+- Status: clarified
+```
+
+This summary is the factual basis downstream skills — starting with `devflow-spec` — build on; record findings faithfully. It carries no implementation plan, solution-space design, lifecycle route, or handoff.
+
+## A/B/C Gate
+
+After the fixed summary, present A, B, and C and wait for the user's explicit depth choice. Record the selected `Depth` with the branch input: A starts Spec and B/C start Cut. A missing or changed depth returns facts to Core.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "A paraphrase is enough." | Surface assumptions and specific gaps. |
+| "Ask everything at once." | Ask one question, then wait. |
+| "The codebase answers user intent." | Code answers current facts, not desired behavior. |
+| "Clarification should pick the next skill." | The summary does not choose. Brainstorm presents A/B/C and starts only the user's selected branch. |
+| "A design or document belongs in the summary." | Record the request and exploration findings only. |
+| "The request looks simple, so the checklist can be skipped." | Simple-looking requests hide the most assumptions; report per-angle findings even when they are `none`. |
+| "The user wants speed, so skip a gate." | Compress wording, never gates. Speed comes from fewer real gaps, not skipped structure. |
+
+## Verification
+
+- [ ] Semantic Echo-Back included all fields, with `none` where a field had no content.
+- [ ] The echo-back was confirmed or corrected before further clarification.
+- [ ] Questions were one at a time, fact-backed, and each used the `Question / Recommended answer / Why now` shape.
+- [ ] The multi-angle checklist ran with per-angle findings, and those findings reached the summary.
+- [ ] Recommendations stayed inside the problem space.
+- [ ] Changed understanding was re-echoed and confirmed before proceeding.
+- [ ] `Confirmed request` includes every fixed field, followed by an explicit A/B/C user gate.
+- [ ] The summary contains no design, route, handoff, documentation, recovery, or implementation instruction.

package/assets/skills/devflow-build/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: devflow-build
+description: "Use when implementing an approved plan, applying Karpathy-style minimal changes, fixing code, refactoring narrowly, creating implementation slices, touching files surgically, or keeping every diff tied to the user goal. Implements only the selected smallest useful solution."
+---
+
+# DevFlow Build
+
+Implement only the selected smallest useful solution.
+
+## Context
+
+Receives a `CUT_PASS` Cut Decision from `devflow-cut`, either through the direct A/B/C success edge or a Core-selected non-unique path.
+
+- Depth A/B input: `CUT_PASS` plus a user-approved Plan Pack at `docs/plans/YYYY-MM-DD-<short-kebab-name>.md`. Confirm the plan stays within the recorded Cut scope; re-run only affected Cut gates if the plan introduces scope, dependency, abstraction, or file-responsibility drift.
+- Depth C input: `CUT_PASS` plus the approved design contract; no Plan Pack is required.
+
+When no plan file exists, the approved design and Cut Decision form the Build Contract basis; skip the plan checker.
+## Plan Review
+
+Load `skills/devflow-build/references/build-methods.md` after this review and before implementation slices. It owns the detailed minimal-change and slice discipline.
+
+Before editing, reconcile the plan against the current codebase — executability review, not redesign:
+
+1. Anchors: every `Modify` symbol/anchor and interface in the plan still exists and matches.
+2. Behavior: each task's `Current behavior` still describes the code.
+3. Steps: unambiguous, with verification commands that can run in this environment.
+4. Skills: every skill declared in `External Skills` (Cut Decision or plan header) is actually loaded through the platform's skill mechanism, or the reason it does not apply is recorded; loading alone is not completion — Build requires the specialist's returned result, not-applicable, or failure facts. A specialist result implying structure outside the approved scope returns scope-drift facts to `devflow-core`, not silent adoption.
+
+Any failed check, unclear instruction, or critical gap: stop and return `BUILD_BLOCKED` with the facts to `devflow-core`. Do not guess, do not silently repair the plan. Reviewing fidelity is not re-deciding the mechanism.
+
+For Depth C (no Plan Pack), run the same review against the approved design contract: confirm the symbols and behaviors it names still exist. Depth C keeps Build freedom inside the Cut Decision; it does not skip this review or the Stop Protocol.
+
+## Build Contract
+
+Before editing, state:
+
+```text
+Goal: ...
+Will touch: <files/modules>
+Not doing: ...
+Skills loaded: <skill-name> / none
+Standards: 可选——引用 code-standards 条目编号
+Narrowest verification: ...
+```
+
+If work touches more than one file or one logical step, create Implementation Slices.
+
+## Plan Pack
+
+When saving a plan file, use `docs/plans/YYYY-MM-DD-<short-kebab-name>.md`, resolved from the current target project's root, unless that project already documents another plan/spec path. Do not save implementation plans under `docs/features/`; that directory is for feature ledgers.
+
+For multi-step work, tasks must cite the approved source, be small and verifiable, and follow the required task contract (Task: / Task type: / Files: / Interfaces: / Current behavior: / Target behavior: / Change mechanics: / Call impact: / Steps: / Acceptance: / Verify: / Comments: / Not doing:) defined in `skills/devflow-plan/SKILL.md`.
+
+No unresolved markers. For `Code change`, follow the recorded file symbol/anchor, `Current behavior`, `Target behavior`, `Change mechanics`, and `Call impact`; do not re-decide the implementation mechanism in Build. The verification step must retain its trigger/input, expected result, and command or manual scenario. `Documentation-only` applies only to tasks with no runtime code files and explicit `documentation-only` interfaces. No "add tests" without naming the behavior. No "handle edge cases" without naming the edge case. No "similar to Task N" shortcuts; repeat enough detail for each task to stand alone.
+
+Before Build, run `node scripts/devflow-plan.js <plan-file>` when a plan is saved to a file. If not found at `scripts/devflow-plan.js` (project-level), try `~/.codex/scripts/devflow-plan.js` or `~/.claude/scripts/devflow-plan.js` (user-level). Do NOT look under `skills/scripts/`. See `core-methods.md` Script Path Resolution.
+
+## Implementation Slices
+
+```text
+Implementation Slices:
+- Slice 1: files / change / per-slice verification
+- Slice 2: files / change / per-slice verification
+```
+
+Rules:
+
+- Keep each slice independently understandable.
+- Prefer a slice that can run a focused check before the next slice.
+- Merge slices that cannot be verified separately.
+- Do not add work removed by `devflow-cut`.
+
+#### Slice 自检清单
+
+每个 slice 输出后逐项自检（八大原则）：
+
+1. 最小切片——一次只改一件事，本 slice 可独立理解。
+2. 参考项目规范——声明遵循的 code-standards 条目（如分层红线/缓存策略）。
+3. 复用现有能力——不重复造轮子，先查项目复用点。
+4. 分层清晰——实体/服务/控制分离，不越层。
+5. 缓存语义正确——读查缓存、写失效缓存。
+6. 可读性——方法短、命名表意。
+7. 副作用隔离——授权/持久化/缓存/远程调用不隐藏在无标注块内。
+8. 可证明——本 slice 有可运行的最小验证。
+
+## Execution Mode
+
+The plan's `Execution mode` (`sequential` | `single-subagent` | `fan-out`) is chosen at Plan approval and passed to Build; Build does not re-decide it. `sequential` runs tasks in dependency order as the Build agent itself; `single-subagent` delegates the whole plan to one executor subagent while the main agent only schedules; `fan-out` runs independent tasks as parallel subagents and dependent tasks in sequence after their inputs land.
+
+### Single-subagent dispatch
+
+- The main agent does not execute tasks. It dispatches the whole approved Plan Pack to one executor subagent, waits for the return, and then merges the returned evidence and enters Prove once.
+- The subagent runs all tasks in dependency order inside one context under the same Plan Review and Prewalk read discipline, appends actual evidence to the plan's Execution Trace, and returns the merged task results and evidence, or `BUILD_BLOCKED` facts.
+- The main agent may send one bounded follow-up when the return misses evidence; anything still incomplete is returned to `devflow-core` as `BUILD_BLOCKED` facts. The subagent never declares done, never enters Prove, and never re-decides the mode or the Cut scope.
+
+### Fan-out dispatch
+
+- Two tasks may run in parallel only when their `Files` touch disjoint file/symbol sets and neither `Interfaces` consumes a symbol the other `Produces`; otherwise run the producer first.
+- Each subagent runs one task contract under the same Plan Review and Prewalk read discipline, and returns the task result or `BUILD_BLOCKED` facts.
+- The main agent merges returned results, reconciles cross-task file overlap, runs the unified `Diff Self-Check`, and enters `devflow-prove` once with merged evidence — never per-subagent.
+
+`single-subagent` and `fan-out` are scheduling only; they do not change Plan Review, Stop Protocol, Cut scope, or the single Prove gate.
+
+## Source Check
+
+When correctness depends on a framework/library/API version:
+
+1. Detect the stack/version from dependency files.
+2. Prefer official docs or local project docs.
+3. If official/current docs cannot be checked, mark the pattern as unverified.
+4. If docs conflict with existing project style, surface the conflict.
+
+Output:
+
+```text
+Source Check: <version/source checked or unverified>; decision <why>
+```
+
+## Surgical Rules
+
+- Touch only files required by the user goal.
+- Match the existing project style.
+- Do not refactor unrelated code.
+- Do not add speculative flexibility.
+- Do not add a new abstraction for one caller.
+- Remove only unused code created by your own change.
+- Keep each change small enough to verify.
+- If a changed line cannot be tied to the user goal, remove it.
+- For bug fixes, prefer the shared root-cause fix after caller/reference search; do not patch only the named symptom when sibling callers remain broken.
+- If you keep an intentional simplification with a known ceiling, add `devflow: <ceiling>, revisit when <trigger>` near the shortcut.
+
+## Code Comment Discipline
+
+Comments are part of the implementation, not an afterthought. The spec's Code Documentation section and the plan's Comments field define what needs documentation — this section enforces it during Build.
+
+### What needs comments
+
+| Code element | When | What to write |
+|---|---|---|
+| New file or function | When the approved Spec/Plan, project convention, public contract, or a non-obvious decision requires explanation | Explain the decision, protected contract, failure condition, or purpose that code alone does not make clear |
+| Changed function (logic change) | When it changes an existing documented contract or introduces a non-obvious reason | Update the relevant explanation or add a concise WHY comment |
+| Non-obvious logic | When the WHY is not clear from the code | Inline comment: explain the reasoning, not the mechanics |
+| Business rule in code | When code encodes a domain rule | Inline comment: which business rule, who defined it, link to spec if possible |
+| Workaround/fix | When fixing a bug or working around a limitation | Inline comment: what was broken, what the fix does, link to issue if possible |
+| Config/constant | When value is non-obvious | Inline comment: why this value, what it controls |
+
+### Comment rules
+
+- **Explain WHY, not WHAT.** `// increment counter` is noise. `// retry counter: stop after 3 to avoid locking the account` is useful.
+- **Match the project's existing comment style and language.** If the project uses JSDoc, use JSDoc. If comments are in Chinese, write in Chinese.
+- **Make required comments durable.** A developer or LLM reading the code later should understand the documented decision and boundary without reconstructing it from history.
+- **Do not comment obvious code.** `let x = 1` does not need a comment. But `let x = 1 // start from 1, not 0, because the API is 1-indexed` is useful if the 1-indexing is non-obvious.
+- **Update comments when you change the code they describe.** Remove or correct stale comments; do not preserve incorrect explanations merely because a comment once existed.
+
+### Comment output check
+
+After implementation, before Diff Self-Check, verify:
+
+```text
+Comment Check:
+- Required by Spec/Plan/project convention: <locations and reason, or none>
+  - Required comment present: <yes/no per location>
+- Non-obvious decisions or boundaries: <locations and reason, or none>
+  - Inline comment present: <yes/no per location>
+- Comment style: matches project / N/A
+```
+
+If a specified or triggered comment is missing, add it before proceeding to Diff Self-Check.
+
+## Testing Rule
+
+- Behavior-changing code: prefer a focused test or reproducible scenario.
+- Bug fix: prove the original symptom or add a regression check when feasible.
+- Docs/rules/skills: validate required wording, frontmatter, links/paths, and scenarios.
+- Static text-only changes can use search-based verification.
+
+## Diff Self-Check
+
+After editing, run:
+
+```text
+Diff Check: Does each change directly serve the goal? Per file: Goal link / Behavior changed / Why this file / Verification.
+Style Check: Does it match existing style?
+Scope Check: Does it include unrequested behavior or drive-by refactor?
+Verification Check: Is there a narrow runnable proof?
+```
+
+If any file has no goal link, remove that change.
+
+## Anti-Rationalization
+
+| Excuse | Reality |
+|---|---|
+| "I'll clean this nearby thing too." | Note it separately; do not mix it into this diff. |
+| "A helper makes it nicer." | One caller is not enough unless local convention requires it. |
+| "We'll verify everything at the end." | Verify slices when focused checks exist. |
+| "Docs changes do not need proof." | Docs/rules/skills need validation just like code. |
+| "The issue only mentions one caller." | Check sibling callers before choosing the fix location. |
+| "The plan is approved, so I just execute." | Plan Review comes first: stale anchors or unclear steps return `BUILD_BLOCKED` to Core. |
+| "I'll infer the missing step." | Guessing past a gap is forbidden; unclear instructions return `BUILD_BLOCKED` facts. |
+| "The code is self-explanatory." | That does not waive a comment required by the approved contract, project convention, or a non-obvious boundary. |
+| "Comments will get stale." | Keep a required comment accurate or remove a stale one; a stale explanation is not a reason to skip a needed decision record. |
+| "I'll add comments after it works." | Add required comments in the same slice so implementation and its stated constraints stay aligned. |
+| "The function name is clear enough." | A clear name can make extra narration unnecessary, but it cannot replace a required WHY, business rule, or compatibility constraint. |
+
+## Stop Protocol
+
+Stop executing immediately and return `BUILD_BLOCKED` with the blocking facts to `devflow-core` when:
+
+- a Plan Review check fails (dead anchor, stale behavior, missing interface, unclear step)
+- a dependency, tool, or declared external skill is missing and the task depends on it, or its returned failure facts block the approved work
+- verification fails repeatedly for the same task
+- the plan has a critical gap that prevents starting or continuing
+
+Do not guess, do not force through blockers, and do not broaden scope to escape. Core decides whether to revise the plan, re-clarify with `devflow-brainstorm`, or enter `devflow-pua`.
+
+## Handoff Gate
+
+Do not say done. A completed Build directly enters `devflow-prove` with:
+
+```text
+Proof target: ...
+Suggested command/scenario: ...
+Known unverified: ...
+```
+
+## Verification
+
+Before leaving this skill, confirm:
+
+- [ ] Plan Review passed or concerns were returned to `devflow-core` as `BUILD_BLOCKED`.
+- [ ] Declared external skills were loaded, or the exception reason was recorded in `Skills loaded`.
+- [ ] Build contract exists.
+- [ ] Cut gates passed or were run.
+- [ ] Slices exist when work is multi-step.
+- [ ] Code Comment Discipline check is complete — every Spec/Plan/project-convention or non-obvious-boundary comment requirement is satisfied.
+- [ ] Diff self-check is complete.
+- [ ] Proof command/scenario is ready for `devflow-prove`.

package/assets/skills/devflow-build/references/build-methods.md

@@ -0,0 +1,40 @@
+# DevFlow Build Methods
+
+Owner: `devflow-build`. Load this reference after C `CUT_PASS`, an approved A/B Plan, or Core selects Build for a non-unique artifact.
+
+## Method 11: Karpathy Minimal Change
+
+Touch only files necessary for the approved goal. Match project style, preserve contracts, avoid one-caller helpers and speculative options, and remove only code introduced by the current change when it becomes unused.
+
+For each changed file record:
+
+```text
+Goal link:
+Behavior changed:
+Why this file:
+Verification:
+```
+
+## Method 12: Implementation Slices
+
+Split multi-step work into one to five testable slices. Each slice names files, user-visible or contract behavior, verification, and comment requirements. Verify a slice before moving on whenever a focused check exists.
+
+## Readability Outcome Check
+
+Before handoff, review changed code from the perspective of a maintainer familiar with the project but not this change. Use names, structure, extraction, comments, and tests as appropriate; do not apply any technique mechanically.
+
+```text
+Readability Check:
+- Intent: each changed unit has a business-purpose name or locally clear role
+- Rules: important conditions use domain terms or small named predicates
+- Failure paths: invalid, exceptional, and boundary behavior is locally visible
+- Side effects: authorization, persistence, cache changes, remote calls, and response mapping are not hidden in an opaque block
+- Convention: naming, layering, errors, logging, cache, and tests follow the nearest comparable project code, or the deviation is recorded
+- Trade-off: <none or concise reason why this is the clearest safe option>
+```
+
+A function may contain several steps when they form one coherent business narrative. Extract or split only when doing so makes responsibility, testing, reuse, or local understanding materially better.
+
+## Build Comments
+
+The approved Spec/Plan and local project convention define required code comments. Add a comment when it records a protected contract, failure condition, business rule, compatibility boundary, or other non-obvious reason; inline comments explain reasons, not syntax. Markdown runtime contracts use headings and fixed output shapes rather than narrative comments.

package/assets/skills/devflow-core/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: devflow-core
+description: "Use when starting development work, routing Problem, Fast, Design-lite, Design, Build, or Recovery work, investigating issues, handling requirements or bugs, or deciding which DevFlow skill owns the next lifecycle step. Before any creative work — creating features, building components, adding functionality, modifying behavior, or defining an unapproved problem-directed change — select devflow-brainstorm for a Confirmed request; pure Q&A, lookup, verification, and investigation-only reports remain exceptions."
+---
+
+# DevFlow Core
+
+Route work through the smallest reliable lifecycle. Core owns next-step selection only when an artifact has no unique successor; skills directly execute the A/B/C success edges defined below.
+
+## Activation Evidence
+
+```text
+Skill Activation: devflow-core
+Trigger: <user words or task shape>
+Route: Problem / Fast / Design-lite / Design / Build / Recovery
+Next skill: <skill name or none>
+Status: [DevFlow: <node> -> <next> | awaiting approval / in progress]
+```
+
+While a DevFlow lifecycle node is active, end each user-facing message with one status line: `[DevFlow: <node> -> <next> | awaiting approval / in progress]`. It reflects the current node without reloading the owner skill. Keep progress visible in the persistent UI: maintain a `todo_write` list with one item per active work unit (lifecycle node, background job, or subagent), marking it `completed` the moment it settles, and use `create_goal` for the session's long-running objective.
+
+## Context Map
+
+Read `skills/devflow-core/references/core-methods.md` before route selection. It supplies Method 0, shared route rules, and the owner map. Do not load all lifecycle references by default.
+
+Read the narrowest relevant project facts, then progressively recall learning and project knowledge. Scan available skills and record a matching external specialist skill; a specialist may perform bounded specialist work inside the current node while DevFlow retains route and node ownership.
+
+Before a route-specific decision, load only the selected owner reference:
+
+| Selected work | Required reference |
+|---|---|
+| Cut | `skills/devflow-cut/references/cut-methods.md` |
+| Spec or Plan | `skills/devflow-spec/references/spec-plan-methods.md` |
+| Build | `skills/devflow-build/references/build-methods.md` |
+| Prove or PUA | `skills/devflow-prove/references/proof-recovery-methods.md` |
+| Learn | `skills/devflow-learn/SKILL.md` |
+
+```text
+Facts: read/confirmed <files or commands>
+Methods: read/confirmed core-methods.md; selected owner references <paths or none>
+Knowledge recall: none / learning index + matched card / project knowledge entry + matched docs
+Skill Discovery: none / <skill-name> (matched: <why>)
+Unknowns: <none or specific unknown>
+```
+
+## Routes
+
+| Route | Use when | Core action |
+|---|---|---|
+| Problem | A reported problem has no explicit fix request. | Prove facts first, then select later work only if a change is known. |
+| Fast | Pure answer, lookup, verification, or one local low-risk change. | Sense, then narrow proof. |
+| Design-lite | Existing feature, one clear low-risk path, quick proof. | State goal, acceptance, exclusions; select Cut before Build. |
+| Design | New requirement, behavior or architecture change, ambiguity, or multiple options. | Select Brainstorm; after confirmation its user-selected A/B/C path directly starts Spec or Cut. |
+| Build | User asks to implement, fix, build, or land an approved change. | Select Cut, then Plan when construction needs several steps, then Build and Prove. |
+| Recovery | Same target remains wrong after correction or proof failure. | Select PUA, consume recovery facts, then choose a different path. |
+
+## Core Flow Map
+
+```text
+A direct success: Brainstorm -> Spec -> Cut -> Plan -> Build -> Prove
+B direct success: Brainstorm -> Cut -> Plan -> Build -> Prove
+C direct success: Brainstorm -> Cut -> Build -> Prove
+
+CUT_REDUCE, CUT_REUSE, CUT_BLOCKED, scope drift, BUILD_BLOCKED,
+Proof FAIL or BLOCKED, and PUA recovery -> Core selects the next owner or stop.
+```
+
+## Core Return Boundaries
+
+- Brainstorm returns only clarification or missing-depth facts; a selected depth directly starts A -> Spec or B/C -> Cut.
+- Spec directly sends an approved A-branch Spec to Cut; a non-success result returns facts to Core.
+- Cut directly sends `CUT_PASS` A/B to Plan or C to Build; `CUT_REDUCE`, `CUT_REUSE`, and `CUT_BLOCKED` return facts to Core.
+- Plan directly sends an approved A/B Plan to Build; scope-drift facts return to Core.
+- Build returns `BUILD_BLOCKED` facts when its Plan Review or execution is blocked.
+- PUA returns recovery facts after its method switch.
+- Prove returns PASS, FAIL, or BLOCKED and invokes Learn after PASS.
+
+Core selects only after a returned non-unique artifact. `CUT_REDUCE` and `CUT_REUSE` stop for user confirmation. Independent `devflow-adversarial` and `devflow-find-fault` review current material only and do not enter lifecycle routing.
+
+## Capability Dispatch
+
+- Unclear requirement, new feature, behavior change, or multiple options: select `devflow-brainstorm` for Semantic Echo-Back and a fixed Confirmed request.
+- Explicit spec or design document: select `devflow-spec` after confirmed request.
+- New structure, dependency, abstraction, configuration, folder, or generic capability: select `devflow-cut`.
+- Approved construction work: select `devflow-build` when Core receives a non-unique construction artifact; A/B approved Plans and C `CUT_PASS` enter Build directly.
+- Completion claim: select `devflow-prove` and require fresh evidence plus adversarial review.
+- Repeated same-target correction: select `devflow-pua`, then re-read facts and switch approach.
+- Reusable correction or verified PASS: select `devflow-learn` for a selective review.
+- Matched external specialist: perform bounded work inside the current owner's node and return result, not-applicable, or failure facts; a specialist never selects a lifecycle owner, depth, or final status.
+
+## Verification
+
+Before leaving Core, confirm that shared methods were read, only needed owner references were loaded, the route matches facts, and every selected skill has a return artifact or stop condition.