Contributing to Dev Flow

中文 | English

Dev Flow accepts reproducible defects, documentation corrections, platform support backed by final-artifact evidence, and bounded product improvements grounded in real development problems.

Change classification

Change	Requirement
Spelling, links, translation, or correction of existing behavior documentation	Open a bounded pull request directly and synchronize the affected document family and root README locales according to the I18n policy
Template or documentation-maintenance rule change	Explain the affected surface; do not change product versions or perform a release
Implementation defect that does not change public semantics	Identify the gap between the approved contract and actual behavior, then fix only that gap
User-visible behavior, Core/MCP contract, persistence, process graph, or host-adapter contract change	Explain the user problem, scope, acceptance criteria, and approach, synchronize implementation/tests/docs/i18n, and update CORE_VERSION when shipped Core changes
npm package version, npm publication, Tag, or GitHub Release	Do not make this an ordinary pull-request deliverable; maintainers run the separate release flow after product work is merged

When classification is unclear, open an Issue first and describe the user problem, current behavior, and expected result. Do not implement a large solution and then ask the specification to accept the completed code.

Opening an Issue

A useful bug report includes:

• the product and version, such as Core, dev-flow-codex, or dev-flow-deepseek;
• operating system, CPU, Node.js version, and host version;
• minimal reproduction steps;
• expected and actual results;
• logs or errors with secrets, private paths, and personal data removed;
• whether the issue concerns installation, explicit activation, Task transitions, Recovery, the data directory, or removal.

A product proposal should first explain the concrete user problem, why the current workflow cannot solve it, and how success would be measured. An implementation approach may be discussed, but it does not replace requirement definition.

Product feature proposal template

## User event

What actually happened?

## Current approach

How does the user handle it without Dev Flow?

## Facts Dev Flow can confirm

What can the Task, Action, repository, and retained evidence determine?

## Decision to make

Should the system continue, review, retry, block, or ask the user to decide?

## User-visible result

What change will the user ultimately see?

## Cost of error

What are the consequences of a false allow and a false block?

## Acceptance evidence

Which test, fault injection, or real Host journey demonstrates the result?

## Explicit non-goals

Which capabilities will this change not expand?

Product decision gate

Before implementation, a proposal must answer clearly:

1. Does it directly improve trustworthy continuation of a long-running task?
2. Is it based on Task, Action, repository observation, or retained records rather than only the agent's narrative?
3. Does it reduce the user's effort to judge current state and next step?
4. Can it establish a repeatable real-Host journey?
5. Does it retain one Core Task state?
6. Does it add unnecessary process steps?
7. Is it horizontal expansion only for another platform, Host, or interface?

A proposal that cannot explain the user problem, visible result, and acceptance method should not move directly into implementation.

Local environment

Repository development requires:

• Go >=1.26;
• Node.js >=24;
• pnpm >=11 <12.

Fork the repository on GitHub, then create a branch from your fork:

git clone https://github.com/<your-account>/dev-flow.git
cd dev-flow
git remote add upstream https://github.com/Innocent-children/dev-flow.git
git fetch upstream
git checkout -b <type>/<short-description> upstream/main
pnpm install --frozen-lockfile

Before editing, read the I18n policy, the Command Reference, and the documents directly related to the change.

Implementation principles

• Solve only the problem stated by the pull request; do not add future capabilities, generic frameworks, or unrelated refactoring.
• Keep Go Core as the sole authority for Tasks, nodes, legal transitions, recovery classification, and terminal outcomes.
• Keep Core's Git observation read-only; do not add shell, commit, push, merge, tag, or publication authority.
• Run only validation directly connected to the changed surface, acceptance criteria, or known risk.
• A user-visible behavior change must synchronize all nine root README files, docs/PRODUCT*, and affected technical documentation.
• A documentation correction must synchronize the paired Chinese/English technical family and every affected root README locale.
• When adding or changing a command, verify it against the package manifest, CLI parser, DSH lifecycle, Core parser, or MCP catalog and synchronize docs/COMMANDS*.
• Public npm installation examples use @latest; human-readable documentation contains no exact product release versions.
• An ordinary feature pull request that changes shipped Core behavior or contracts updates the machine-readable CORE_VERSION; it does not change npm release versions or perform Tag, npm, or GitHub Release operations.

Validation

At minimum, documentation changes should confirm that:

• Markdown, tables, code fences, and Mermaid render correctly on GitHub;
• every file in the language navigation exists and links back to the other locales;
• section structure, commands, platforms, and support claims are aligned in paired Chinese/English document families;
• all nine root README files keep position, capability, commands, platforms, stable support, and boundaries aligned;
• every ordinary installation example uses @latest, while exact product versions remain in machine-readable files and release records;
• docs/COMMANDS* matches the executable command and tool catalog;
• non-English files contain no placeholder translation or whole-section English fallback;
• the change does not broaden claims in the current Support Matrix.

For code changes, prefer targeted checks for the affected package, node, contract, or user story. Run repository-wide validation only at the final checkpoint required by the change contract:

pnpm run validate

Do not repeatedly run the complete suite as generic insurance, and do not present simulation, static checks, or user-performed results as real-host final-artifact evidence.

Pull request requirements

Create the branch from current main and explain:

1. the current problem;
2. what the change actually modifies;
3. the explicit non-goals;
4. validation performed and its result;
5. acceptance criteria and their corresponding tests or contracts;
6. the document families changed and locales synchronized;
7. the implementation source for each installation or command claim.

Concise Conventional Commit-style messages are recommended, for example:

docs: synchronize README locales
fix(store): reject invalid snapshot before writable open

A pull request should remain independently reviewable. Split documentation rewrites, product behavior changes, unrelated refactors, and version publication into separate changes.

Release boundary

Merging product work does not publish it immediately. Core, Codex, and DeepSeek have independent versions. After changes are merged, maintainers select the product, channel, and exact version, then run the fixed checks, version alignment, build, read-back, Tag, npm, and GitHub Release operations.

By submitting a pull request, you agree that your contribution is provided under this repository's Apache License 2.0.