Project etiquette (ship sequence)

Why this exists

Shipping is a pipeline of gates, not a single “push and hope.”
The same sequence works for almost any project (Python, Node, Rust, monorepos):

Blast radius → Fix → Test → Update project → Update docs → Build → Commit → CI green → Publish

Skip a gate only when the user explicitly says so (e.g. “docs later”, “no publish”).

When to use

• User asks to finish / ship / release a change.
• Phrases like: “test everything, if it passes update everything, build, commit to CI, if it passes publish to PyPI.”
• Multi-hour builds where you must not leave the tree half-shipped.

Portable gate chain

Execute in order. After any failure, stop advancement until that gate is green.

0. Blast radius (before large edits)

• Activate change-safety (skill_activate(name=change-safety)) when available.
• Name the surface, list coupled neighbors, plan paired checks + manual smoke for UI/chrome/messengers that unit tests miss.
• Prefer durable architecture over patch loops for known failure classes.

1. Fix / implement

• Complete the requested behavior.
• Prefer small, verifiable steps; keep the tree runnable.
• Note risks (migrations, breaking APIs, signing, secrets).

2. Test (hard gate)

• Discover how this repo tests (pytest, npm test, cargo test, make check, …).
• Open .github/workflows/ (or equivalent) and run those commands locally before push. Pytest-only is not CI.
• Run the full suite when the user asked for “everything”; otherwise run the subset that covers the change plus the project CI lint/type/docs steps.
• Add or update tests when behavior changed.
• Do not commit known-failing tests unless the user wants a WIP commit.
• Do not push until the local CI commands are green.

3. Update the project

• Bump version only when shipping a real release (semver: patch for fixes, minor for features).
• Do not bump version for docs-only fixes (manuals, What's new catch-up, README typos, help sync). Commit as docs: on the current version; users get the notes on the next real release or from git/F1 after rebuild.
• Align version surfaces if the repo has more than one (package.json, Cargo.toml, …) when you do bump.
• Keep assets/config consistent with the change.

4. Update documentation

• User-visible change → CHANGELOG / release notes / help docs.
• Developer-facing change → README / architecture notes as the repo expects.
• Run any docs sync/check scripts the project provides.
• Docs should describe what the user does, not only internal renames.
• Docs-only → no version bump / PyPI / release tag unless the user explicitly asks.

5. Build

• Produce what CI/release expects (wheels, bundles, desktop artifacts).
• A green unit suite with a broken package build is not done.

6. Commit

• Stage only intentional files (no secrets, no local noise).
• Message: complete sentences; conventional prefix when it fits (fix:, feat:, docs:, release:).
• One logical theme per commit when practical.
• Note Risk: / Smoke: when fragile zones were involved.

7. Push and wait for CI

• Push to the integration branch the project uses (main / master) only after the local CI commands are green.
• Wait for remote CI to finish. Report the run URL when available.
• Red CI → run the failed step locally, fix until it is green, then push. Do not push a guess. No publish while red.

8. Publish (only if asked and CI is green)

• Tag release if the project uses tags for installers/changelogs.
• Publish packages (PyPI, npm, crates.io, …) only with existing credentials and project conventions.
• Confirm the published version is reachable (e.g. PyPI JSON, npm view).

Response format (report back to the user)

After a ship sequence, summarize with a short table:

If blocked, state which gate and the smallest next action.

Anti-patterns

• “It works on my machine” without running the project’s test command.
• Pushing after pytest-only when CI also runs ruff / mypy / docs.
• Pushing a CI-fix commit without re-running the failed CI step locally.
• Committing version bumps without changelog/docs.
• Publishing before CI finishes (or ignoring a red run).
• Force-pushing shared mainline branches.
• Leaving half a release without telling the user.
• Treating green CI as proof that title bar / live bots / WebView embeds work.

Adapting to a new repo

1. Read README / CONTRIBUTING / AGENTS.md / CI workflow.
2. Map each gate to local commands (record them in the session brief if long-lived).
3. Prefer project scripts over inventing one-off publish paths.
4. Keep a change-safety checklist for this repo’s fragile zones.

RemedyAI appendix (this monorepo)

Use when cwd is the RemedyAI tree (or user says “this project”).

Also respect root AGENTS.md (installer naming, version surfaces, smoke matrix). For end-of-session continuity use skill session-handoff.

When developing Remedy itself (self-inject + gauntlet + soak + stress), activate self-dev-loop first — it sequences self-inject, gauntlet-security, soak-product, stress-suite, and this ship chain.