Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
51 lines (32 loc) · 5.02 KB

CONTRIBUTING.md

File metadata and controls

51 lines (32 loc) · 5.02 KB
Raw

Contributing

Thanks for considering a contribution! This repo has a deliberate, narrow philosophy, and most declined PRs are well-executed work that simply didn't know about it. Read this first; it will save you effort and tell you where your work will land best.

The one rule everything follows from

This repo is a universal template. People fork it and adapt it to their own market, language, and profile. Upstream stays market-agnostic, person-agnostic, and Claude Code-native. The corollary: a contribution is judged by fit to this rule first, execution quality second. Well-built but off-policy still gets declined (kindly, with reasons).

What gets merged

  • Universal customization features: anything that makes the fork-and-adapt path better for everyone. Precedent: /add-template (#30), /add-portal (#37).
  • Robustness and correctness fixes with the failing case demonstrated. Precedent: NaN flag validation (#35), HTML entity decoding (#55, #56), salary column detection (#64).
  • Docs that close real gaps: platform-specific setup (#41, #60), stale references (#36, #68).
  • Infrastructure that reduces review burden and is argued from evidence, not speculation. Precedent: CI (#59), which caught a latent bug while being built.

What gets declined

  • Market- or country-specific skills and content. One country's portal opens the door to every country's portal; there is no principled stopping point. Precedent: #31 (India), #39 (France, despite an honest and excellent PR), #67 (China). The in-tree portal skills are either country-agnostic (linkedin-search) or the maintainer's own demonstration instance (the Danish portals).
  • Personal profile data. The template ships placeholders; your populated profile lives in your fork. CI enforces this (placeholder-integrity). Precedent: #17, #72.
  • Alternative-harness ports and duplicate workflow sources. The markdown specs ARE the implementation; a second copy (another agent CLI, an orchestration layer, a wrapper command) drifts from the first the moment either changes. Precedent: #44, #49, #66.
  • Speculative infrastructure. Complexity must be argued from a problem that exists, not one that might. Precedent: #63.
  • Kitchen-sink PRs. One concern per PR. Bundles get asked to split (#73) - and splits get reviewed fast (#75, #76 arrived within the hour and were handled same-day).

The bar for new commands

The core lifecycle is feature-complete: /setup → /scrape → /rank → /apply → /interview → /outcome → calibration back into /setup, with /expand, /upskill, /add-template, /add-portal, and /reset around it. Every stage of a real job hunt has an owner.

A new command therefore faces a high bar. The test that admitted the existing ones: does it operationalize something error-prone that already exists in the framework (documented machinery nothing executes, data something writes but nothing reads)? "Useful" and "possible" are not sufficient; the strongest proposals connect two things that already exist without modifying either (#43, #54).

Claims get verified

Reviews here are empirical. Bug reports are reproduced on master before the fix is considered; "all tests green" is checked against whether the tests can distinguish master from the fix. PRs whose premise doesn't reproduce get declined even when the code is fine - it has happened (#35's converter fix, #52's first version). You can make this fast:

  • State the failing case and how to reproduce it.
  • Put CLI tests in .agents/skills/<name>/cli/tests/ (bun test, network-free where possible); Python tool tests in tests/.
  • Run what CI runs: python tools/lint_skills.py, bun run typecheck in touched CLIs, and the relevant test suites.

Building for your own market? Do this instead

  1. Fork the repo and run /add-portal with your local job board - it scaffolds a portal skill matching the shipped contract, and /scrape picks it up automatically.
  2. Announce your fork in the pinned Community forks & adaptations discussion so others can find it.

Market-specific skills are genuinely valuable - they just live in forks, where their maintainers can test them and their users can find them.

Practical notes

  • Portal-skill contract: search/detail commands, --format json|table|plain, stderr JSON errors with exit 1, backoff on 429/5xx, zero runtime dependencies by default. See /add-portal's spec and linkedin-search as the reference implementation.
  • Personal-use boundaries: portal skills that touch ToS-restricted sources carry a prominent personal-use-only warning, and CI deliberately makes no live portal requests. Don't "fix" that.
  • LaTeX changes: both templates must compile (lualatex for the CV, xelatex for the cover letter) and hold their exact page counts. CI smoke-checks this.

Questions and proposals are welcome in Discussions - an Idea thread costs nothing and can save you building the wrong thing :-)