Developer guide

Respect the boundary

Before writing code, internalize the deterministic/reasoning split described in the architecture. Deterministic stages are pure Python and must stay reproducible. Reasoning stages read a versioned prompt and write a validated file. Keeping the two apart is what keeps the system cheap and legible.

Secrets handling

Real credentials live only in .careeros/secrets.env, which is gitignored. Source it — never print, cat, or grep its contents. Config fields that end in _env hold the name of an environment variable, not the value. Tokens are never persisted raw; the token-exhaustion cache stores only a hash fingerprint.

The failure-handling principle

When any non-trivial step can't complete, the agent doesn't guess or silently skip. It:

• Clearly explains what failed;
• Explains why, if known;
• States the impact on the current run;
• Presents the options — fix and retry, continue with reduced functionality, or abort;
• And waits for explicit confirmation before continuing.

This holds uniformly across every stage, even under a permissions-skipping flag. The agent never makes assumptions about what you'd prefer.

Run the tests

$ pip install -e ".[dev]"
$ pytest

Debug one stage at a time

Because every stage reads and writes files, you can run any single stage against an existing run directory without re-running the whole pipeline.

$ careeros discover --provider remoteok --dry-run --limit 3
$ careeros dedupe
$ careeros constraints
$ careeros lint path/to/resume.md
$ careeros verify-resume path/to/resume.md