Skip to content

How to Help Improve It (Plain Language)

Want to help make WorkWingman better? Here's how contributing works, in plain terms. The short version: work on a copy, get a second opinion before you save it into the project, make sure the automated checks pass, and keep secrets out.

The basic habit

Think of the project's main code like a shared, tidy kitchen. You don't cook your experiments directly in the shared kitchen — you work on your own copy (a "branch"), and only bring your dish back once it's good and someone (or something) has checked it.

The rhythm looks like this:

  1. Make a branch. Your own copy of the code to work in.
  2. Make your change.
  3. Get a second opinion before saving it into the project's history (more below).
  4. Save it (a "commit").
  5. Open a pull request — basically, "here's my change, please consider adding it."
  6. Let the automated checks run and pass.

Review before merge — the important one

Before your change gets locked in, WorkWingman asks you to run a second-opinion review (the /codex-review step). A fresh, independent reviewer looks over exactly what you changed and flags anything that looks like a bug, a security problem, or something sloppy.

This isn't optional, and it isn't a comment on you — it's a required safety net. Even great cooks have a second person taste the dish before it goes out. You fix what it finds (or have a good reason not to), and only then do you save the change.

Why tests and review matter here

WorkWingman handles real, personal things: your job history, your documents, your passwords. A small mistake could mean a form filled wrong or, worse, a secret handled carelessly. So the project leans on two safety nets:

  • Automated tests — little checks that confirm the app still behaves. They run automatically on every proposed change, and they have to pass.
  • The second-opinion review — a fresh set of eyes on your change before it's accepted.

Between them, most mistakes get caught before they ever reach anyone's real data.

Keep secrets out

The single most important rule: never save secrets into the project.

  • The password vault file (the .kdbx file) holds real passwords. It must never be committed. Once something is in the project's history, it's very hard to fully remove.
  • The same goes for build leftovers and your own local data — none of that belongs in the shared project.

When in doubt: if a file contains anything personal or secret, it stays on your machine only.

Keep the two guides in step

WorkWingman keeps two versions of its docs: a technical one for engineers and a plain one (like this page) for everyone. If you change how something works, please update both so they don't fall out of sync. And only ever describe things that actually work today — anything still being built belongs under a clearly-labeled "Roadmap" note, not written up as if it's finished.

This isn't just a polite ask anymore — it's an automatic check. When someone changes the app's code without touching the docs, the project's robot checker (the same one that runs the tests) flags it and blocks the change. It also checks that every technical page has its plain-language twin, that no page is orphaned (unreachable from the index), and it nudges big changes to add a chapter to the "making of" story. Docs stay honest because the machine insists on it.