Skip to content

feat(skills): vendor the outsource skill (explore/review/write)#14

Open
OriNachum wants to merge 1 commit into
mainfrom
feat/vendor-outsource-skill
Open

feat(skills): vendor the outsource skill (explore/review/write)#14
OriNachum wants to merge 1 commit into
mainfrom
feat/vendor-outsource-skill

Conversation

@OriNachum
Copy link
Copy Markdown
Contributor

Summary

  • Vendors the canonical outsource skill from guildmaster (cite-don't-import pattern)
  • Adds outsource review | explore | write — hand a scoped task to convertible (a different engine/mind) and fold its answer back; diversity catches what the author's mind glides past
  • Read-only verbs (explore, review) run in an isolated throwaway git worktree and cannot touch the working tree
  • Patch bump (0.12.0 → 0.12.1) per the version-check CI rule

Test plan

  • Confirm .claude/skills/outsource/SKILL.md frontmatter name: outsource matches directory name
  • Confirm scripts/outsource.sh is executable and resolves convertible from PATH
  • Run outsource explore against a small scope to verify the worktree isolation
  • CI green (version-check, tests, SonarCloud quality gate)

🤖 Generated with Claude Code

  • guildmaster (Claude)

Cite-don't-import copy of the canonical outsource skill from guildmaster:
hand a scoped repo task to convertible (a *different* engine/mind) for a
diverse second opinion — outsource review|explore|write. Portable wrapper;
resolves the convertible CLI from PATH. Patch bump per version-check rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@qodo-code-review
Copy link
Copy Markdown

Review Summary by Qodo

Vendor outsource skill for diverse second opinions via convertible

✨ Enhancement

Grey Divider

Walkthroughs

Description
• Vendors the canonical outsource skill from guildmaster with three verbs
• explore and review run read-only in isolated git worktrees at HEAD
• write implements changes on a drive branch or opens a PR with --pr
• Portable wrapper resolves convertible CLI from PATH or local dev fallback
• Patch version bump (0.2.0 → 0.2.1) per version-check CI rule
Diagram
flowchart LR
  User["User invokes outsource verb"] -->|explore/review| ReadOnly["Read-only in throwaway worktree"]
  User -->|write| InPlace["In-place drive branch or PR"]
  ReadOnly --> Convertible["convertible drive CLI"]
  InPlace --> Convertible
  Convertible --> Result["TaskResult summary printed"]

Loading

Grey Divider

File Changes

1. .claude/skills/outsource/scripts/outsource.sh ✨ Enhancement +259/-0

Portable outsource CLI wrapper for convertible integration

• Main entry point script (259 lines) implementing the outsource command wrapper
• Resolves convertible CLI portably from PATH or local dev fallback with uv
• Implements three verbs: explore (read-only investigation), review (second opinion on diff),
 write (in-place implementation)
• Read-only verbs use throwaway git worktree at HEAD to prevent side effects
• Comprehensive flag parsing for repo, base branch, engine, model, base-url, max-steps, timeout, and
 PR options

.claude/skills/outsource/scripts/outsource.sh


2. .claude/skills/outsource/SKILL.md 📝 Documentation +104/-0

Skill documentation and usage guide for outsource

• Skill metadata and documentation (104 lines) with frontmatter name, type, and description
• Explains the three verbs and their use cases with emphasis on diversity over strength
• Documents all command-line options and environment variable overrides
• Specifies hard rules: read-only enforcement, dirty-tree guard, and output as second opinion
• Lists honest limits: worktree isolation + prompt constraint, committed-only review, single-model
 default

.claude/skills/outsource/SKILL.md


3. .claude/skills/outsource/prompts/explore.md 📝 Documentation +20/-0

Prompt template for explore verb

• Prompt template (20 lines) for read-only investigation verb
• Instructs model to investigate and report findings with file:line citations
• Enforces read-only constraint and efficient step usage
• Requests structured findings report with context, edge cases, and open questions

.claude/skills/outsource/prompts/explore.md


View more (4)
4. .claude/skills/outsource/prompts/review.md 📝 Documentation +27/-0

Prompt template for review verb

• Prompt template (27 lines) for independent review verb
• Instructs model to review committed diff ($BASE...HEAD) with candid second opinion
• Enforces read-only constraint and prioritized, terse output
• Requests structured review with correctness risks, design concerns, and actionable suggestions

.claude/skills/outsource/prompts/review.md


5. .claude/skills/outsource/prompts/write.md 📝 Documentation +13/-0

Prompt template for write verb

• Prompt template (13 lines) for write verb implementation
• Instructs model to make minimal, scoped changes following repository patterns
• Emphasizes reading neighboring files and not widening scope
• Requests summary of changes and rationale

.claude/skills/outsource/prompts/write.md


6. CHANGELOG.md 📝 Documentation +6/-0

Changelog entry for version 0.2.1

• Adds new section for version 0.2.1 dated 2026-05-31
• Documents addition of vendored outsource skill from guildmaster

CHANGELOG.md


7. pyproject.toml ⚙️ Configuration changes +1/-1

Version bump to 0.2.1

• Bumps version from 0.2.0 to 0.2.1

pyproject.toml


Grey Divider

Qodo Logo

@qodo-code-review
Copy link
Copy Markdown

qodo-code-review Bot commented May 31, 2026

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (1)

Context used
✅ Compliance rules (platform): 22 rules

Grey Divider


Action required

1. Missing outsource entry in docs 📘 Rule violation § Compliance
Description
A new vendored skill outsource was added under .claude/skills/outsource/, but
docs/skill-sources.md has no corresponding provenance/divergence entry even though the skill’s
SKILL.md claims it is tracked there. This breaks the required audit trail/provenance map for
vendored skills and will cause drift, confusion, and harder future re-vendoring and
license/provenance reviews.
Code

.claude/skills/outsource/SKILL.md[R98-103]

Evidence
The PR introduces the new .claude/skills/outsource/ skill, and its SKILL.md explicitly states
that the skill is tracked in docs/skill-sources.md. However, the provenance tables in
docs/skill-sources.md list multiple skills under the canonical and inbound workflow sections and
do not include any entry for outsource, showing the provenance/divergence registry was not updated
alongside this vendoring and violating the requirement that each added/modified vendored skill be
documented with its source and divergence notes.

Rule 630217: Document provenance and divergence of vendored skills
.claude/skills/outsource/SKILL.md[98-103]
docs/skill-sources.md[20-32]
.claude/skills/outsource/SKILL.md[98-104]
docs/skill-sources.md[20-44]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR vendors a new skill at `.claude/skills/outsource/` but does not add/update the required provenance/divergence documentation in `docs/skill-sources.md`, despite `SKILL.md` stating it is tracked there.

## Issue Context
`docs/skill-sources.md` is the required upstream/downstream map (vendoring provenance registry) for vendored skills and is used to guide future re-syncs/re-vendoring. The newly added `outsource` skill must be recorded with its source (guildmaster re-vendor / true origin), acquisition date/commit/tag if known, and divergence notes (even if “verbatim”); alternatively, if the intent is not to track it there, the claim in `SKILL.md` should be removed/adjusted to avoid misinformation.

## Fix Focus Areas
- .claude/skills/outsource/SKILL.md[98-104]
- docs/skill-sources.md[20-44]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

2. Prompt text gets rewritten 🐞 Bug ≡ Correctness
Description
render_prompt() replaces $ARGUMENTS first and then $BASE, so any literal $BASE appearing in
the user-supplied argument string will be rewritten to the base branch name, corrupting the
instruction sent to convertible drive. This can change task semantics for all verbs
(explore/review/write).
Code

.claude/skills/outsource/scripts/outsource.sh[R160-164]

Evidence
The renderer injects user text via $ARGUMENTS and then performs a $BASE replacement on the whole
string, which will also affect the already-injected user text. The review prompt demonstrates
$BASE is a real template token used by the system.

.claude/skills/outsource/scripts/outsource.sh[157-165]
.claude/skills/outsource/prompts/review.md[6-13]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`render_prompt()` performs sequential string replacements in a way that can mutate user-provided text: `$ARGUMENTS` is injected first, then `$BASE` is replaced, which will also replace `$BASE` inside the injected `$ARGUMENTS` text.

### Issue Context
The prompt templates legitimately contain `$BASE` (e.g. review prompt), but user input should never be subject to template-token substitution.

### Fix Focus Areas
- .claude/skills/outsource/scripts/outsource.sh[157-165]
- .claude/skills/outsource/prompts/review.md[6-13]

### Expected fix
Replace `$BASE` in the template **before** injecting `$ARGUMENTS` (or use a safer templating approach / unique delimiters) so `$BASE` occurrences in user text remain untouched.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. Allow-dirty skips git check 🐞 Bug ☼ Reliability
Description
For write, when --allow-dirty is set, the only git invocation (git status) is skipped, and
there is no explicit git rev-parse validation, so a non-git --repo can proceed into `convertible
drive. This makes outsource write --allow-dirty --repo <non-git-dir>` behave inconsistently with
explore/review and can fail mid-drive or operate on an unintended directory.
Code

.claude/skills/outsource/scripts/outsource.sh[R238-251]

Evidence
--allow-dirty sets ALLOW_DIRTY=1, which causes the guarded git status check to be skipped in
run_write(). Unlike run_readonly(), run_write() has no unconditional git rev-parse check
before invoking convertible drive.

.claude/skills/outsource/scripts/outsource.sh[127-137]
.claude/skills/outsource/scripts/outsource.sh[218-222]
.claude/skills/outsource/scripts/outsource.sh[238-251]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`run_write()` relies on the dirty-tree check (which calls `git status`) as an implicit git-repo validation. When `--allow-dirty` is passed, that check is bypassed and `run_write()` performs no git-repo validation before calling `convertible drive`.

### Issue Context
`run_readonly()` explicitly validates `--repo` is a git repository via `git rev-parse --is-inside-work-tree`, but `run_write()` does not.

### Fix Focus Areas
- .claude/skills/outsource/scripts/outsource.sh[218-222]
- .claude/skills/outsource/scripts/outsource.sh[238-251]
- .claude/skills/outsource/scripts/outsource.sh[127-137]

### Expected fix
Add the same `git rev-parse --is-inside-work-tree` check to `run_write()` (or right after `REPO` normalization) so it runs regardless of `ALLOW_DIRTY` and fails fast with a clear error if `--repo` is not a git repo.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Qodo Logo

@sonarqubecloud
Copy link
Copy Markdown

Comment on lines +98 to +103
## Provenance

This is a **first-party convertible** skill — `agentculture/convertible` is its
origin. guildmaster **re-broadcasts** it to the mesh (the same inbound pattern as
the devague-origin workflow skills), tracking it in `docs/skill-sources.md`. The
`cite, don't import` policy holds: downstream repos copy it, they don't symlink
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Missing outsource entry in docs 📘 Rule violation § Compliance

A new vendored skill outsource was added under .claude/skills/outsource/, but
docs/skill-sources.md has no corresponding provenance/divergence entry even though the skill’s
SKILL.md claims it is tracked there. This breaks the required audit trail/provenance map for
vendored skills and will cause drift, confusion, and harder future re-vendoring and
license/provenance reviews.
Agent Prompt
## Issue description
The PR vendors a new skill at `.claude/skills/outsource/` but does not add/update the required provenance/divergence documentation in `docs/skill-sources.md`, despite `SKILL.md` stating it is tracked there.

## Issue Context
`docs/skill-sources.md` is the required upstream/downstream map (vendoring provenance registry) for vendored skills and is used to guide future re-syncs/re-vendoring. The newly added `outsource` skill must be recorded with its source (guildmaster re-vendor / true origin), acquisition date/commit/tag if known, and divergence notes (even if “verbatim”); alternatively, if the intent is not to track it there, the claim in `SKILL.md` should be removed/adjusted to avoid misinformation.

## Fix Focus Areas
- .claude/skills/outsource/SKILL.md[98-104]
- docs/skill-sources.md[20-44]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant