forge-setup

name	forge-setup
description	Harness adaptation runbook — clone the repo, find harness-specific references, patch them for the running harness. User-invoked only.
source	https://raw.githubusercontent.com/weselben/RooForge/main/skills/forge-setup/SKILL.md
disableModelInvocation	true

Forge Setup

The skills in this repo are authored against Kimi Code CLI. Most are pure prompt contracts and run anywhere — but a handful reference harness-specific machinery: kimi -p non-interactive loops, the CreateGoal tool, plan mode, and the AgentSwarm/Agent subagent API. On a different harness (Claude Code, Codex, Gemini CLI, opencode, …) those references are dead.

This skill is the discovery + adaptation + bootstrap procedure: it clones the repo to a temp directory, makes the agent find every non-agnostic surface itself, research its own harness's equivalent, patch the references with minimal changes, and optionally install the adapted skills into the harness's skill directory. It does not ship a per-harness mapping table — harnesses change faster than any table stays true. The agent running on the target harness is the best researcher for that harness.

When to run

• First session on any harness that is not Kimi Code CLI.
• After upgrading the harness, when a skill's referenced tool/flag no longer exists.
• When loops, pr-review, pr-resolve, forge-flow, dispatching-parallel-agents, or subagent-driven-development reference tooling the current session does not have.

Step 0 — Clone the repo to a temp directory

Before any discovery, clone this repo to a throwaway workspace so patches don't touch the original (or the harness's skill directory until verified):

REPO_URL="https://github.com/weselben/RooForge"
WORKDIR="/tmp/rooforge-$(date +%s)"
git clone "$REPO_URL" "$WORKDIR"
cd "$WORKDIR"

Done when: the repo is cloned to $WORKDIR and you are inside it. All subsequent steps run from $WORKDIR.

Step 1 — Identify the harness

Try to identify what is running you, in order:

1. Own tool surface — which tools exist this session? (AgentSwarm, CreateGoal, EnterPlanMode, a Skill tool, a Task tool, …)
2. Environment — CLI binary on PATH (which kimi claude codex gemini opencode), harness config dirs (~/.kimi-code, ~/.claude, ~/.codex, …), env vars.
3. Ask the user. If neither identifies it, ask: "Which harness/CLI is running this session?" Do not guess and patch blind.

Done when: the harness name and its CLI binary (if any) are known.

Step 2 — Discover non-agnostic surfaces

Scan the cloned repo for harness-specific references. This exact inventory, run from $WORKDIR:

grep -rn -E 'kimi -p|kimi\b|CreateGoal|EnterPlanMode|ExitPlanMode|plan mode|AgentSwarm|subagent_type|Agent\(resume|run_in_background' skills/ --include='*.md' --include='*.sh'

Known surfaces today (verify against the grep — the grep is the truth, this list is the orientation):

Surface	Where	Kimi form	What it needs
Non-interactive CLI loop	loops/scripts/run_loop.sh, loops/SKILL.md, pr-review, pr-resolve (scripts + templates)	kimi -p "<prompt>"	The harness CLI's headless one-shot-prompt flag that prints the reply to stdout
Goal / contract persistence	forge-flow/SKILL.md	CreateGoal tool	A long-living goal/contract mechanism, or a file fallback
Plan mode with approval gate	forge/SKILL.md, planning-and-task-breakdown/SKILL.md, pr-review/pr-resolve templates	EnterPlanMode / plan file / user approval	The harness's plan-mode equivalent, or a file-based plan contract
Parallel subagent dispatch	dispatching-parallel-agents/SKILL.md, subagent-driven-development/SKILL.md (+ prompt templates), planning-and-task-breakdown/SKILL.md	AgentSwarm with {{item}} template, subagent_type: coder/explore/plan, Agent(resume=…), run_in_background	The harness's subagent/parallel-task API: batch dispatch, agent roles, resume, background runs
Skill loading	AGENTS.md, several SKILL.md "load X" instructions	Skills read as plain files from skills/	Nothing — file reads are harness-agnostic. Only patch if the harness has a native skills dir the repo should be symlinked/copied into

Step 3 — Research the harness's equivalents

For each surface found in step 2, research how this harness does it:

1. Own documentation first — the harness's docs dir, --help output (<cli> --help), built-in skill/command listings, config schema.
2. Web second — search for the harness's headless/non-interactive mode, subagent API, and plan/goal features. Prefer official docs.
3. Record each mapping before patching: kimi -p "…" → e.g. claude -p "…", CreateGoal → e.g. a GOAL.md contract file, AgentSwarm → e.g. parallel Task calls.

If the harness has no equivalent for a surface, fall back to the simplest file-based convention and say so in the patch:

• No goal API → GOAL.md at repo root, re-read at every session start (forge-flow already treats the goal as a re-injected contract; a file satisfies that).
• No plan mode → write the plan file and stop for user approval in plain chat.
• No subagent API → run the swarm sequentially; keep the prompt templates unchanged.

Step 4 — Patch the cloned repo with minimal diffs

Premade example replace commands — adapt the replacement side to whatever step 3 found. Run from $WORKDIR. Each is deliberately narrow; never rewrite skill logic, only the harness reference.

# 1. Non-interactive loop engine — replace the CLI + flag (example: claude -p)
grep -rl 'kimi -p' skills/ | xargs sed -i 's/kimi -p/claude -p/g'
grep -rl '\bkimi\b' skills/ --include='*.sh' | xargs sed -i 's/\bkimi\b/claude/g'

# 2. Goal tool — replace with the harness's goal mechanism or the file fallback
grep -rl 'CreateGoal' skills/ | xargs sed -i 's/CreateGoal/GOAL.md contract file/g'

# 3. Plan mode naming — match the harness's own terms, keep the approval gate intact
grep -rl 'EnterPlanMode\|ExitPlanMode' skills/ | xargs sed -i 's/EnterPlanMode/plan mode/g; s/ExitPlanMode/exit plan mode/g'

# 4. Subagent dispatch — rename the API, keep {{item}} template mechanics and role mandates
grep -rl 'AgentSwarm' skills/ | xargs sed -i 's/AgentSwarm/parallel Task dispatch/g'

Patch rules:

• Minimal changes. One reference swapped for its equivalent. No reformatting, no rewording of surrounding prose, no "while I'm here" cleanups.
• Contracts stay. DONE:/BLOCKED: in run_loop.sh, the role-mandate blocks, the MANDATORY FIRST loads, and the plan-approval gate are behavior, not harness references — never touch them.
• Scripts must still parse. After patching a .sh, run bash -n on it.
• Same-scope commits. Per repo convention, conventional commits with the skill name as scope. A harness adaptation spans several skills — use chore(forge-setup): adapt skills to <harness> as one commit.

Step 5 — Verify the adapted clone

1. Re-run the step-2 grep from $WORKDIR. Expected: zero hits for the old harness's terms outside forge-setup itself (this file documents the Kimi forms on purpose — leave it).
2. Syntax-check every patched script: find skills/ -name '*.sh' -exec bash -n {} \;.
3. Smoke-test the loop engine if the harness CLI exists: one run_loop.sh call with a trivial prompt template that answers DONE: ok on iteration 1.
4. Report the mapping table (old → new, per surface) to the user.

Step 6 — Prepare identity for commit authorship

Before installing skills, the user must set their git identity. If the user wants the adapted use-git-identity skill to reflect their own identity (not the RooForge default), prompt:

The adapted use-git-identity skill currently sets:
  user.name = "weselben/rooforge"
  user.email = "[e-mail]"

Enter your desired git name (or press Enter to keep "weselben/rooforge"):
Enter your desired git email (or press Enter to keep "[e-mail]"):

Update $WORKDIR/skills/use-git-identity/SKILL.md with the provided values before proceeding. This ensures commits made by the adapted skills carry the user's identity.

Step 7 — Install adapted skills into the harness skill directory (optional)

If verification passes, offer to copy the adapted skills into the harness's skill directory so future sessions load them natively.

First, delete any existing RooForge skills in the harness directory to ensure a clean update on re-run:

# Determine the harness skill directory (prefer user's config dir)
HARNESS_SKILLS_DIR=""
if [ -d "$HOME/.claude/skills" ]; then
  HARNESS_SKILLS_DIR="$HOME/.claude/skills"
elif [ -d "$HOME/.codex/skills" ]; then
  HARNESS_SKILLS_DIR="$HOME/.codex/skills"
elif [ -d "$HOME/.kimi-code/skills" ]; then
  HARNESS_SKILLS_DIR="$HOME/.kimi-code/skills"
elif [ -d "$HOME/.opencode/skills" ]; then
  HARNESS_SKILLS_DIR="$HOME/.opencode/skills"
else
  HARNESS_SKILLS_DIR="$HOME/.agents/skills"
fi

mkdir -p "$HARNESS_SKILLS_DIR"

# Remove existing RooForge skill directories (clean update)
for skill in $(ls "$WORKDIR/skills/"); do
  [ -d "$HARNESS_SKILLS_DIR/$skill" ] && rm -rf "$HARNESS_SKILLS_DIR/$skill"
done

# Copy adapted skills one-by-one (exclude forge-setup — it documents the Kimi baseline)
for skill  $( ); 
  [  =  ] && 
   -r  

 

Ask the user before copying. If they decline, the adapted clone remains at $WORKDIR for manual inspection.

Rules

• Discovery over assumption. The grep inventory in step 2 is re-run every time — never patch from a memorized list.
• Ask when unknown. Harness unidentified → ask the user. Equivalent not found after research → ask the user before inventing a fallback.
• Minimal diffs. Reference swap only. Anything beyond that is a separate change.
• forge-setup is exempt from its own patches. This file names the Kimi forms as the reference baseline; step 5's grep excludes it deliberately.
• Work on the clone. Steps 2–5 run on $WORKDIR, not the original repo or the harness skill directory. Only step 7 copies out.

Boundaries

Forge Setup does not:

• Install the harness CLI or change harness config
• Rewrite skill behavior, contracts, or prompt templates beyond the harness reference
• Run forge-init (repo bootstrap) or forge-flow (session bootstrap) — those come after, using the adapted skills
• Commit anything without the user's go-ahead
• Modify the original GitHub repo (works on a local clone only)