Codflow Governance

CodFlow Governance — change workflow

CodFlow is an Apache-2.0, self-hosted, cash-on-delivery (COD) e-commerce platform for Algeria, open-sourced for the first time. This skill is the workflow for landing a change. The repo contract (layout, commands, verification, boundaries, traps, security rules) lives in the root AGENTS.md — read it first; it is the source of truth. Package-specific commands and boundaries live in each package's AGENTS.md (cod-astro/theme01/AGENTS.md).

When to use

• You are about to change code, docs, schema, or CI in this repo.
• You are writing README feature claims.
• You are reviewing a contribution.

The change workflow

1. Locate the change

• Identify the package(s) affected (cod-server / cod-client-astro / cod-shared / cod-astro/theme01). Read the root AGENTS.md, then the package's AGENTS.md.
• Respect the cod-shared boundary: schema, queries, RBAC scopes, and error codes are defined there and only there. Do not duplicate them in a package.
• Migrations: add a new migration; never rewrite an already-applied one.
• Ask before adding a production dependency or changing the D1 schema.
• Keep engine logic out of cod-astro/theme01 (swappable theme layer).

2. Install dependencies

One install at the repo root covers every workspace (single root lockfile — never create per-package lockfiles):

npm ci

3. Make the change

• One logical change per commit. Conventional Commits (feat:, fix:, docs:, chore:, refactor:, test:, ci:).
• No explanatory code comments unless asked.
• Never commit secrets (API keys, carrier tokens, credentials). Real secrets go in wrangler secrets / .dev.vars (gitignored).
• Add or update a focused test for behavior changes.

4. Verify — never skip

• After any TypeScript change: run npm run typecheck in the affected package (theme01: npx astro check).
• After any behavior change: run npm test in the affected package.
• README claims must be code-verified: never write a feature claim the code does not implement. If a feature is partially built, say exactly that.
• Do not mark work complete until typecheck + tests actually pass.

5. Commit, branch, PR

• Work on a branch named feat/…, fix/…, chore/…, docs/….
• PRs must be small enough to review in one sitting (< ~500 lines).
• The PR template checklist must pass: no secrets, tests cover the change, README claims match code, conventional commit message.
• CI (typecheck + tests for cod-server, cod-client-astro, cod-client (legacy), and astro check + tests for theme01) must be green.
• When reviewing: README claims only what code does? Secrets absent? Tests included? Migrations additive?

6. Changelog

• User-visible changes go under [Unreleased] in CHANGELOG.md (Keep a Changelog), grouped by Added / Changed / Deprecated / Removed / Fixed / Security.
• Releases follow SemVer, are git-tagged, and announced via GitHub Releases.

Review checklist (use when reviewing a contribution)

• README claims only what the code actually does
• No secrets / credentials in the diff
• Tests cover the change (or an existing test covers it)
• Migrations are additive (new file, not a rewrite)
• cod-shared boundaries respected (no duplicated schema/scopes)
• Conventional commit message
• Typecheck + tests pass for affected packages

Security reports

• Never accept vulnerability reports as public issues — point reporters to GitHub private vulnerability reporting (see SECURITY.md).
• Acknowledgment target: 3 business days; coordinated disclosure.
• Supported versions: only main and the latest tag.