kevin-mok/readme-recruiter-sync

Readme Recruiter Sync

Keep the root README.md aligned with the repository before commit or docs workflows ship changes. Focus on truthfulness, recruiter-first information hierarchy, runnable onboarding, repo-based tech-stack explanation, and a consolidated recruiter-facing hook.

Quick Start

1. Read references/readme-contract.md.
2. Inspect the root README.md and the files the current change touches.
3. Verify whether the README still matches the repository and recruiter-readability bar.
4. If any issue is fixable now, return update_in_same_change and block the commit unless README updates are included.
5. Return blocked only when the README cannot safely be fixed inside the current change scope.

Outcome States

• pass_no_change: README is accurate and passes the recruiter-first gate.
• update_in_same_change: README can be made compliant in the same change and must be edited alongside the scope change.
• blocked: README has required fixes but the current commit scope is not safe for in-scope edits.

Workflow

1. Determine whether the gate applies.
   • Always apply before commit or push workflows finalize work.
   • Apply when the user asks for README work directly.
   • Assume it applies when changes touch AGENTS.md, AGENTS.repo.md, dot_codex/, dot_agents/, plans/, setup flows, documented commands, or repo positioning.
   • Resolve skill metadata from repo-local dot_agents/skills/readme-recruiter-sync, then repo-local .agents/skills/readme-recruiter-sync, then $HOME/.agents/skills/readme-recruiter-sync (or READMERECRUITERSYNC_SKILL_DIR when explicitly set).
2. Ground every README claim in repo evidence.
   • Read the relevant config, skills, scripts, docs, and existing README sections.
   • Prefer tracked files over memory.
3. Audit the front-of-file hierarchy before checking coverage.
   • Default to a recruiter-first structure unless the user explicitly asks for a different order.
   • Require a substantive opening hook: at least two sentences (or short paragraph), and at least ~35 words.
   • The opening must explicitly answer: What is this repo, who benefits, and why it matters.
   • Recruiter-facing value should be consolidated near the top and not repeatedly scattered across distant sections.
   • Surface proof early: the opening hook plus Tech Stack And Why Chosen should appear before setup-heavy sections.
   • Move Quick Start, How to run, dense command blocks, and other setup-heavy content later by default.
   • If the README has top-level Quick Start, Install, Setup, How to run, or a major fenced code block before both
     • the opening recruiter-facing hook/section, and
     • Tech Stack And Why Chosen, the README is stale unless operator-first ordering was explicitly requested.
   • Treat these as stale even if technically correct:
     • generic one-line intros
     • recruiter-facing value duplicated in multiple distant sections
     • stack rationale buried below setup blocks
     • a feature/browse section used as the opening hook substitute
4. Check required coverage from references/readme-contract.md.
   • install/bootstrap
   • day-to-day use
   • core command flags or options for README-documented entrypoints
   • repo-based tech stack and rationale
   • recruiter-facing value consolidated into the opening hook
5. Verify commands and flags before documenting them.
   • Use local --help, usage output, or script source.
   • If a command has no meaningful flags to explain, state that directly in the README.
6. Keep the tech stack section grounded in the repo.
   • Center it on repo-evidenced layers: chezmoi, Codex CLI/config, AGENTS chain, local skills, Graphiti MCP/Neo4j, terminal tooling, and Python/Bash automation.
   • Pair each layer with one concise "why chosen" rationale.
7. Choose the final outcome state:
   • pass_no_change: no issues.
   • update_in_same_change: any fixable README issue is present.
   • blocked: README contract cannot be applied safely in this same change scope.

Default Order

Prefer this order unless the user explicitly asks for another order:

1. Title plus longer opening hook
2. Tech Stack And Why Chosen
3. Optional architecture/implementation snapshot
4. Install, bootstrap, day-to-day commands, and deeper operator docs

Commit Flow Rules

• Treat this skill as a hard gate for commit and push workflows in this repo.
• Never waive the gate because the diff is small.
• Never fabricate recruiter copy, installation steps, tech-stack claims, or CLI flags.
• If README.md is already dirty for unrelated reasons and this scope needs README edits, call out the conflict and stop instead of guessing merge order.

Output Contract

When the state is not pass_no_change, list each issue as:

• coverage or hierarchy
• the specific stale section/claim
• line/evidence evidence that triggered the mismatch