dev-flow: Instructions file for Codex

Dev Flow Repository Instructions

This file defines how AI agents maintain this repository. Put repository-specific AI instructions, implementation constraints, and documentation-update rules here. CONTRIBUTING* guides human contributors; product README files guide users. The shipped Dev Flow Skills govern Host interaction with the product and remain in the locations listed under Skill Maintenance.

Authority

Before implementation work, read in this order:

1. the user's current explicit request and acceptance criteria;
2. CONTRIBUTING_zh-CN.md or CONTRIBUTING.md;
3. docs/PRODUCT.md or docs/PRODUCT_en.md;
4. the technical documents directly related to the change;
5. the current source code, schemas, package manifests, and executable tests for the affected surface.

Before a version-only release, read in this order:

1. release/README.md;
2. the selected product's release README under release/;
3. the current prepare and publisher contracts under release/;
4. the package manifest and current public-version metadata.

When documentation and executable behavior disagree, use the executable implementation to determine current behavior and update the affected documentation in the same change. Do not infer requirements from branch names, directory names, chat history, or historical design documents.

Documentation Responsibilities

Choose a document by its reader and purpose before editing it. A code change does not automatically require a README or PRODUCT change. Keep detailed explanations in their owning reference and link to them from user guides when needed.

Document	Reader and responsibility
AGENTS.md	Repository AI agents: instruction priority, scope, architecture constraints, implementation, review, validation, documentation maintenance, and release boundaries.
Root README*.md	End users: what Dev Flow does, suitable tasks, prerequisites, installation, starting and resuming work, common operations, necessary usage limits, and links to further help.
packages/*/README.md, docs/CODEX_en.md, docs/DEEPSEEK_en.md, docs/CLAUDE*, docs/ZCODE*	Users of that package or Host: setup, supported operations, troubleshooting, maintenance, removal, and Host-specific limitations.
docs/PRODUCT*	Product readers: target users, problems, business functionality, user workflows, product scope, and non-goals.
docs/DEMO*, docs/WEBUI*, docs/DESKTOP-PETS*	Users following a walkthrough or operating a specific interface; detailed interface and artwork guidance stays here.
docs/ARCHITECTURE*, docs/ARTIFACTS*, docs/WORKTREE-SOURCES*, docs/THREAT-MODEL*	Developers and integrators: component responsibilities, protocols, state and data rules, implementation design, and trust boundaries.
docs/CORE-RESPONSES*	Core and Host developers: success/failure envelopes, structured error detail, recovery instructions and response validation.
docs/COMMANDS*	Users and integrators needing exact commands, options, selectors, environment variables, and MCP inputs and results.
docs/SUPPORT-MATRIX*, docs/PROJECT-STATUS*, docs/WINDOWS-ADAPTATION*	Readers checking supported environments, delivered capability, recorded verification, and remaining limitations.
docs/ROADMAP*	Product readers: future outcomes and priorities, clearly distinguished from delivered capability.
CONTRIBUTING*	Human contributors: issues, proposals, development setup, validation, and pull requests.
MANIFEST*, docs/I18N*	Readers navigating documentation and source locations; translators checking maintained languages, document families, and translation consistency.
internal/README*, scripts/README*, tests/**/README.md, protocol/fixtures/README.md	Maintainers of those directories: local structure, development commands, test procedures, and fixture usage.
release/**/README.md, docs/RELEASE-STRATEGY.md, docs/VERSIONING.md, docs/TOOLCHAIN-BASELINES*	Maintainers: build environments, version policy, artifact preparation, verification, and publication procedures.
SECURITY.md	Users and researchers reporting vulnerabilities and checking the security reporting policy.
skills/dev-flow/core/ and Host Skill directories	Agents using the installed product: maintained Core interaction instructions and Host-specific authorization, workspace, and tool operations.