Document the contributor workflow: repo topology + engine vendoring

Open
  • Is something wrong?
#17 1 comment 0 reactions 0 assignees View on GitHub

@jimcadden is already working on this.

Since Nov 5, 2026.

  • #19 by @jimcadden — open

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
shell
Domain
documentation

Research direction

Start with the README and CLAUDE.md sections named in the issue, then inspect scripts/vendor-engine.sh and _vendor.json to confirm the vendoring command and provenance. Document the three repositories' source-of-truth roles and the rules for generated and stale copies in both files. Done when both contributor guides include the requested guidance; pull request #19 is already open for this issue.

Written by the indexing model from the issue text.

Description

Problem

The vendoring workflow is well-designed but undocumented for contributors:

  • The README (pre-## Development) says only that the engine is "vendored from rossoctl/automation" — it never names scripts/vendor-engine.sh, never shows the invocation, and never states the source-of-truth rules across the three repos (automation = engine, agent-skills = canonical SKILL.md, repoman = distribution).
  • CLAUDE.md covers DCO/attribution policy only — nothing about repo topology or vendored code, so an LLM agent contributing to this repo gets no orientation.
  • Nothing marks skills/repoman/scripts/ as generated output. The only provenance hint is _vendor.json, which is easy to overlook.

Risk

A contributor (especially an LLM agent) asked to fix an engine bug while working in this repo will plausibly edit the vendored scripts in place. That fix bypasses automation's tests and is silently overwritten on the next vendor. The committed parity guard (#6) would catch the drift, but it doesn't exist yet.

Proposed fix

  • Add a ## Development section to the README: the three-repo source-of-truth map and the vendoring command (scripts/vendor-engine.sh --source <automation> --dest skills/repoman/scripts), with an explicit "never edit skills/repoman/scripts/ directly" rule.
  • Add a "Repo Topology & Vendored Code" section to CLAUDE.md with the same rules, phrased for LLM contributors: where engine changes belong, that vendored scripts are generated output, that SKILL.md changes should be ported to agent-skills, and that the per-program skills/<program>/scripts/ copies are known-stale (#5) and not authoritative.

Related

  • #5 — standalone skill resync onto the modular engine (the known-stale copies referenced above)
  • #6 — committed parity guard (enforcement complement to this documentation)
  • Design context: rossoctl/automation docs/specs/2026-10-22-repoman-v010-release-packaging-design.md (epic rossoctl/automation#72)

Assisted-By: Claude Code

Dominant language
Shell
Stars
7
Forks
1
Avg merge
5d 10h
Merged PRs (30d)
2

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from rossoctl/repoman

All issues in rossoctl/repoman

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.