Code FlowVersioned project conventions
Save a private convention draft, inspect its version history, and preview publication to a project repository. Commit the staged conventions file if future runs should inherit it.
Keep project guidance current
Settings → Projects & access keeps human-authored project guidance privately beneath CODEFLOW_HOME/conventions/. A saved draft does not change a repository and is never inserted into agent context automatically. External run content cannot author guidance through the team capability API.
Each save requires the exact observed revision. A concurrent edit returns HTTP 409 and preserves the editor draft. Compare the latest saved text, then deliberately keep your draft against that newer base or export it. Versions retain their original text, timestamp, hash, and note. The latest 32 revisions are retained; each holds at most 64 KiB of UTF-8 text. Line endings normalize to LF and nonempty guidance ends with a newline. History files use atomic durable replacement with private file permissions. Corrupt or inaccessible histories are left untouched, and a failed operation does not poison later writes.
Select a retained version and Preview saved revision before restoring. Restore as new revision requires both the current revision and the previewed version hash. It copies the old text into a new revision; it does not rewrite history or publish anything. Save or revert unsaved editor changes before restoring.
To activate guidance, select a repository belonging to this project and inspect its current file. Publish and stage file explicitly writes and stages .codeflow/conventions.md. The repository must be clean and idle. Publication checks the saved private revision, repository HEAD, and exact source file hash while holding the private revision lock and the repository lock. Non-project repositories, symbolic .codeflow components, symbolic files, symbolic .git markers, binary files, and oversized source files are refused. Code-flow stages this single guidance path even if it is ignored; it does not commit or push.
Review and commit the staged file yourself. Only .codeflow/conventions.md at a run's committed base ref is read into context, before existing vendor guidance files. The existing aggregate convention limit remains 6,000 characters; longer guidance is truncated with a prompt to read the repository file. Publishing a draft without committing it does not change conventions for future runs. Locked-down imported runs continue to inherit trusted parent/base guidance according to existing run creation rules.
Publication attempts restore the prior target file if staging fails and the source has not changed concurrently. If another tool changes HEAD or the target during publication, those changes are preserved and the UI requires a new inspection. Review any reported Git index error before retrying.
API contracts: GET /api/projects/:id/conventions, PUT with {revision,text,note?}, POST /restore-preview with {version}, and POST /restore with {revision,version,hash}. GET /publication?repo=PATH returns the observed {sourceHash,head,clean,text,...}. Explicit POST /publish requires {repo,revision,sourceHash,head}. Publication authorization is checked against the project's repository membership and current activity on the server; private drafts are not automatic execution instructions.